内容
# Glyph Grid Studio
一款适用于 macOS 的实时字符网格图像渲染器。 将任意图像拖入并转换为可调的 Unicode 字符马赛克 — ASCII、块元素、八分之一、六分之一、盲文 — 具有实时的 OKLab 调色板插值、时空蓝噪声抖动和 Lottes 风格的 CRT 光束后处理。
[](https://github.com/Joona-t/glyph-grid-studio/releases/latest)
[](LICENSE)
**免费 · 开源 · macOS 11+ (Intel + Apple Silicon)**
🌐 **网站与下载：** https://lovespark.love/glyph-grid-studio/
## 下载
1. **[下载最新版本](https://github.com/Joona-t/glyph-grid-studio/releases/latest)** (`.dmg`)，打开它，将 **Glyph Grid Studio** 拖入 **Applications**。
2. **首次启动（仅一次）。** 该应用程序免费且开源，但未使用付费 Apple Developer 证书签名，因此 macOS 会阻止首次打开。 要允许：
- **右键单击**（或 Control-click）应用程序 → **打开** → **再次打开** 对话框，**或**
- **系统设置 → 隐私和安全** → 向下滚动 → **"仍然打开"**，**或** 运行：
```bash
xattr -dr com.apple.quarantine "/Applications/Glyph Grid Studio.app"
```
**系统要求：** macOS 11（Big Sur）或更高版本。 通用二进制文件 — 在 Apple Silicon 和 Intel Mac 上均可原生运行。
如果您更喜欢自己构建？ 请参见下面的 [从源代码构建](#build)。
## 功能
| 轴 | 选项 |
|---|---|
| 调色板（11） | 单色，磷光，包豪斯，lovespark，单色琥珀色，赛博磷光，琥珀磷光，骨炭，奶油纸，银炭，香料 |
| 色彩模式（4） | 保留，单色，双色，渐变 |
| 斜坡（9） | 经典，密集，稀疏，unicode 块，渐变，gradientNoSpace，块阴影，块升序，径向 |
| 抖动（9） | 无，bayer4，bayer8，蓝噪声，**STBN** （NVIDIA EGSR 2022），时间，floydSteinberg，atkinson，jarvisJudiceNinke |
| 选择（4） | 亮度，形状，形状边缘感知，边缘方向 |
| 字符集（7） | ASCII，asciiDense，块元素，盲文，六分之一，八分之一，斜坡のみ |
| 后处理（8） | 晕影，辉光，halation，扫描线，色差，磷光衰减，深度雾，**CRT 光束** （Lottes / Blur Busters 2024） |
| 动画 | 呼吸单元 EMA，每帧增益脉冲，每单元抖动 — 运行时可调 |
| 导出 | PNG 快照 · 动画 GIF89a · MP4 (H.264) · 预设 JSON · 分享网址 |
## 算法说明
- **6-D 形状向量匹配** （Alex Harri 2024）：每个字符都编码为 6 个浮点数，描述局部质量分布；每个单元格查找通过 k-d 树选择最接近的匹配。 匹配 CNN 质量，成本约为 1% （Chen et al. arXiv 2503.14375，2025）。
- **STBN 抖动**：Halton(2,3) 驱动的 NVIDIA 时空蓝噪声近似。 比哈希抖动的 Bayer 更平滑的每帧变化，无需运输 50 KB 纹理资产。
- **OKLCH 调色板插值**：沿较短色调弧的圆柱 OKLab 插值，因此跨远色调的调色板过渡保持饱和，而不是通过灰色降低。
- **原生 GIF/MP4 编码**：帧从 JS 画布通过 base64 IPC 直接传递到 Rust。 GIF 通过 `gifski` （质量 100 的调色板编码；Twitter 适配路径在 600→540→480→420→360 像素下重试，直到输出符合 15 MB 限制）。 MP4 通过 `openh264` 和 `mp4` muxer 实现 Instagram 兼容的循环。
## 使用方法
### 作为人类 — 视觉工作室（GUI 模式）
将图像拖入窗口，滑动滑块，观察画布实时更新，点击导出 GIF。 默认行为是在无参数启动时。
### 作为代理/脚本 — 无头 CLI
相同的渲染管道，无 GUI。 在离屏 Tauri 窗口中运行，GIF 写入后退出。
```bash
# 单个渲染，显式标志
glyph-grid-studio render \
--in ~/Downloads/portrait.jpg \
--out ~/portrait-warm-bone.gif \
--palette cream-paper \
--color-mode monochrome \
--ramp gradient \
--dither stbn \
--selection-mode shape-edge-aware \
--glyph-set octant \
--frames 24
# 列出所有可用的调色板/斜坡/抖动/字符集
glyph-grid-studio catalog | jq
# 批量：渲染一个或多个源的 N 个变体，**在单个应用程序会话中** （~10 倍于每次渲染调用 — 启动 + 解码一次付费）。
# 清单形状：{"in": "<默认源>"， "frames": N， "perf": false，
# "jobs": [{"name", "out", "format": "gif|mp4", "in": "<每个作业的源>"，
# "capWidth": 720, "targetMaxBytes": 15728640, "config": {...}}]}
# capWidth 720 自动定位 Twitter 的 15 MB 限制（自适应缩减梯度）。
glyph-grid-studio batch --manifest variants.json
# 帮助
glyph-grid-studio render --help
glyph-grid-studio batch --help
```
### 作为 Claude / Cursor 工具 — MCP 服务器
将其连接到任何 MCP 感知 AI 客户端，渲染器成为原生工具。 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"glyph-grid-studio": {
"command": "/Applications/Glyph Grid Studio.app/Contents/MacOS/glyph-grid-studio",
"args": ["mcp"]
}
}
}
```
重启 Claude Desktop。 然后在任何聊天中：
> *"将 ~/Pictures/sunset.jpg 中的图像渲染为奶油纸单色字符绘图，使用形状边缘感知八分之一选择。 将其保存在原始文件旁边。"*
公开工具：`glyph_grid_render`，`glyph_grid_catalog`。 完整的设置 + 代理探索示例见 [docs/mcp.md](docs/mcp.md)。
## 构建
```bash
# 需求：Rust 1.77+，Cargo，Xcode CLI 工具
cd src-tauri
cargo tauri build # ~40 秒增量，~3 分钟冷启动
# 输出：src-tauri/target/release/bundle/macos/Glyph Grid Studio.app
```
要安装：
```bash
ditto "src-tauri/target/release/bundle/macos/Glyph Grid Studio.app" \
"$HOME/Applications/Glyph Grid Studio.app"
xattr -cr "$HOME/Applications/Glyph Grid Studio.app"
open "$HOME/Applications/Glyph Grid Studio.app"
```
无头二进制文件位于 `Glyph Grid Studio.app/Contents/MacOS/glyph-grid-studio`。 v0.2 之后的 Homebrew 软件包将位于 `$PATH` 中，作为 `glyph-grid-studio`。
## 项目布局
```
src/
index.html 单文件 p5 草图（CONFIG、场景、绘图循环、测试钩子）
lib/
glyph-fonts.js WOFF2 级联 + 存在性检测
glyph-dither.js 有序 + 误差扩散 + STBN 抖动
glyph-palette-morph.js OKLab/OKLCH 插值
glyph-shape-index.js 6-D 向量 + k-d 树最近邻选择
glyph-crt.js 后处理链（渐晕 → CRT 光束）
glyph-studio.js Tweakpane 绑定 + 拖放 + 记录 + 导出
...
glyph-sets/ 预烘焙的图集 JSON（ASCII、八分之一、六分之一、盲文...）
fonts/ 捆绑的 WOFF2（Cascadia + IBM VGA 回退）
src-tauri/
src/lib.rs Tauri 命令：save_png、save_gif_real、save_gif_to_path、
pick_image、read_image_file、save_preset_json、load_preset_json
Cargo.toml tauri 2.10，gif 0.13，image 0.25
tauri.conf.json 窗口 1500×820，dragDropEnabled，withGlobalTauri，devtools
capabilities/ core:default, dialog, fs
```
## 测试会话
在开发过程中运行了一个 469-GIF 笛卡尔特征测试，以验证每条代码路径都能正确渲染。 有关错误日志和总结，请参见 `BUGS_AND_ITERATIONS.md`。 测试驱动函数（`runStudioPhase(N)` / `runAllStudioPhases()`）仍然可用于回归测试。
## 许可证
[MIT](LICENSE) — Joona Tyrninoksa, 2026
