ofd-converter

ofd-converter

OFD 文档转换命令行工具，支持将 OFD 文件转换为 PDF、DOCX（Word）、纯文本、Markdown、单文件 HTML 和图像格式（包括多页 TIFF），也支持将 PDF、XPS、Markdown、Office 文档（doc/docx/odt/rtf/wps/pptx/xlsx 等）和 HTML/MHTML 转换为 OFD 或 PDF。

使用本工具处理文档前，请阅读项目根目录的 免责声明。转换结果不保证适用于特定业务、法律或合规场景。

编译

go build .

用法

ofd-converter [选项] <输入文件> [输出文件或目录]

ofd-converter [选项] --input-dir <输入目录> --output-dir <输出目录>

查看命令帮助：

ofd-converter --help

选项

输出格式可通过 -format 指定，也可根据输出文件扩展名自动推断（.zip 需要显式指定 -format）。输入默认为 OFD，PDF、XPS 等其它输入按文件扩展名识别为对应导入器，也可用 -from 显式指定。多个文档体按出现顺序合并，页码从所有文档体的第一张页面开始连续计算。 批量转换时必须通过 -format 指定统一的输出格式；默认使用 4 个并发任务，单个文件失败后会继续转换其他文件，全部任务完成后返回失败汇总。

选项作用范围

部分选项只在特定转换方向生效，容易误用。下表列出常见选项的适用范围：

需要注意：

• -paper 和 -landscape 不会改变 OFD → PDF、Markdown → OFD、Office → OFD/PDF 的页面尺寸。OFD → PDF 保留原页面尺寸；Markdown → OFD 使用固定 A4 版式；Office → OFD/PDF 使用源文档自身的页面设置。
• 图片转 OFD 默认只嵌入图片；指定 -ocr 后才调用本机 Tesseract，默认语言为 chi_sim+eng，即简体中文与英文。
• 因此，例如把 -landscape 用在 ofd-converter input.ofd output.pdf 上不会有任何效果。

退出码

2 与 1 的界线是「命令要不要改」：前者重试没有意义，后者可能是文档本身有问题， 批量任务里更需要靠这个区分判断是否该整体重跑。批量模式下单个文件转换失败仍 按 1 汇总，不会因为参数分层被记成 2。

PDF 预算参数的负值或超出允许范围返回 2；文档超过预算、严格模式遇到诊断返回 1。

加密文档

-password 提供打开口令，目前只作用于 PDF 输入。口令不对时转换直接失败并说明 原因，不重试：

ofd-converter -password 'secret' -format ofd enc.pdf out.ofd

口令会出现在进程命令行里，同主机其他用户可从 ps 读到。批量处理加密文档时应 确认执行环境可信。

OFD 的包级加密（GB/T 33190）目前不支持：这样的文件会报解析失败。

中断

转换按页推进，每渲染完一页就检查一次取消信号，因此 Ctrl-C 会在当前页结束后 立即停止，而不是跑完整个文件（批量模式同理）。停止时输出 已取消。 并以退出码 130 退出——这是用户主动停止，不是转换失败。

示例

PDF 转 OFD

ofd-converter input.pdf output.ofd
ofd-converter -from pdf -format ofd input.pdf output.ofd
ofd-converter --pdf-strict --pdf-max-input-bytes 33554432 input.pdf output.ofd
ofd-converter --pdf-image-mode compact --pdf-jpeg-quality 90 input.pdf compact.ofd
ofd-converter --pdf-jpx-backend openjpeg input.pdf openjpeg.ofd

OpenJPEG 是可选后端。启用前需安装 libopenjp2 开发包和 pkg-config，并在 Linux 上以 CGO_ENABLED=1 go build -tags openjpeg ./cmd/ofd-converter 构建。默认构建不链接 OpenJPEG；非 Linux、禁用 CGO 或未启用构建标签时选择该后端会在遇到 JPX 图片时报错。

compatible 保持默认图像兼容性和无损处理；compact 将无软蒙版/颜色键的 CMYK JPEG 转为 RGB JPEG，以减小照片资源体积，可能产生有损画质变化。带 Mask 或 SMask 的图像 仍采用 PNG，以保留透明边缘；此类页面及非 JPEG 图像不保证明显缩小。

PDF 导入默认限制输入、页数、对象数、解压流、图片像素、字体、输出图元、处理量与 递归深度。所有预算超限都会终止转换。CLI 可调整输入和图片预算；完整默认值及库 API 见 PDF 支持清单。

