petipoua/petiglyph

# petiglyph `petiglyph` 是一个 TUI 和 CLI 工具，用于将图像和视频转换为自定义字体字形（glyphs）。 已在内部实现终端中的“太空狼跳电臀舞（twerking amogus）” 😎 ### 视频教程： [](https://raw.githubusercontent.com/petipoua/petiglyph/main/readme-assets/petiglyph-demo.mp4) ## 快速入门 ### 1. 安装 选择其中一种方式： ``` npm install -g petiglyph ``` ``` pip install petiglyph ``` ``` yay -S petiglyph ``` 你也可以从 GitHub Releases 下载预编译的二进制文件。 请确保 `ffmpeg` 已添加到 `PATH` 中。 ### 2. 用法 在终端中，进入你希望创建项目的文件夹，然后输入： ``` petiglyph ``` 这会打开 TUI 主面板，你可以在其中创建项目并开始导入媒体，以生成字形、网格和动画。 支持的媒体： - 图像：`png`、`jpg`、`jpeg`、`webp`、`bmp`、`gif`、`svg`、`avif` - 动画媒体：`gif`、`mp4`、`mov`、`mkv`、`webm`、`avi`、`m4v` 生成的字形可以是 4 种类型： - 标准等宽，静态 - 标准等宽，动画 - 字形网格，静态 - 字形网格，动画 对于所有这 4 种类型，petiglyph 将在安装字体后，在主面板的 `Installed petiglyph fonts`（已安装的 petiglyph 字体）区域生成静态和动画字形。 要复制这些字形以便在其他地方复用，你需要使用方向键导航到 `Installed petiglyph fonts` 区域，选择你想要的字形，按 ENTER 键将其复制到剪贴板，然后粘贴到你自己的工具或应用中（这些应用也需要加载新字体，请参阅上面的警告）。 在动画字形上按 ENTER 键会将所有帧复制到剪贴板。要看到它们的动画效果，你需要编写自己的脚本来将所有字形渲染为动画。
## 文档 ### 项目模型与发现 每个项目都是自包含的： ``` my-font/ petiglyph.toml images/ build/ petiglyph.lock ``` `petiglyph.toml` 存储配置，`images/` 存储项目本地源和 导入的帧，`build/` 存储生成的产物，以及 `petiglyph.lock` 在首次构建后保留字形到码点（codepoint）的分配关系。 使用以下命令创建项目： ``` petiglyph new-project my-font ``` 如果没有子命令，`petiglyph` 将打开工作区 TUI。项目发现 会搜索当前目录及深度为 2 的后代目录，并且 不跟随目录符号链接。如果只发现一个项目，则会自动选中。 如果发现多个项目，则会在交互式终端中打开工作区选择器； 而自动化命令则会报告其歧义。`use-project` 通过精确的 项目目录基本名称（basename）进行选择，并拒绝具有重复匹配项的候选路径。 ### CLI 参考 | 命令 | 用途及重要选项 | | --- | --- | | `petiglyph` 或 `petiglyph tui` | 打开工作区 TUI。需要交互式终端。 | | `petiglyph new-project ` | 创建 `/petiglyph.toml`、`images/` 和 `build/`。 | | `petiglyph use-project tui` | 在 TUI 中打开选定的一个项目。 | | `petiglyph use-project create glyph ...` | 导入一个或多个静态字形源。 | | `petiglyph use-project create grid-glyph ...` | 导入一个被拆分为 `--rows` 行和 `--cols` 列的源。 | | `petiglyph use-project create animated-glyph ...` | 将 GIF/视频帧作为字形导入；需要 `--fps`。 | | `petiglyph use-project create animated-grid-glyph ...` | 导入拆分为网格的帧；需要 `--fps`、`--rows` 和 `--cols`。 | | `petiglyph use-project configure glyph ...` | 设置或清除源阈值并设置反转。 | | `petiglyph use-project configure grid-glyph ...` | 配置网格尺寸、渗透、阈值和反转。 | | `petiglyph use-project configure animation ...` | 配置 FPS、阈值、反转和仅网格设置。 | | `petiglyph use-project delete animation ` | 移除一个动画定义。 | | `petiglyph use-project build` | 生成项目产物。`--force-remap` 会丢弃先前的码点分配。 | | `petiglyph use-project install-font` | 构建并安装所选项目的托管字体。 | | `petiglyph use-project show-sample` | 打印现有的 `build/glyph-sample.txt`；它不会执行构建。 | | `petiglyph use-project doctor` | 运行全局和所选项目检查；`--repair` 应用支持的修复。 | | `petiglyph list projects` | 列出已发现的项目和清单格式错误的警告。 | | `petiglyph list installed-fonts` | 列出已管理的已安装字体系列及其所有权详细信息。 | | `petiglyph delete-project ...` | 验证整个批次，然后删除项目目录。 | | `petiglyph uninstall-font ...` | 从 `list installed-fonts` 中卸载确切的托管字体系列名称。 | | `petiglyph uninstall-all-fonts` | 移除所有托管 Petiglyph 字体和元数据。 | | `petiglyph doctor` | 运行全局检查和任何可解决的项目检查。 | 全局 `--debug` 启用项目本地的管线诊断。 `--ffmpeg-auto-install` 允许在 缺少 FFmpeg 时运行检测到的包管理器命令。支持自动化的命令接受 `--json`；创建操作也 接受 `--build` 和 `--install`，其中 `--install` 隐含了构建。使用 `petiglyph --help` 获取详尽的标志语法和接受的值。 ### 创建和配置字形 CLI 公开了与 TUI 相同的四种创建类型： ``` # 每个 glyph 一张图片 petiglyph use-project my-font create glyph \ --input logo.png mark.svg # 一个 Sprite Sheet 拆分为 glyph 单元格 petiglyph use-project my-font create grid-glyph \ --input icons.png --rows 4 --cols 4 # GIF/视频帧作为 glyph petiglyph use-project my-font create animated-glyph \ --input spinner.gif --name spinner --fps 8 # 每帧拆分为网格单元格 petiglyph use-project my-font create animated-grid-glyph \ --input dashboard.mp4 --name dashboard --fps 10 \ --rows 2 --cols 4 ``` 一个 `--input` 可接受多个路径。创建操作会导入和配置源， 除非有请求，否则不会进行构建或安装。静态构建输入为 `png`、 `jpg`、`jpeg`、`webp`、`bmp`、`gif` 和 `svg`。`avif` 仅支持导入，并 转换为项目本地的 PNG。动画媒体支持 `gif`、`mp4`、`mov`、 `mkv`、`webm`、`avi` 和 `m4v`。 ``` petiglyph use-project my-font configure glyph logo.png \ --threshold 88 --invert on petiglyph use-project my-font configure glyph logo.png \ --clear-threshold petiglyph use-project my-font configure grid-glyph icons.png \ --rows 2 --cols 8 --horizontal-bleed strong --vertical-bleed off petiglyph use-project my-font configure animation spinner \ --fps 12 --threshold 72 --invert off petiglyph use-project my-font delete animation spinner ``` 网格尺寸和渗透仅对网格源和网格动画有效。 ### 调优参数 图像管线执行可选的灰度导入处理、纵横比适应 缩放、阈值处理、可选反转，然后是可选的网格边缘渗透。 所有预览都通过统一的缩放比例保持源或字形的纵横比； 空白的垂直行可能会在适应之前被裁剪，但预览永远不会 被拉伸以填满多余的宽度或高度。 | 设置 | 范围/默认值 | 效果 | | --- | --- | --- | | `threshold` | `0..=255`，默认为 `64` | 较高的值保留较少的像素；较低的值产生更饱满的形状。可以按源覆盖项目默认值。 | | `invert` | `on` 或 `off`，默认为 `off` | 翻转阈值处理的结果。 | | `grayscale_enabled` | 静态默认关闭；动画默认开启 | 通过灰度色调处理重写导入的光栅像素。SVG 文件不会被重写。 | | `grayscale_brightness` | `-80..=80`，默认为 `0` | 增亮或变暗灰度值。 | | `grayscale_contrast` | `-80..=80`，默认为 `0` | 增加或减少色调分离度。 | | `grayscale_gamma_percent` | `50..=200`，默认为 `100` | 调整中间调；处理顺序依次为伽马、对比度、亮度，然后是阈值。 | | `rows`、`cols` | 两者均大于 `0` | 将完整源适应为网格，然后将其拆分为字形单元格。 | | `horizontal_bleed` | `off`、`weak`、`strong`；默认为 `weak` | 略微扩展跨越内部左/右网格边界的轮廓，以减少接缝。 | | `vertical_bleed` | `off`、`weak`、`strong`；默认为 `off` | 扩展跨越内部上/下边界的轮廓；支持情况取决于渲染器。 | | `fps` | `1..=30` | 存储 Petiglyph 预览/播放时序元数据。TTF 文件包含静态字形且本身不会动画。 | | `glyph_size` | 默认为 `64` | 设置在生成字体轮廓之前使用的光栅工作大小。 | `off` 保持网格边缘裁剪状态，`weak` 增加少量重叠，`strong` 增加 更大的重叠。渗透改变的是最终的轮廓几何形状，而不是阈值处理。 ### 清单参考 正常的读取和构建可能会重写 `petiglyph.toml` 以创建或规范化 托管字段，因此请保持其可写权限。 | 字段 | 类型和默认值 | 含义 | | --- | --- | --- | | `input_dir` | 字符串，`"images"` | 项目相对源目录。 | | `out_dir` | 字符串，`"build"` | 项目相对构建目录。 | | `font_name` | 字符串，`"Petiglyph"` | 生成的字体系列名称。 | | `glyph_size` | 整数，`64` | 光栅工作大小。 | | `threshold` | 整数，`64` | 项目全局阈值。 | | `codepoint_start` | 码点字符串，`"U+100000"` | 项目补充专用区域的首选起始位置。 | | `project_id` | 托管字符串 | 稳定的项目标识。缺失或为空值时将自动生成。 | | `threshold_overrides` | 表，空 | 以相对于 `input_dir` 的路径为键的按源阈值。 | | `invert_overrides` | 表，空 | 以相对于 `input_dir` 的路径为键的按源布尔值。 | | `compositions` | 表，空 | 以源路径为键的静态网格定义。 | | `animations` | 表数组，空 | 标准或网格动画定义。 | 网格组合包含 `rows`、`cols`、`horizontal_bleed` 和 `vertical_bleed`。省略的渗透值将默认规范为水平 `weak` 和 垂直 `off`。 ``` [compositions."icons.png"] rows = 4 cols = 4 horizontal_bleed = "weak" vertical_bleed = "off" [[animations]] name = "spinner" type = "standard" fps = 8 frames = ["spinner-0001.png", "spinner-0002.png"] [[animations]] name = "dashboard" type = "grid" fps = 10 frames = ["dashboard-0001.png", "dashboard-0002.png"] rows = 2 cols = 4 horizontal_bleed = "weak" vertical_bleed = "off" ``` 动画帧路径是相对源键。标准动画不能 定义网格字段。网格动画需要为正数的 `rows` 和 `cols`。 动画条目还可包含 `grayscale_processing`，它记录了 `grayscale_enabled` 以及一个嵌套的 `grayscale` 表（包含 `gamma_percent`、 `contrast` 和 `brightness`）。色调值在读取时会规范化为其支持的 范围。 ### 构建和码点稳定性 ``` petiglyph use-project my-font build petiglyph use-project my-font build --force-remap ``` | 产物 | 位置和用途 | | --- | --- | | TTF | `build/.ttf`：用于应用程序和托管安装的标准字体。 | | BDF | `build/.bdf`：位图字体表示。 | | 映射 | `build/glyph-map.json`：源/字形名称和分配的 Unicode 码点。 | | 样本 | `build/glyph-sample.txt`：使用已分配码点的可复制文本。 | | 预览 | `build/previews/*.png`：每个生成的字形的阈值预览图像。 | | 字形锁 | `petiglyph.lock`：供未来构建使用的项目根分配历史记录。 | 现有的源映射通过 `petiglyph.lock` 保持稳定。已移除的 映射可能保持非活动状态，因此它们的码点不会被意外重用。 Petiglyph 为托管项目保留了非重叠的补充专用区域。 如果其拥有的范围必须增长且现有分配无法保留，正常的构建 可以自动重新定位和重新映射项目。 `--force-remap` 会有意丢弃现有分配并分配一个全新的映射。使用旧码点存储的文本可能会渲染出错误的字形 或根本不渲染任何字形。 生成的 TTF 可以像任何标准 字体一样嵌入到其他应用程序中。嵌入 Petiglyph 可执行文件本身也需要在每个用户的系统上提供 FFmpeg。 ### 安装和卸载 ``` petiglyph use-project my-font install-font petiglyph list installed-fonts petiglyph uninstall-font "my-font Petiglyph" petiglyph uninstall-all-fonts ``` 安装是显式的、托管的，并由项目元数据拥有。重新安装 项目会替换该项目先前的托管产物。在平台支持的 情况下，Petiglyph 会刷新或广播字体缓存状态。 托管位置： | 平台 | 位置 | | --- | --- | | Linux | `~/.local/share/fonts/petiglyph/` | | macOS | TTFs 位于 `~/Library/Fonts/`；元数据位于 `~/Library/Fonts/petiglyph/` | | Windows | `%LOCALAPPDATA%/Microsoft/Windows/Fonts/petiglyph/` | 使用 `list installed-fonts` 获取 `uninstall-font` 接受的确切字体系列名称。 卸载命令通过 Petiglyph 元数据选择托管产物， 并且不会移除不相关的字体。更改 字体后请重启应用程序，以便它们重新加载字体状态；完全重启系统仅作为最后手段。 在 Windows Terminal 1.21 或更高版本中，在主要的 终端字体之后添加已安装的系列作为回退字体，例如 `"Cascadia Mono, my-font Petiglyph"`。 ### 诊断和恢复 `petiglyph doctor` 始终检查全局托管安装和 Unicode 注册表 状态。当一个或多个清单可以被解析时，它也会 运行项目检查。 `petiglyph use-project my-font doctor` 显式地选择一个项目。 | 结果 | 含义 | | --- | --- | | `info` | 一次成功的检查或信息状态。 | | `warning` | 可恢复的不一致性或缺失的预期状态。 | | `error` | 可能阻碍正确操作的无效状态。 | | `repaired` 状态 | 报告的问题在此运行期间已成功更改。 | 检查涵盖过期的全局和项目锁、格式错误的安装元数据、 孤立的元数据和托管 TTF、Unicode 注册表结构和范围 冲突、清单有效性、源可见性以及字形锁标识、 条目、码点和源引用。 ``` petiglyph doctor --repair petiglyph use-project my-font doctor --repair ``` `--repair` 仅执行支持的修复，例如移除过期的锁和 孤立项、移除无效的字形锁条目或重新创建缺失的项目 范围分配。它不会重新构建或重新安装项目。 ### JSON 自动化 将 `--json` 添加到支持的命令中： ``` petiglyph list projects --json petiglyph use-project my-font create glyph \ --input logo.svg --build --json petiglyph use-project my-font doctor --json ``` 成功和失败的命令使用一个信封： ``` { "ok": false, "command": "use-project.create.glyph", "version": "0.1.5", "data": { "completed_stages": ["resolve", "import", "configure"] }, "error": { "code": "creation_stage_failed", "stage": "build", "message": "build failed", "causes": [], "hints": [ "Imported files and manifest changes were retained.", "Fix the reported cause, then run the project build or install command." ] } } ``` | 字段 | 含义 | | --- | --- | | `ok` | 成功时为 `true`，否则为 `false`。 | | `command` | 稳定的命令标识符。 | | `version` | 生成响应的 Petiglyph 版本。 | | `data` | 特定命令的负载；失败的创建操作包括已完成的阶段。 | | `error` | 成功时为 `null`，否则为结构化失败信息。 | | `error.code` | 机器可读的失败类别。 | | `error.stage` | 适用时标记失败的创建阶段。 | | `error.message` | 主要面向用户的错误。 | | `error.causes` | 嵌套的错误链消息。 | | `error.hints` | 恢复指导。 | | `error.candidates` | 提供时的候选匹配项；为空时省略。 | 失败会返回非零的退出代码。多阶段创建失败可以保留 已完成的导入和清单更改；请检查 `data.completed_stages`，修复 报告的原因，然后再次运行构建或安装。 ### 运行时、调试和故障排除 FFmpeg 会在命令分发之前（包括 TUI 启动时）被检查。请将其安装到 `PATH` 中，传递 `--ffmpeg-auto-install`，或设置 `PETIGLYPH_NO_FFMPEG_PROMPT=1` 以抑制交互式安装提示。 `--debug` 或设置为真值的 `PETIGLYPH_DEBUG` 会在所选项目目录的 `debug/pipeline.log` 和 `debug/artifacts/` 中启用图像管线诊断。 `PETIGLYPH_DEBUG_CELL=x` 会覆盖调试预览渲染所使用的 终端单元格几何形状。 设置 `PETIGLYPH_TUI_DEBUG=1` 以启用 TUI 事件日志。默认情况下，日志使用平台 临时目录；`PETIGLYPH_TUI_DEBUG_LOG=/path/to/log` 可覆盖 该路径。 | 问题 | 操作 | | --- | --- | | 缺少 FFmpeg | 将 FFmpeg 安装在 `PATH` 中或使用 `--ffmpeg-auto-install`，然后重新运行 Petiglyph。 | | 未找到项目 | 从包含深度 2 以内项目的目录运行，或使用 `new-project` 创建一个。 | | 项目选择不明确 | 在该基本名称唯一的工作区中使用 `use-project `。 | | 清单格式错误 | 修复报告的 TOML 字段或值；`list projects` 会报告格式错误的清单，而不将其视为有效项目。 | | 不支持该媒体 | 将其转换为支持的静态或动画格式；AVIF 必须通过导入工作流输入。 | | TUI 在终端外失败 | 在交互式终端中运行它，或者在自动化中使用带有 `--json` 的 CLI 命令。 | | 码点或注册表冲突 | 运行 `doctor`；对于支持的修复使用 `--repair`。仅在可以接受更改旧映射时才使用构建 `--force-remap`。 | | 过期的锁阻碍了工作 | 运行 `doctor --repair`；过期的锁会在十分钟后被识别。 | | 已安装的字形无法渲染 | 使用 `list installed-fonts` 确认确切的系列，在应用程序中对其进行配置，然后完全重启该应用程序。 | | 剪贴板复制失败 | 安装一个可用的提供程序：Linux/Unix 上的 `wl-copy` 或 `xclip`，macOS 上的 `pbcopy`，或 Windows 上的 PowerShell/`clip.exe`。 | ### 开发链接 - [CI.md](CI.md) - [RELEASE.md](RELEASE.md) - [CONTRIBUTING.md](CONTRIBUTING.md)

标签：ffmpeg, GIF处理, GNU通用公共许可证, MITM代理, Node.js, Python, Python安全, SVG处理, TUI工具, 二进制发布, 像素艺术, 像素转换, 可视化界面, 图像处理, 多媒体处理, 威胁情报, 字体生成器, 字符画, 开发者工具, 开源工具, 控制台应用, 无后门, 终端动画, 终端艺术, 自定义字体, 视频处理, 视频转字符画, 逆向工具, 通知系统