图像转文本 PDF

将已完成的光栅图像转换为 PDF，精确保留原始图像，并叠加一层透明文本层，以支持文本选择、复制与搜索。

工作流

1. 获取完整的图像。

• 将图像视为视觉上的唯一真实来源（source of truth）。
• 保持原始图像尺寸；布局坐标应尽可能使用相同的像素坐标空间。

2. 构建文本层布局 JSON 文件。

• 优先采用返回文本框（text boxes）的 OCR 工具或视觉模型，而非手动推断位置。
• 使用用户提供的源文本（source text）校正 OCR 识别结果：OCR 文本框决定位置，源文本决定最终可复制的内容。
• 如需提取、校正或提示框级文本（box-level text），请参阅 references/ocr-alignment.md。
• 关于 JSON 的确切结构，请参阅 references/layout-json.md。

3. 生成两个 PDF 文件。

python scripts/compose_image_text_pdf.py 
  --image /path/to/image.png 
  --layout /path/to/layout.json 
  --output /path/to/image-text.pdf 
  --debug-output /path/to/image-text-check.pdf

对于 CJK 或其他非拉丁文字，请传入 Unicode 字体：

python scripts/compose_image_text_pdf.py 
  --image /path/to/image.png 
  --layout /path/to/layout.json 
  --output /path/to/image-text.pdf 
  --debug-output /path/to/image-text-check.pdf 
  --font-file /path/to/NotoSansCJK-Regular.ttc

4. 交付前检查调试 PDF。

• 最终 PDF 的外观应与仅含图像的源文件完全一致。
• 调试 PDF 应高亮显示文本框，并在隐藏文本层将要放置的位置显示可见文本。
• 若高亮框发生偏移，请修正 layout JSON，而非修改图像。
• 若复制/粘贴的文本有误，请修正 layout JSON 中的 text 字段，而非 OCR 图像。

OCR 单词转布局

当 OCR 工具返回单词级（word-level）文本框时，需将其转换为行级（line-level）布局项：

python scripts/ocr_words_to_layout.py 
  --ocr /path/to/ocr.json 
  --output /path/to/layout.json 
  --image-width 1536 
  --image-height 2048 
  --source-text /path/to/source.txt

该转换器支持多种常见 JSON 格式，包括含 words、items、textAnnotations 字段，或嵌套的 page/line/word 对象。它会将邻近的单词聚类为行，并在匹配度足够高时，用源文本中最接近的对应行替换 OCR 输出的文本。

实践准则

• 除非整段文字必须作为一个整体被选中，否则文本框应保持为行级（line-level）——行级框更易于定位与调试。
• 无需精确复现光栅化字体（rasterized font）的样式；隐藏文本层只需几何位置大致准确且文本内容正确即可。
• 以可视化检查用的 PDF 作为验证产物（validation artifact）；它应使每个嵌入的文本片段清晰可见。
• 对于生成式图像，请在图像生成阶段即要求将文本以大号、彼此分离的区块形式呈现；密集细小的文字会显著增加 OCR 识别与人工校正的难度。
• 应将原始图像作为 PDF 背景予以保留，而非在演示文稿或网页格式中重新构建布局。