技术文章

用 HotPDF 在 Delphi 中将 PDF 页面导出为 SVG

在 PDF 里排一个标题,常见写法是 /F1 1 Tf 10 0 0 10 72 700 Tm (Total) Tj ( due) Tj:字号是 1,真实大小由文本矩阵携带。把它喂给一个手写的 PDF 转 SVG 转换器,第二段文本往往几乎叠在第一段上面。假设 "Total" 的五个字形平均半个 em,文本原点应前进 2.5 个文本空间单位,经矩阵换算是 25 磅。转换器若把 2.5 直接加到矩阵平移分量上,笔只走到十分之一处," due" 就叠印在前一个词上

ISO 32000-1 §9.4.4 明确规定文本空间内的位移要经过文本矩阵,所以更新是 e += tx*a 和 f += tx*b,绝不是对 e 做普通加法。PDF 状态必须在元素落笔的那一刻带进 SVG 属性,这样的地方还有很多,本文剩下的篇幅就逐个过一遍

用 BuildLoadedPageSVG 导出已加载的页面

HotPDF 能把已加载文档的任意一页导出为独立的 SVG 1.1 文件。THotPDF.BuildLoadedPageSVG 接收一个从零起算的页面索引,以 AnsiString 返回整个文档,页面无法导出时返回空串;SaveLoadedPageAsSVG 把同样的标记写入文件,失败时返回 False。两者都有一个带 EmbedFonts 标志的重载,后文再讲

导出页面的尺寸取自 crop box。宽高以磅为单位写出,viewBox 使用 PDF 用户单位,所以 SVG 里的一个单位就是 PDF 里的一个单位。路径、文本段、图像 XObject、内联图像、着色、平铺图案、裁剪路径、Type 3 字形和嵌套的 Form XObject 都会进入输出,栅格内容则以 base64 PNG data URI 的形式随文件携带

var
  Pdf: THotPDF;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('statements.pdf', '') <= 0 then
      Exit;                  // LoadFromFile 返回页数
    for I := 0 to Pdf.LoadedPageCount - 1 do
      if not Pdf.SaveLoadedPageAsSVG(I, Format('page-%d.svg', [I + 1])) then
        Writeln('Page ', I + 1, ' could not be exported');
  finally
    Pdf.Free;
  end;
end;

对于不想随身带一个编译好的 Delphi 程序的构建管线,HotPDF 命令行工具以 HotPDFCLI export-svg <pdf-file> [-o prefix] [--pages range] 的形式暴露同样的导出。SVG 是文本,这让它与 把 PDF 页面渲染为位图 中的栅格路线成为好搭档:位图告诉你页面长什么样,SVG 则告诉你页面由哪些对象画出来,而且是一种文本 diff 能读懂的形式

为什么整页一翻,字形和照片全毁

PDF 用户空间从左下角向上生长;SVG 从左上角向下生长。整页只翻一次能修正所有坐标,但同一笔也会把每个字母、每张照片镜像掉。另外两处不匹配更隐蔽。PDF 用栈给状态定作用域(q 压入,Q 弹出),SVG 则让元素继承祖先分组声明的一切。PDF 还有不少内容靠约定表达:线端和线接是整数,零宽度意味着"最细可见线",操作符变体切换缠绕规则

HotPDF 从 Delphi 导出页面时,把有状态的 PDF 内容流映射为声明式 SVG 树,贯穿 y 轴原点、栈作用域和整数约定
有状态的 PDF 内容流遇上去声明式的 SVG 树,三处不匹配都需要翻译而非照搬

BuildLoadedPageSVG 用一个页面预变换处理翻转,并在局部修正文本和图像。每个文本元素都带着这条链:页面预变换 × CTM × 文本矩阵 × matrix(1,0,0,-1,0,0)。右侧因子在自己的小坐标系里把字形重新立起来,基线则留在页面翻转放它的地方。因为修正是矩阵而不是特殊分支,旋转、镜像和倾斜的文本都不需要额外代码

图像用另一个因子。PDF 图像空间把第一行采样放在单位正方形顶边,而 SVG image 元素自带 y 向下的坐标系,所以输出的变换是 CTM 右乘 matrix(1,0,0,-1,0,1)。符号一错,页面的矢量内容完好无损,每张照片却倒挂起来

