Go x/image/font/sfnt UnitsPerEm 为什么不是输出图片字号

用 Go 解析 TTF 或 OTF 后，如果看到 UnitsPerEm() 返回 1000、2048 之类的数字，很容易把它误认为“字体要输出多少像素”。这个理解会让字号、字形边界和画布尺寸全部错位。

官方地址：https://pkg.go.dev/golang.org/x/image/font/sfnt

UnitsPerEm 返回的是字体内部 em 方格包含多少个抽象 font units；输出图片中的字号由调用 Metrics、GlyphBounds 或 LoadGlyph 时传入的 ppem 决定。UnitsPerEm 主要用来理解和转换字体坐标，不是直接传给图片画布的字号。

一、先分清字体内部单位和像素字号

SFNT 字体保存的是可缩放的轮廓和元数据。UnitsPerEm 告诉你一个 em 方格在字体坐标系里有多少个单位，常见值是 1000 或 2048。这个数描述字体设计坐标的分辨率，不代表屏幕、图片或打印设备上的像素。

sfnt 的文档把另一件事写得很明确：涉及长度、坐标和字体指标的方法都接收 ppem，它表示 1 em 对应多少像素，并且使用 26.6 定点数。比如希望 1 em 约为 30 像素，传入的是 fixed.I(30)，而不是 fixed.I(int(f.UnitsPerEm()))。

二、把 ppem 作为渲染目标传入方法

排查字号时，先把目标像素尺寸明确下来，再把它转换成 fixed.Int26_6。下面的函数只负责读取字体指标，便于观察“同一字体在 30 像素和 48 像素 em 下会得到什么结果”。

package main

import (
	"fmt"

	"golang.org/x/image/font"
	"golang.org/x/image/font/gofont/goregular"
	"golang.org/x/image/font/sfnt"
	"golang.org/x/image/math/fixed"
)

func printMetrics(ppemPixels int) error {
	f, err := sfnt.Parse(goregular.TTF)
	if err != nil {
		return fmt.Errorf("解析字体失败: %w", err)
	}
	var buf sfnt.Buffer
	// ppem 是目标像素字号；fixed.I 会把整数像素转换为 26.6 定点数。
	ppem := fixed.I(ppemPixels)
	metrics, err := f.Metrics(&buf, ppem, font.HintingNone)
	if err != nil {
		return fmt.Errorf("读取字体指标失败: %w", err)
	}
	fmt.Printf("UnitsPerEm=%d ppem=%d ascent=%v descent=%v height=%v\\n",
		f.UnitsPerEm(), ppemPixels, metrics.Ascent, metrics.Descent, metrics.Height)
	return nil
}

func main() {
	// 分别观察两个渲染目标，不能把字体内部单位当成字号传入。
	if err := printMetrics(30); err != nil {
		fmt.Println(err)
	}
	if err := printMetrics(48); err != nil {
		fmt.Println(err)
	}
}

这里的 UnitsPerEm 只被打印出来做诊断，真正进入 Metrics 的是 ppem。如果把 2048 当成像素传入，计算结果对应的是一个极大的 em 目标，后面即使画布只有几百像素，也会出现裁剪或“字号异常大”的现象。

三、为什么看起来字号对了，字形仍然不居中

字号只是 em 的目标像素尺寸，不等于某一个字符轮廓的宽高。字符有自己的边界、左右留白和 advance；字体整体还有 ascent、descent 和行高。把这些值混在一起，最常见的结果就是字形被裁掉、基线偏移或不同字符之间间距不一致。

func inspectGlyph(r rune, ppemPixels int) error {
	f, err := sfnt.Parse(goregular.TTF)
	if err != nil {
		return fmt.Errorf("解析字体失败: %w", err)
	}
	var buf sfnt.Buffer
	// 每次用同一个 ppem 读取字符索引，保证比较发生在同一像素目标下。
	ppem := fixed.I(ppemPixels)
	glyph, err := f.GlyphIndex(&buf, r)
	if err != nil {
		return fmt.Errorf("查询字形索引失败: %w", err)
	}
	if glyph == 0 {
		return fmt.Errorf("字体没有提供 %q 的字形", r)
	}
	// GlyphBounds 返回当前字形边界和 advance，不代表最终画布大小。
	bounds, advance, err := f.GlyphBounds(&buf, glyph, ppem, font.HintingNone)
	if err != nil {
		return fmt.Errorf("读取字形边界失败: %w", err)
	}
	fmt.Printf("rune=%q bounds=%v advance=%v\\n", r, bounds, advance)
	return nil
}

