pdf2ofd

PDF 转换维护说明

本包解释 PDF 页面内容，并通过 pkg/creator 生成 OFD。 用户可依赖的能力范围、近似行为、资源预算和失败处理统一记录在 PDF 支持清单。本文件用于定位实现、运行回归和维护依赖。

文档与代码注释的分工

测试名称和断言是具体覆盖行为的主要记录。本文件只保留按主题查找的入口， 不逐次追加所有测试用例、临时输出路径或一次验证的数值结果。

实现入口与不变量

回归入口

下表提供主题入口。组合场景、预算、取消和诊断的具体断言以测试源码为准。

TestConvertTestdataPDFs 使用 testdata 下各来源目录中的 PDF 样本。样本、外部字体或独立阅读器 不可用时，应查看测试的 skip/省略日志；一次 go test 成功不表示全部外部验证已执行。

常用命令

以下命令均在仓库根目录运行：

go test -mod=readonly ./internal/pdf2ofd -count=1
go test -mod=readonly ./pkg/converter ./pkg/converter/import/pdf ./pkg/creator ./pkg/webreader -count=1
go vet -mod=readonly ./internal/pdf2ofd ./pkg/converter ./pkg/creator ./pkg/webreader
CGO_ENABLED=0 go test -mod=readonly -tags purego ./internal/pdf2ofd -run 'TestSemantic|TestType3|TestTextClipping|TestTransparency' -count=1
go run ./cmd/ofd-validator --format text --mode strict /path/to/output.ofd

OFD 严格校验预期为 0 错误、0 警告。它检验包结构和语义，不替代源 PDF 的显示对照。 真实杂志、标准文档等往返测试可能需要较长时间，运行时应保留完整结果。

外部字体与证据输出

OFD_CJK_TEST_FONT=/path/to/cjk-font.ttf go test ./internal/pdf2ofd -run 'TestCJK' -count=1 -v

测试字体从外部加载；没有合适字体时明确 skip，不下载或提交字体。基础专项也使用 Go 自带字体和内嵌的小型码流。Adobe CMap 是运行映射数据，来源、许可与重建由 cmaps/README.md 和 SHA256SUMS 维护。

独立验证与阅读器差异

PDF JPX 解码默认使用纯 Go 后端。Linux 可选构建 OpenJPEG 后端：安装 libopenjp2 开发文件与 pkg-config 后，使用 CGO_ENABLED=1 go test -tags openjpeg ./internal/pdf2ofd 验证；调用方可通过 Options.JPXBackend 选择 openjpeg。该后端应用 PDF /Decode 数组，用于需要匹配特定阅读器显示行为的文档。

修改渲染逻辑时，检查源 PDF、直接 OFD 栅格、往返 PDF 栅格和文字提取。 仅比较 OFD 与往返 PDF，或仅通过格式校验，不能证明与源 PDF 一致。

以下是回归中已观察到的阅读器差异，版本和参考值应保留在对应测试注释中， 不能据此宣称与所有阅读器一致：

32 位最近邻坐标计算另有独立回归；整包 386 验证曾被 go-xml/xdm 的既有年份 常量溢出阻塞，不能把单个坐标回归通过写成整项目已通过 32 位编译。

OFD→PDF 字体输出与依赖维护

多 FD CFF 子集化尚未实现。创建器保留完整字体面，转换器和 Web 阅读器的 PDF 输出 按字体使用完整嵌入回退；其他字体继续子集化。TTC 只提取所选字体面。

CID-keyed CFF 写为 FontFile3 /CIDFontType0C。PDF Encoding 将紧凑字符代码映射到 原 CFF charset 中的 CID，W 按 CID 写出；CIDFontType0 不使用 TrueType 专属的 CIDToGIDMap。ToUnicode 来自实际源文本，保留共享字形的不同 Unicode、连字和 补充平面字符。完整嵌入会增大 PDF，但应避免不安全地重排 FDSelect 和局部子程序。

本地 replace 会使用工作区依赖补丁。发布时需同步依赖版本，并确认脱离本地 replace 仍可构建；测试源码通过本地补丁不等于补丁已进入发布依赖。

font/canvas fork 单独运行默认 go vet 曾有 CFF2 不可达代码和 Point/Rect 未指定字段名 的既有提示。维护记录应区分项目相关包检查和依赖自身检查，不能合并描述为全部通过。