带 /Rotate 项的页面会在翻转前先在 y 向上的显示空间里加一个旋转:90 度对应 (0,-1,1,0,0,W),180 度对应 (-1,0,0,-1,W,H),270 度对应 (0,1,-1,0,H,0),其中 W 和 H 是未旋转的页面尺寸,翻转使用旋转后画布的高度。页面框也未必从原点开始。crop box 为 [100 100 712 892] 的页面,导出器会先把左下角挪到 (0,0) 再旋转,与栅格渲染器采取的步骤相同,否则内容会落在画布外一百个单位

HotPDF 为 /Rotate 90、180 和 270 组合页面旋转预变换,并将 CTM 右乘 matrix(1,0,0,-1,0,1),使 Delphi PDF 到 SVG 导出保持嵌入图像直立
页面旋转预变换与图像翻转矩阵共同保证旋转页面和照片在导出的 SVG 中保持正立

文本矩阵与逐字符定位

每个文本段变成一个 SVG text 元素,其 x 属性为每个字符各列一个位置。位置从字形前进量加字符间距 Tc 累加而来,词间距 Tw 只在单字节码 32 之后追加。碰巧等于 32 的双字节码拿不到词间距,这是 ISO 32000-1 §9.3.3 的规定,也是 CID 字体赖以工作的前提。一个字形代表多个字符时(比如连字),这些字符共享它的前进量,但每个字符仍各有自己的 x 值

水平缩放和文本提升按 §9.4.4 折进文本渲染矩阵,写成 [Th 0 0 1 0 Trise] × Tm,因此它们随被变换过的文本矩阵一起缩放、一起旋转。TJ 数组里的 kerning 数值是千分之一 em,与其他水平移动一样要乘以 Th

两个 XML 细节很重要。每个 text 元素都带 xml:space="preserve";没有它,查看器会合并连续空格,x 列表就与字符错位。文件是 UTF-8,字符显式按 UTF-8 编码,不走系统代码页。XML 1.0 禁止的码点(低于 0x20 的控制字符、代理区、U+FFFE 和 U+FFFF)被替换为 U+FFFD。来自 复杂文字塑形 的文本走同一条路,因为在内容流写出之前,塑形器已经把字符簇变成了带定位的字形

具名字体还是嵌入轮廓

默认情况下文本声明自己的字体:导出器从 /BaseFont 和字体描述符推出一个字体族,加上 Arial, sans-serif 这类通用兜底,查看器用已安装的字体绘制文本。这让文件保持小巧、文本完全可用,但如果页面是用一款嵌入的企业字体排的,任何没装它的机器都会用替代字体绘制,宽度再也对不上逐字符位置

给 EmbedFonts 传 True 会把嵌入字体程序的字形写成 defs 块里的轮廓,在页面上所有出现处共享。原始文本仍以零填充不透明度写在轮廓之上,因此可以选中、可以搜索。SVG 只要离开生成它的机器,就用 True:设计交付、归档、CI 代理上的视觉比对都算。文件留在装有这些字体的环境里且在乎体积时,用默认值

procedure ExportOutlined(Pdf: THotPDF);
var
  Svg: AnsiString;
  Output: TFileStream;
begin
  // 来自嵌入字体的字形轮廓,上层叠可选择文本
  Svg := Pdf.BuildLoadedPageSVG(0, True);
  if Svg = '' then
    raise Exception.Create('Page 1 could not be exported');
  Output := TFileStream.Create('page-1-outlined.svg', fmCreate);
  try
    Output.WriteBuffer(Svg[1], Length(Svg));
  finally
    Output.Free;
  end;
end;

两条路径都遵循渲染模式。模式 1 只描边不填充,模式 2 既填充又描边,模式 3 不可见但照常前进笔位,模式 4 到 7 把字形加进裁剪路径。描边字形还需要一次修正:线宽活在用户空间,而 text 元素在文本空间绘制,所以线宽要除以文本矩阵的缩放。用 2 Tr 0.25 w 加粗的文本因此保住四分之一磅的轮廓;若留在 SVG 默认的一个单位,它会显得粗笨

图形状态带进每个元素的是什么