GlyphBounds 的返回值描述的是“这个字形放在原点时的边界”和它的 advance。边界可能有负的左上坐标，advance 还可能大于实际墨迹宽度。要把字形放入图片，应该先根据边界和基线计算画布位置，而不是直接把 UnitsPerEm 当成宽高。

四、用 LoadGlyph 时不要重复缩放

LoadGlyph 返回的是经过 ppem 缩放后的矢量线段。线段坐标仍然是 fixed.Int26_6，交给矢量栅格化器时通常要除以 64 转成像素坐标。这里有两个容易叠加的错误：一是传入错误的 ppem，二是拿到已经按 ppem 缩放的线段后再按 UnitsPerEm 额外缩放一次。

func loadGlyph(r rune, ppemPixels int) (sfnt.Segments, error) {
	f, err := sfnt.Parse(goregular.TTF)
	if err != nil {
		return nil, fmt.Errorf("解析字体失败: %w", err)
	}
	var buf sfnt.Buffer
	glyph, err := f.GlyphIndex(&buf, r)
	if err != nil {
		return nil, fmt.Errorf("查询字形索引失败: %w", err)
	}
	if glyph == 0 {
		return nil, fmt.Errorf("字体没有提供 %q 的字形", r)
	}
	// LoadGlyph 已按 ppem 生成当前像素目标下的轮廓，不再乘除 UnitsPerEm。
	segments, err := f.LoadGlyph(&buf, glyph, fixed.I(ppemPixels), nil)
	if err != nil {
		return nil, fmt.Errorf("加载字形轮廓失败: %w", err)
	}
	return segments, nil
}

sfnt 本身是低层解码器，不负责把矢量直接变成图片像素。若后续使用 vector.Rasterizer，应根据线段的 fixed.Int26_6 坐标转换到栅格器坐标，再结合基线和画布原点绘制。不要因为图片显示得小，就把 UnitsPerEm 重新当成缩放因子。

五、字号不符时按四层信号排查

1. 输入字体层：确认实际解析的是预期的 TTF、OTF 或字体集合成员；不同字体的 UnitsPerEm 可以不同，不能用一个固定值替代。
2. 目标尺寸层：记录传给 Metrics、GlyphBounds、GlyphAdvance 和 LoadGlyph 的 ppem，检查是否使用了 fixed.I 或等价的 26.6 表示。
3. 指标层：同时观察 Metrics 的 ascent、descent、height，以及目标字形的 GlyphBounds 和 advance；不要只量图片里非透明像素的宽高。
4. 画布层：确认基线、原点、缩放和裁剪逻辑。画布留白变大不代表字号变小，字形边界偏移也不一定是 UnitsPerEm 错了。

六、把 UnitsPerEm 用在它真正擅长的地方

当需要在字体坐标和像素坐标之间做明确换算时，UnitsPerEm 才会成为比例的一部分。例如字体原始坐标中的某个长度要映射到当前 ppem，可以按“字体单位 ÷ UnitsPerEm × ppem 像素”理解；但具体的字形轮廓和指标最好让 sfnt 的方法按 ppem 计算，避免自己漏掉定点数、hinting 或坐标方向。

如果目的是得到最终文字图片，还要继续处理栅格化、抗锯齿、基线、背景和裁剪。UnitsPerEm 只负责说明字体坐标系的尺度，不能替代这些渲染步骤。

七、值班式速查清单

• 看到 UnitsPerEm 时，把它记为“字体内部 em 方格的单位数”。
• 看到 ppem 时，把它记为“当前 1 em 的像素目标”，使用 fixed.I 传入整数像素。
• 要判断整行高度，看 Metrics；要判断单个字形，看 GlyphBounds 和 advance。
• 要拿到可栅格化轮廓，用 LoadGlyph，随后处理 26.6 定点坐标和画布原点。
• 若输出不对，按字体输入、ppem、指标、画布四层记录，不要先修改 UnitsPerEm。

八、总结

sfnt.Font.UnitsPerEm() 返回的是抽象的 font units 数量，典型值 1000 或 2048 只说明字体内部坐标如何组织。输出图片字号要看传给字体方法的 ppem，它是 1 em 对应的像素数，并以 26.6 定点表示。实际排查时，先确认 ppem，再分别查看 Metrics、GlyphBounds、advance 和画布定位，最后才处理矢量到像素的栅格化。

相关问题

• fixed.I(30) 和直接写入 30 为什么不是同一个参数？
• 为什么同一个 ppem 下，不同字符的 GlyphBounds 高度仍然不同？
• 什么时候应该使用 font.HintingNone 来观察字体单位？
• sfnt 的矢量轮廓和最终图片像素之间还差哪些栅格化步骤？