Image to Fonts — 样本图片 → OTF 字体
经过验证的流水线:二值化 → 连通组件分离(合并点/碎片) → 行/基线估计 → 矢量追踪(轮廓行走 + 拐角保留型平滑 + 闭合RDP) → em坐标取整后二次清理 → 大写700归一化 → 光学上伸/侧间距校正 → opentype.js打包为OTF。上伸(如O略微超出基线)和装饰(如Q的尾巴)均按原样复制,因此会自动保留。
步骤0 — 必须首先询问字体名称
图片到达后,在开始工作前首先询问字体名称(例如:“字体名称叫什么?”)。如果图片只包含英文字符,建议使用英文名称——中文名称可能导致在Photoshop等软件中字体列表显示为透明(名称不可见)。获得名称后再继续。如果用户已经说了名称,则直接使用。
同时确认:如果样本是受版权保护的商业字体,请添加一行提示(仅供个人学习/实验用途),如果用户已知则跳过。
步骤1 — 分辨率确认(根本上的最重要事项)
“放大后看起来不平滑”、“每个字符大小不同”等反馈90%是因为原始分辨率不足,而非算法问题。 实测:用相同字符比较85px高度的字符表与500px高度字符表,平滑处理前原始追踪数据的点数分别为201个与575个(2.9倍差距)——低分辨率导致曲线绘制材料不足。
- 收到图片后,首先通过
img2bin.py获取转换后尺寸(W, H),并结合大致行列数估算每个字符的像素高度。 - 如果字符高度远低于150px(尤其是80~100px范围),则继续工作,但提前告知“放大后可能较为粗糙”,或者最好请求“请重新拍摄/导出字符高度300px以上的图片再上传”。
- 可以接收多张图片(如大写字符表+小写字符表)——按照下文“多张表合并”流程合并为一个字体。
img2bin.py的缩放上限为3400px(以宽高中较大者为准)。若收到超过此上限的原图,将在此上限范围内最大化利用。
步骤2 — 图片分解
cd <此技能的scripts文件夹>
python3 img2bin.py <上传图片> /tmp/ff/sheet.bin # 输出: W H
node pipeline.js segment /tmp/ff/sheet.bin <W> <H> /tmp/ff/work
检查 segment 输出 JSON 中的 count 和 standard:
standard: true(26/52/62个) → 判断为字母顺序表。按读取顺序自动生成标签:- 26个 =
A~Z,52个 =A~Z a~z,62个 =A~Z a~z 0~9 - 编写 labels.json:
{"0":"A","1":"B",...}(comps.json 中的 i 顺序 = 读取顺序)
- 26个 =
standard: false→ 表中混有标题、装饰、样本文本或单词样本。绝不强制按顺序标注(偏移一个位就会导致整个字体出错)。改为:
→ 直接通过 view 工具查看 contact.png,肉眼识别每个编号格中的字符,然后编写 labels.json。装饰、不可识别字符标记为python3 contact_sheet.py /tmp/ff/work /tmp/ff/contact.png"skip"。同一字符出现多次时,只保留最清晰的一个用于字符本身,其余标记为"skip"。("?"会作为实际问号字符进入字体,因此不要用于丢弃碎片。)- 如果行结构可见则利用:若为字母表,但前后夹杂了标题/样本行,找到4行13个字符的行(即 A-M / N-Z / a-m / n-z),则仅对这些行按顺序标注,其余行全部标记为
"skip"。 - 若是单词样本(如“MODERN SERIF”),则提前告知用户只有出现的字符会进入字体。
- 如果行结构可见则利用:若为字母表,但前后夹杂了标题/样本行,找到4行13个字符的行(即 A-M / N-Z / a-m / n-z),则仅对这些行按顺序标注,其余行全部标记为
多张表合并(例如:大写.png + 小写.png)
python3 img2bin.py 大写.png /tmp/ff/upper.bin # 输出: W H
python3 img2bin.py 小写.png /tmp/ff/lower.bin # 输出: W H
node pipeline.js segment /tmp/ff/upper.bin <W1> <H1> /tmp/ff/work_upper
node pipeline.js segment /tmp/ff/lower.bin <W2> <H2> /tmp/ff/work_lower
合并两个结果的 comps.json(对裁切索引重新编号以避免冲突,并复制 crops 文件),编写合并后的 labels.json(大写索引→A-Z,小写索引→a-z),然后只运行一次 build。这样大写基准比例(capMed)才能一致地应用于两套字符。(合并脚本示例请参考之前的会话记录——用 Python 连接两个 comps.json 数组,并复制 crops/ 文件即可。)
数字/符号表
标签不仅可以使用英文、数字,也可以直接使用单字符符号(如 "!", "@", "?", "’" 等)。字形名称会自动转换为标准名称(如 exclam, at, question),字偶间距调整仅应用于英文、数字对。
- 符号表包含
!·?·;·%·=等多碎片字符以及小点、引号,因此 segment 的自动合并和行过滤经常出错(将相邻符号合并为一整块,或整行丢弃较小行)。如果 count 与预期不符,请使用 contact sheet 确认;若出错,则直接提取连通组件并查看编号后的图片,手动为每个字符拼接碎片,创建comps.json/crops/(格式与 segment 结果一致:i, row, x0..y1, baseline, cropW, cropH, offX, offY)。如果需要调整不同表格间的尺寸(如数字比大写字母小的表格),则先按比例调整图片。 - 表中缺失的符号可以利用已有碎片组合:
"= 两个引号,:= 两个点,.= 点,,= 逗号。 - 表中的布局与排版位置不同。build 后,在 project.json 中调整位置,然后用
node pipeline.js rebuild <project.json> <out.otf>重新生成(以 cap 700 为基准):- + = ~ < > *的垂直中心约为340,引号类上端约为705,_上端约为-60,[ ]高度与( )一致。注意:很多表格的最后一行字符(如 XYZ)画得特别小,请检查高度,调整后通知用户。 - 如果只有大写字母表,则将大写字母形状复制到 a–z 中,使其作为小写字母也能显示(通知用户)。字偶间距也复制到小写/大小写混合对,通过
apply_kerning.py添加。
步骤3 — 字体构建 + 质量检查
轮廓闭合——“起始点尖刺突出”bug已在pipeline.js中修复
像 S 顶部那样应圆滑的地方出现尖刺的 bug,已通过使 loopsToPath 中的所有坐标取整为整数而修复(原因见下方工程笔记)。尽管如此,每次构建时仍需通过以下检查确认。
闭合性检查(始终包含在构建后QA中,结果应为0个):
python3 - /tmp/ff/font_final.otf <<'EOF'
import sys
from fontTools.ttLib import TTFont
from fontTools.pens.recordingPen import RecordingPen
gs=TTFont(sys.argv[1]).getGlyphSet(); bad=[]
for n in gs.keys():
p=RecordingPen(); gs[n].draw(p); st=la=None
for op,a in p.value:
if op=='moveTo': st=a[0]
elif op in('curveTo','lineTo','qCurveTo'): la=a[-1]
elif op=='closePath' and st and la and max(abs(st[0]-la[0]),abs(st[1]-la[1]))>2: bad.append(n)
print('轮廓闭合异常的字形:', len(bad), bad[:10])
EOF
node pipeline.js build /tmp/ff/work /tmp/ff/labels.json "<字体名称>" /tmp/ff/font.otf /tmp/ff/project.json
构建后,必须进行 Mac/Windows 兼容性清理和验证:
PSNAME=$(node -e "
const opentype=require('./opentype.min.js');
const b=require('fs').readFileSync('/tmp/ff/font.otf');
const f=opentype.parse(b.buffer.slice(b.byteOffset,b.byteOffset+b.length));
console.log(f.names.postScriptName.en);
")
python3 fix_mac_names.py /tmp/ff/font.otf "$PSNAME" "<字体名称>" /tmp/ff/font_final.otf
fontbakery check-opentype /tmp/ff/font_final.otf --loglevel FAIL 2>&1 | grep -c "Result: FAIL" # 应为0
python3 -c "from ots import sanitize; print('OTS:', 'PASS' if sanitize('/tmp/ff/font_final.otf', check=False, capture_output=True).returncode==0 else 'FAIL')"
python3 render_preview.py /tmp/ff/font_final.otf /tmp/ff/qc.png "<字体名称>"
直接通过 view 工具检查 qc.png。但注意:在此环境中,根据会话不同,可能无法实际通过 view 工具查看渲染图像。 此时,应尽可能通过结构性诊断(如下文“结构性QA”部分)进行检查;如果仍无法发现缺陷,应坦诚告知用户“我无法直接看到结果”,并请求用户提供问题区域的放大截图——不要凭空猜测或滥加修改。
步骤4 — 交付成果
- 复制到
/mnt/user-data/outputs/:<字体名称>.otf+<字体名称>_project.json(project.json 用于后续字符替换/调整,务必一同提供并告知用户妥善保存)。将两个文件打包为 zip 一同提供(以防环境阻止直接下载 .otf)。 - HTML 预览文件(使用
make_preview.py):将 .otf 以 base64 内联嵌入的单一文件。- 基于
preview_template.html(位于 assets 文件夹)生成。组成:- 顶部“Image to Font Skill”标题
- 用该字体大号渲染字体名称 + 完整字符表(包含实际字体中的大写、小写、数字、符号行及数量)
- 用户指定的样本文本一行
- 亲自试用(Type Tester) — 输入框 + 尺寸(16–160px)/字距滑块。位于样本卡片下方、下载卡片上方
- [字体文件(.otf)下载] 按钮 — 如果 HTML 在本地打开,则直接保存 .otf;在 Claude 模块查看器中,通过
downloads功能保存<名称>.zip(内含 .otf)(查看器会阻止页面直接下载,也不允许 .otf 扩展名)。发布为模块时,必须声明{downloads: true}功能,按钮才能生效——未声明则点击无反应。 - “有想要替换的字符吗?”提示卡片 — 这不是 HTML 内部的上传/修改功能,而是静态提示文本(无按钮、无JS),告诉用户“返回此对话窗口并上传字符图片”。字符替换仅通过对话方式处理——绝不要在 HTML 中添加文件上传/拖放/zip下载功能(以前添加过,但只会增加复杂性,实际并未使用)。
- 底部
© @用户句柄版权 + “使用/分享时请注明出处”字样
- 预览文件除了作为模块发布外,HTML 文件本身也必须一同提供(与 .otf, project.json, zip 一起)。如果环境不支持下载功能声明,则告知用户通过聊天中的文件卡片获取字体文件。
- 基于
- 提供文件(.otf, project.json, zip, preview.html)+ 总结识别了哪些字符、缺失字符、安装方法(双击 .otf)。
- 在传递消息末尾必须询问(可以一次性问两个问题):
- “如果某个字符形状异常或需要替换,请将放大图片附加到此对话中(建议字符高度150px以上)。”
- “还有其他需要调整的地方吗,比如字距或字符形状?”
如果用户附加了图片,按照下文“字符替换(patch)”流程处理;如果用户提供字距反馈,则通过缓存
/tmp/ff/work仅调整参数重新构建(无需重新上传图片)。
字符替换(patch)——仅用高分辨率图像重新处理特定字符
用户对某个字符不满意,并上传了该字符的大图时:
python3 img2bin.py <放大图片> /tmp/ff/patch.bin # 输出: W H
node pipeline.js patch <project.json 路径> /tmp/ff/patch.bin <W> <H> <字符> /tmp/ff/font.otf /tmp/ff/project.json
- project.json 由用户提供(来自之前会话)或位于同一会话的 /tmp 中。如果找不到,则请求用户提供。
- patch 将“图片整体的墨迹”视为一个字符(不会仅选择连通组件中最大的碎片)。这样,O 内部的螺旋装饰等与笔画分离的细节也能完整保留——以前只会选择一个最大碎片,导致此类细节完全丢失的 bug。
- 如果一张图片中包含多个字符(例如“Z”和“H”并排),则自动找到列方向墨迹密度接近零的位置进行分割,然后分别 patch。
- 会自动对齐原字符的高度和最低点(包括上伸/下伸部分),无需担心尺寸问题。替换后重新构建 → QA(fontbakery/OTS) → 更新预览 → 重新交付。
- 对于字体中原本没有的 g/j/p/q/y 类小写字母,通过 patch 新增会被拒绝,因为无法估计基线——请告知用户使用完整字符表。
字距/字符形状微调(无需重新上传)
如果原始分割结果缓存在 /tmp/ff/work(或合并后的 work_merged)中,则只需调整 pipeline.js 中的常量,然后重新运行 node pipeline.js build ... 即可。可调整的参数(均在 build 命令内):
- 默认字距(侧间距):
LSB计算公式的比例(当前 0.66)——降低则整体更紧凑 - 单词间距(空格宽度):
spaceAdv计算公式的比例(当前 LSB×5.4) - 字偶间距强度:触发阈值(当前 -3)和最大拉近宽度(当前 -190)——阈值放宽(如 -1)会使更多字符对拉近
- 光学侧间距(左右独立):由
edgeCurviness测量的 leftStd/rightStd 超过阈值(cropW×0.02)的一侧才进行缩小(当前 72%)。必须按左右独立计算——之前对只有一侧为曲线的字符(如 j 的左侧环为曲线、右侧点/竖为直线)使用左右相同的值,导致另一侧无辜变窄的 bug(通过“j 看起来与后粘贴字符连在一起”的反馈发现)。 - 字符级光学上伸:根据顶部/底部“平坦度比例”(从顶部端开始,很细的条带宽度 ÷ 稍内侧条带宽度,从衬线支架之后测量,当前使用
H*0.03/H*0.15位置,阈值 0.62)自动判断 topFlat/botFlat。扁平字符(纯flat)比例 1.0,仅一侧扁平则为 1+OVERSHOOT_HALF,两者都不是则为 1+OVERSHOOT_ROUND,乘以原始scale(当前分别为 0.7%/1.2%)。使用DEBUG_SHAPE=1 node pipeline.js build ...可在 stderr 查看每个字符的 topFlat/botFlat/nativeH。 - x-height 自然聚类:不考虑是否存在上伸部/下伸部(不得根据是否有下伸部来过滤候选字符——nativeH 是基线到顶部的距离,与下伸部无关),将全体小写字母的
nativeH排序,找到最大间隔(gap),仅选择该间隔下方的聚集(仅当占总数的 35% 以上时采用),然后统一对齐到公共基准高度。用于对齐 v,w,x,y,z 等细微上端高度偏差的纯 x-height 字符。
绝对不要做的事情——曾经发生的严重 bug:切勿使用“将所有小写字母强制调整到 x-height 目标高度”的方式。这会将带上升部(b,d,f,h,i,j,k,l 等)的小写字母也压到 x-height 高度,导致比原版小很多的事故(用户反馈“你在开玩笑吧?”并立即要求回滚)。正确方式:绝对不要触碰原始图片的全局 scale,对于单个字符,只在其自身缩放上乘以一个很小的比例(1.007~1.012 等)略微放大。x-height 聚类设计上也确保绝不包含聚类外的字符(如带有上升部的字符)。
原始图片本身的实际大小差异(例如表格中某个字符确实画得更大)不属于算法修正的范围——请向用户确认原始图片是否就是有意设计的。
要求从字体中某个字符派生另一个字符的请求(例如“将小写 s 设为缩小版大写 S”)不要将此请求设为技能的固定功能——明确指示为“仅本次应用,不要加入技能逻辑”。如有需要,可通过一次性后处理脚本直接操作 project.json(复制目标字形的 loops 后缩放到目标高度并重新定位坐标),不修改 pipeline.js 的 build 逻辑。
结构性QA(当无法直接通过 view 工具查看时)
在无法查看渲染图像的会话中,可以直接打开 project.json 的 glyphs 数据检查以下内容:
- 轮廓缠绕方向:检查外轮廓与内空间(counter)循环的有符号面积(鞋带公式)是否互为相反符号——符号相同则内空间可能无法正确镂空。
- 自相交:检查循环中非相邻线段之间是否有交叉(O(n²) 检查)。
- 异常线段:平均线段长度 4 倍以上或小于 0.5 的线段(但直线立柱等正常长线段也可能存在,仅供参考)。
- 高度/字距实测:使用 fontTools 的
BoundsPen、hmtx表提取特定字符的 top/bottom/advance/RSB,与目标值比较。也可以使用uharfbuzz测量实际造型宽度(含字偶间距)。
如果通过这些诊断仍无法发现问题(例如“部分字符像被撕裂了一样”),应坦诚告知“结构上没有发现缺陷,但我在此环境中无法直接查看渲染效果”,并请求放大截图。
工程笔记
- 度量:unitsPerEm 1000,ascender 760,descender -240(总和必须为 1000——否则所有字符都会垂直偏移)
- 大写字母、数字高度中位数 → 归一化为 700。行的基线 = 该行底部 y 的中位数(上伸、下伸自然以负值保留)
- 合并规则:仅小碎片(面积小于 30%)被大碎片吸收——用于 i·j 的点、断开的花丝线。绝对禁止合并字符本身(防止装饰下伸部吞掉下一行字符的事故)
- 行过滤:根据面积较大碎片的高度中位数(bigH)的 0.5~1.28 倍范围外移除行(如标题、说明、超大样本行)。此过滤器也不完美,因此当 count 不是标准值时,必须用肉眼看 contact sheet
- 重复标签仅使用第一个
- em 坐标取整阶梯效应(已修复):将像素坐标转换为最终 em 单位(通常放大 5~6 倍)时,如果每个点独立取整,原本完全直线的线段也会产生微小偏移,看起来像阶梯。
glyphFromCrop在取整后立即使用很小的容差(2.2 单位)再进行一次简化以消除残留锯齿。该问题不会随分辨率提高而自动消失(反而放大倍数越大越明显)。 - 轮廓平滑:
traceBinary沿像素边界行走产生的阶梯噪声,在rdpClosed简化之前,先通过smoothPolyline(拐角保留型,仅对拐角角度小于 71 度的点进行邻居平均缓和)消除。拐角判断阈值也放宽至 71 度,使真正的拐角(如衬线支架)保持锐利,其余部分作为曲线处理。 - 轮廓起始点尖刺突出(已修复,2026-11):S 顶部等应圆滑的地方出现尖刺的长期 bug。其原因并非边框处理或分辨率,而是文件保存阶段——
loopsToPath将中点/贝塞尔控制点传递为小数时,opentype.js 在 CFF 中为每个点独立取整写入相对坐标,导致误差在一圈内累积,终点与起点偏差 5~15 单位,closePath 用直线连接此间隙形成尖刺(几乎所有字符都有,在点多的 S 上最明显)。现在所有坐标都取整为整数传递。仅凭 project.json 绝对看不出来,因此如果怀疑,应像“闭合性检查”那样直接检查最终 .otf 的绘图命令。 - 结果格式为 .otf(安装、使用与 .ttf 相同)。如果用户真正需要 TTF,告知其在 FontForge 中打开后生成即可。