SVG 呈现属性不遵循 PDF 的作用域规则,所以每条路径都带着当下生效的完整描边状态落笔。线端 0, 1, 2 变成 butt、round、square;线接 0, 1, 2 变成 miter、round、bevel;斜接限制、虚线数组和虚线相位在设置时写出。带负数项的虚线数组,或没有正数项的非空数组,会被忽略并沿用上一个图案;空数组 [] 恢复实线。同样的值也可以经 ExtGState 字典到达,其 LW、LC、LJ、ML、ca 和 CA 键同样生效

PDF 里零线宽意味着设备能画出的最细的线。照抄会让描边不可见,抄成 1 则让线随每次放大变粗。导出器写出 stroke-width="1" 并配以 vector-effect="non-scaling-stroke",无论放大多少倍,这条发丝线都保持约一个设备像素宽。星号操作符 f*、B* 和 b* 附加 fill-rule="evenodd",普通形式则保留 SVG 默认的非零缠绕

Q 恢复填充和描边颜色、不透明度、线宽、线端、线接、斜接限制、虚线数组和相位,文本状态也一并恢复。ISO 32000-1 §9.3.1 把文本状态划入图形状态,所以 q … Q 内设置的 2 Tr 不能去描边 Q 之后的文本。裁剪遵循 §8.5.4:W 只标记路径,裁剪在绘图操作符之后生效,所以 re W f 先填充矩形、后应用裁剪。每个裁剪变成一个 clipPath 加一个包裹分组,Q 关闭自匹配的 q 以来打开的分组

Form XObject 的行为等价于一个隐式的 q … Q。导出器把 form 裁剪到它的 /BBox,进入时保存状态、退出时恢复,图章内部的虚线边框不会把样式泄漏进其后的页面内容。平铺图案映射到使用它的内容流的默认空间(§8.7.2),也就是页面或 form,与绘制图案时的 CTM 无关。EMF 和 WMF 矢量导入 以相反方向运行类似的状态模型,作为 Form XObject 导入 SVG 则覆盖从 SVG 回到 PDF 的反程

颜色、着色与测试要比对的字符串

颜色经由每一个 PDF 颜色操作符进入 SVG:g、rg、k 及其描边形式,以及带页面或 form /ColorSpace 资源中具名空间的 cs / scn。Separation、DeviceN、ICCBased、Indexed 和 Lab 颜色由页面渲染器所用的同一套颜色空间代码解析成 RGB。用 cs 选择空间时,从 §8.6.8 定义的初始颜色出发:设备空间里是黑色,Separation 和 DeviceN 里是 tint 1.0,Indexed 里是索引 0。SVG 没有油墨的概念,专色到达时是它的 RGB 外观,油墨名留在 PDF 里。需要真实分色的打样工作属于 渲染 Separation 与 DeviceN 专色 中描述的上色模型

轴向和径向着色变成 SVG 渐变。规范把 /Extend 默认为 [false false],即 t0 之前、t1 之后什么都不画,而 SVG 的 pad 扩散方式会把端点颜色向外铺。导出器给每个不延伸的端各加一个全透明色标来弥合差异。基于函数的着色按每单位约一个采样点的密度采样成图像,网格着色则渲染成嵌入图像

十六进制颜色以大写输出。做字符串比较的回归测试要预期 #FF0000,按小写写的测试会在完全正确的输出上失败。坐标和宽度四舍五入到四位小数,transform 矩阵保留九位有效数字,两者都以句点作小数分隔符,与跑测试那台机器的 locale 无关

procedure CheckRedRectangle(Pdf: THotPDF);
var
  Svg: AnsiString;
begin
  Svg := Pdf.BuildLoadedPageSVG(0);
  // Assert 是你自己在测试里加的检查,不属于导出功能
  Assert(Pos(AnsiString('fill="#FF0000"'), Svg) > 0,
    'expected the red fill in uppercase hex');
  Assert(Pos(AnsiString('xml:space="preserve"'), Svg) > 0,
    'text elements keep their spaces');
end;

这类字符串检查在输入 PDF 由你自己的代码生成、预期颜色已知时是站得住的。对外来页面,把两个构建的 SVG 互相比对,能抓住的问题比任何硬编码属性都多。围绕已加载文档的其余工具集,从渲染、编辑到导出,都写在 HotPDF Delphi PDF 组件页面