普通模式遇到已识别的内容缺失或近似转换，会继续生成 OFD，并向标准错误报告诊断码、 输入文件、页号、对象编号与资源名。--pdf-strict 在首条诊断后失败，已有输出文件保留。 严格模式针对已报告的转换缺口，不代表完整实现 PDF 规范。

Markdown 转 OFD

Markdown 输入会被重新排版为 A4 固定版式，支持标题、段落、列表、引用、代码块、GFM 表格和本地图片；代码块使用系统等宽字体（优先 Noto Sans Mono CJK SC / DejaVu Sans Mono 等）。出于安全和确定性考虑，不会抓取远程图片（http/https 地址会被跳过并记录警告）。相对图片路径以 Markdown 文件所在目录为基准。-paper 和 -landscape 对 Markdown 输入不生效。

行内链接与自动链接会写成文字图元上的 CLICK 动作，OFD 阅读器与 PDF 导出都能点。目标原样保留，相对路径不拼成绝对路径。空目标（[文字]()）与纯锚点（[文字](#标题)）只按链接配色、不生成动作——Markdown 标题不会被写成 OFD 大纲，锚点无处可跳。

ofd-converter input.md output.ofd
ofd-converter -from md -format ofd input.md output.ofd

图片转 OFD

图片按页面尺寸整幅嵌入，不做版面切分。默认只嵌图片，不产生文字层——文档体积最小，但既不能搜索也不能复制文字。

加 -ocr 后会调用本机 Tesseract 识别文字，生成一个不可见文字层盖在图片上：视觉仍是原图，但文字可选中、可被浏览器和 PDF 阅读器内查找。Tesseract 未安装或语言包缺失时会返回明确错误，不会静默降级。默认语言 chi_sim+eng（简体中文 + 英文），可用 -ocr-language 换成 eng、chi_sim 或其它已安装语言的组合。

扫描件要得到可搜索的 PDF 时，图片 → OFD（带 OCR）→ PDF 是比直接转 PDF 更可控的路径。

ofd-converter scan.png output.ofd
ofd-converter -ocr -ocr-language chi_sim+eng scan.png output.ofd

Office 文档转 OFD / PDF

通过 LibreOffice 命令行转换 Office 文档：转 OFD 时先转 PDF 再复用 PDF→OFD（保留文字层），转 PDF 时直接输出。需要目标机器已安装 LibreOffice；未安装会返回明确错误。支持 doc/docx/odt/rtf/wps、ppt/pptx/odp、xls/xlsx/ods 等常见格式。页面尺寸沿用源文档设置，-paper 和 -landscape 在此方向不生效。

ofd-converter report.docx report.pdf
ofd-converter --from docx --format ofd report.docx report.ofd
ofd-converter report.doc report.ofd
ofd-converter --soffice /opt/libreoffice/program/soffice --office-timeout 300 report.pptx report.ofd

批量转换 Office 文档或 HTML/MHTML 时通过 -external-workers（默认 2）限制同时运行的 LibreOffice/Chrome 进程数，普通输入仍使用 -workers。

XPS 转 OFD / PDF

XPS 输入通过系统的 xpstopdf 转换为 PDF，再由现有 PDF 导入器转换为 OFD。需要目标机器安装 libgxps；也可以通过 -xpstopdf 或 OFD_XPSTOPDF 指定可执行文件路径。XPS 转 PDF 时不会经过 OFD 中间格式。

ofd-converter input.xps output.pdf
ofd-converter input.xps output.ofd
ofd-converter -xpstopdf /usr/bin/xpstopdf input.xps output.ofd

XPS 与 Office/HTML 输入一样受 -office-timeout 和 -temp-dir 控制；批量转换时受 -external-workers 限制。

HTML/MHTML 转 OFD / PDF

通过 Chrome/Chromium 打印引擎渲染 HTML/MHTML：转 OFD 时先转 PDF 再复用 PDF→OFD，转 PDF 时直接输出。需要目标机器已安装 Chrome/Chromium；未安装会返回明确错误。支持 html/htm/xhtml 与 mhtml/mht。默认禁止加载外部资源（仅本地与 data:），纸张默认 A4。

ofd-converter page.html page.pdf
ofd-converter --format ofd page.html page.ofd
ofd-converter --paper A3 --landscape page.html page.pdf
ofd-converter mail.mht mail.pdf
ofd-converter --chrome-no-sandbox --allow-remote page.html page.pdf

OFD 转 PDF

ofd-converter input.ofd output.pdf

OFD 转纯文本

只提取页面中的文字内容，不保留字体、颜色和页面布局。文字对象按 Y 坐标聚成行、行内按 X 坐标排序，并根据水平位置用空格补位对齐列（CJK 等全角字符按两列宽度计算）；不同页面之间使用分页符 \f 分隔。

ofd-converter input.ofd output.txt
ofd-converter -format txt input.ofd output.txt

OFD 转 Markdown

Markdown 转换只提取文字内容，不保留字体、颜色和页面布局：

• 首行一级标题使用 OFD 文档体的 DocInfo.Title；没有标题时使用 OFD 文档。
• 段落之间会补空行：按段首缩进、段落标记（第 X 条、第 X 编、(一)、一、 等）以及纵向段间距识别段落起点，避免 GFM 把多行软换行合并成同一段。
• 不同页面之间使用水平分隔线 --- 分隔；若首个页面没有文字，不会在正文前输出多余分隔线。
• 以 第 X 章 开头的行（支持阿拉伯数字和中文数字）输出为二级标题 ##。
• 其余标题根据字号比例以及编号（如 1.、1.2.、1.2.3.）识别为 ### 及更深层级，最深不超过六级。
• 只有位于页面顶部或底部的纯页码行（如 12、- 12 -、— 12 —）会被过滤；页面中部的纯数字行（如代码行号、数据）会保留。
• 正文中的 Markdown 特殊字符（\、`、*、_、[、]、<、>、|、~ 及行首标记）会被转义。

输出格式说明

OFD 转 Word（DOCX）

输出的是可编辑的 Word 文本，不是页面截图：OFD 的绝对坐标被转换成 Word 的标题、段落、列表、带框线表格与内嵌图片，文字可以直接改字、复制、重排。

代价是版面不再固定。换字体或改文字后 Word 会按自己的规则重排，所以发票、 证照这类依赖精确位置的版式会走形——这类需求请继续用 PDF 输出。

具体取舍：

• 字号与字体名按 OFD 原值写入 w:sz 与 w:rFonts，不嵌入字体文件， 实际字形取决于打开方的系统字体。
• 纸张尺寸取首个有内容的页面；OFD 允许逐页不同尺寸，本转换不做逐页分节。
• 批注层的水印与印章默认剔除。批注在 OFD 里承载的是叠加在正文上的标记： 整页水印、电子印章、签章位置、阅读批注。实测保密宣传册首页的「保密资料」水印 由 81 个批注文字对象组成，同页真实正文只有 5 个，不剔除时每个段落都会被水印 文字淹没。用 -docx-annotations 可以保留。
• 页面模板层不作剔除：它常放页眉页脚与标题栏，是真内容。
• 行首带序号的行按列表条目输出（Word 自动编号，序号不在正文里重复显示）。 只识别单段序号（「1.」「2)」「一、」「（三）」「· 」），且要求同段序号连续、 从 1 开始。多段序号（「1.2.」）一律不识别——实测几乎都是章节号或带点前导符的 目录条目，做成自动编号会丢掉前导符与页码并改写序号。跨页延续的列表（每页只有 一条）也会漏判。
• 图片按页面上的纵向位置穿插进文字之间，栅格格式（PNG/JPEG/GIF/BMP/TIFF/EMF/WMF） 按原始字节内嵌。每页最多 64 张，避免整版图片类的文档产出体量失控的文件。
• SVG 等矢量图片会被跳过。DOCX 没有等价的矢量内嵌表示，转成位图会损失清晰度， 不如不输出。
• 图片图元的裁剪（Clips）与边框（Border）暂不还原，输出的是原始矩形。

用 -no-docx-tables 关闭表格识别（双栏正文、公式排版容易被误判成表格）， 用 -no-docx-images 关闭图片内嵌。

ofd-converter 文档.ofd 文档.docx
ofd-converter -docx-annotations 文档.ofd 文档.docx

Markdown 的表格识别

使用 -md-tables 时，还会根据文字的水平位置和空白间隔识别无边框表格（OFD 没有表格语义，表格只是文字对象的位置组合），输出 GFM 表格：第一行作为表头，跨多行的单元格会按纵向位置合并到同一行。该识别依赖版面位置，双栏正文、公式排版等可能被误判，因此默认关闭。

ofd-converter input.ofd output.md
ofd-converter -format markdown input.ofd output.md
ofd-converter -format markdown -md-tables input.ofd output.md

转换为指定格式的图片

ofd-converter -format png input.ofd output.png
ofd-converter -format jpg -bg white input.ofd output.jpg
ofd-converter -format tiff -dpi 300 input.ofd output.tiff
ofd-converter -format svg input.ofd output.svg

OFD 转单文件 HTML

HTML 默认将每页渲染为内嵌 PNG；使用 -html-format jpg 或 -html-format svg 时则分别使用内嵌 JPG 或 SVG 写入 HTML。三种模式都不依赖外部资源，并保留页面尺寸和浏览器打印分页。HTML 的 <title> 优先使用 OFD 第一个文档体的非空 DocInfo.Title，没有标题时使用 OFD 文档。

页面上叠有一层透明文字层：视觉由页面图像承担，文字层让页面里的文字可选中、可被浏览器内查找（Ctrl+F）、可被屏幕阅读器朗读。它不内嵌字体，字号用容器查询单位随页面缩放，对产物体积影响可忽略（两页文档约 210 字节、0.2%）。代价是文字度量由浏览器用系统字体完成，与 OFD 版面可能有细微偏差，用 -no-html-text-layer 可关掉。

-html-format svg 会把页面用到的字体整份 base64 内嵌（canvas 的 SVG 写入器不做子集化），单页可达 10MB 以上，仅适合小文档试验，不建议用于正式输出。

ofd-converter -format html input.ofd output.html
ofd-converter -format html -html-format jpg input.ofd output.html
ofd-converter -format html -html-format svg input.ofd output.html
ofd-converter -format html --no-html-text-layer input.ofd output.html

转换指定页面

ofd-converter -format png -page 3 input.ofd page3.png

多页输出为 zip 包或目录

ofd-converter -format png -o pages.zip input.ofd
ofd-converter -format png -o pages/ input.ofd
ofd-converter -format png -dir -o pages input.ofd

TIFF 输出为单个 TIFF 文件；多页 OFD 会写成多页 TIFF，支持 .tif 和 .tiff 扩展名。TIFF 使用 Deflate 压缩；背景默认为白色，DPI 由 -dpi 控制。

批量转换

批量模式递归查找输入目录下扩展名为 .ofd 的普通文件，以及所有已注册导入器的输入文件（PDF、Markdown、Office 文档等），扩展名大小写不敏感。文本、Markdown、HTML、PDF、OFD 和 TIFF 每个输入生成一个文件，并保留输入目录的相对路径；PNG/JPEG/SVG 等逐页图像格式每个输入使用独立目录保存页面图像：

# 默认使用 4 个并发任务，递归转换为 PDF
ofd-converter --input-dir ./ofd --output-dir ./pdf --format pdf

# 使用 8 个并发任务转换为 Markdown
ofd-converter --input-dir ./ofd --output-dir ./markdown --format md --workers 8

# 多页 OFD 转换为 PNG，每个 OFD 一个页面目录
ofd-converter --input-dir ./ofd --output-dir ./images --format png

# 只扫描输入目录的第一层
ofd-converter --input-dir ./ofd --output-dir ./pdf --format pdf --recursive=false

# 批量把 Office 文档转换为 OFD，限制 LibreOffice 并发为 2
ofd-converter --input-dir ./docs --output-dir ./ofd --format ofd --external-workers 2

例如，input/nested/demo.ofd 会生成 output/nested/demo.pdf；转换为 PNG 时会生成 output/nested/demo/page-0001.png 等页面文件。批量转换不会覆盖输入目录中的同名文件；如果有文件转换失败， 命令会在所有任务完成后返回退出码 1，并列出失败文件及错误原因。默认直接覆盖已有输出；使用 -overwrite=false 时，已有输出会记为失败且不会覆盖；使用 -skip-existing 时，已有输出会跳过且不计为失败。

输出到标准输出

ofd-converter input.ofd - > output.pdf
ofd-converter -format txt input.ofd - > output.txt
ofd-converter -format md input.ofd - > output.md
ofd-converter -format png -page 1 input.ofd - > page1.png
ofd-converter -format tiff input.ofd - > pages.tiff

多页 PNG/JPEG 等图像输出时文件名格式为 page-0001.png 等；TIFF 输出为单个多页文件。