简介PdfPig是一个面向C#开发者的PDF解析库也可看作PDFBox的跨平台移植版本。它支持读取和提取PDF文件中的文本、几何信息并能创建包含文字与基本图形的新文档适用于内容抽取、版面分析、文档检索及OCR预处理等场景。该库基于NetStandard可方便集成到.NET Core、ASP.NET Core及桌面应用中。资源压缩包约27.03MB暂未公布文件数量与类型明细。目前已有572人学习下载。借助这份资源读者可以快速上手PdfPig的API理解PDF文档对象模型与文本提取流程同时参考从0.0.x升级到0.1.x的迁移指南避免踩坑。无论是开发PDF数据抽取工具还是需要为文档分析系统提供底层支持这份资料都能带来实际帮助。1. 用C#解PDF文本困局PdfPig到底给你什么接到一个合同归档需求时我发现自己又站在了同一个坑里PDF里明明有文字C#却怎么都抠不干净。正则匹配出来的文本七零八落页码错乱、多栏文本拼成一锅粥还查不到每个词的坐标。后来我拆了这份PDFBox在C#侧的移植版PdfPig才把整条提取链路理顺。PdfPig不是把Java的PDFBox包一层壳而是用C#重新实现了PDF解析器能拿到页面对象、字体字形、字母级坐标还带布局分析能力输出hOCR、ALTO XML、PageXML这些中间格式。适合做文档解析、RPA抓取、档案全文检索的.NET开发者新手能照着跑通熟手可以直接拿来改坐标算法。2. 从PDFBox到PdfPig命名空间映射与第一条提取流水线2.1 为什么是“移植”而不是“绑定”早期在C#里处理PDF常见路数是把PDFBox打包成Java运行时调用或者用IKVM把PDFBox转成.NET程序集。这种做法在演示Demo里没问题一上生产就露馅冷启动慢JVM内存被容器限额卡住部署还要附带一整套Java运行时环境。PDFBox的核心价值在解析逻辑不在Java本身于是就有了PdfPig这类纯C#移植把词法分析、字体解析、内容流解释都用C#重写。举一个我在模拟项目X里对比过的数据同样打开一份2000页的文档IKVM方案下程序集体积接近300MB内存峰值能到2GB以上PdfPig方案程序集不到10MB内存峰值大约在500MB到800MB差距主要来自不用拉起JVM。PdfPig基于netstandard 2.0所以老项目的.NET Framework 4.7.2能用新项目的.NET Core 3.1以上也能用不用单独适配。从API角度看迁移成本也不高。PDFBox里的PDDocument对应PdfDocumentPDPage对应PagePDFTextStripper提取纯文本这件事在PdfPig里就是page.Text。核心概念对齐后PDFBox时代写的业务逻辑能平移大半。2.2 最小可运行打开文档、取页面、拿文本先把包引入项目。我用的是dotnet命令行的方式dotnet add package UglyToad.PdfPig这条命令会从NuGet拉取PdfPig及其依赖。注意引入的包名和命名空间在1.x系列里已经统一成UglyToad.PdfPig老文章里写的PdfPig早期预览版命名空间可以忽略。接下来是第一个能跑的提取脚本using UglyToad.PdfPig; var bytes File.ReadAllBytes(contract.pdf); using (var document PdfDocument.Open(bytes)) { var page document.GetPage(1); Console.WriteLine(page.Text); }这段代码做了三件事读文件、开文档、取第一页文本。我习惯用Open(bytes)而不是Open(path)因为文件可能来自FTP下载流、对象存储的响应流用字节数组打开能避免文件句柄占用问题尤其在高并发抽取场景下路径方式容易撞上文件锁。PdfDocument实现了IDisposable一定要用using包住。很多人第一次用PdfPig时只记得Dispose页面忘了释放文档本身结果批量处理完内存一直涨。页面对象是解析结果的视图真正的底层对象池在文档里文档不释放池不会回收。2.3 从Letters重建带坐标的文本行page.Text拿到的是一整页的文本但PDF的文本输出顺序不是阅读顺序而是内容流里的绘制顺序。同一个页面里表格单元格、页眉页脚、浮动注释的位置在内容流里可能交替出现直接把page.Text扔给正则去匹配很容易跨区块匹配出错误结果。我在模拟项目X里处理采购合同时就翻过车页面底部有一个“合同编号A-2024-001”的页脚正文末尾也有一个合同编号page.Text把两段拼在一起正则优先命中了页脚。解决办法是放弃page.Text改用page.Letters拿字母级对象自己按坐标重建行var page document.GetPage(1); var lines page.Letters .GroupBy(letter Math.Round(letter.StartBaseLine.Y, 1)) .OrderByDescending(group group.Key) .Select(group new string(group .OrderBy(letter letter.StartBaseLine.X) .Select(letter letter.Value) .ToArray())) .ToList();这里按Y坐标分桶同一行文字的基础线Y值基本一致取一位小数容差把字母分到同一个桶里。每个桶内部按X坐标从左到右排序再拼成字符串。最后按Y值从大到小排列因为PDF坐标系统的原点在页面左下角Y轴向上增长顶部行Y值最大。这段代码的关键参数是分桶容差。取一位小数、约0.1磅的容差适合常规正文如果文档里混有上标、下标或公式容差要放大到行高中位数的一半否则上标会被拆成独立的一行。字母对象里的StartBaseLine是基线起点不是字母左上角做行分桶用基线比用边界框更稳。3. 拆开PDF对象模型Catalog、字体表与字母级坐标3.1 PDF的逻辑层与物理层Catalog、Pages、Contents流PDF文件从物理结构上看是一堆对象的集合对象之间用对象编号和偏移量互相引用文件尾部的xref表负责索引。但从逻辑层看入口只有一个根目录对象Catalog。Catalog往下挂页面树Pages页面树挂具体PagePage的Contents引用内容流内容流里才是真正的绘制指令。PdfPig把这层逻辑结构基本照搬到了C#侧。document.Catalog可以拿到文档级目录信息遍历Catalog.Pages.DirectPages能拿到所有Page对象。每个Page对象暴露了宽度、高度、旋转角度这几个关键属性var page document.GetPage(1); var width page.Width; var height page.Height; var rotation page.Rotation; var number page.Number;width和height的单位是点1点等于1/72英寸这个单位在处理坐标时必须时刻记住。很多坑都出在这把72磅当成1像素去做可视化画出来的框全偏了。旋转角度处理在后面避坑章节展开。内容流层面的解析PdfPig做得比较透明。它把内容流里的Tj、TJ、TD等文本绘制指令解释成一个一个Letter每个Letter都保留了它来自哪个内容流、绘制时用了哪套矩阵。这意味着你不用自己去解析PDF指令但要理解Letter背后对应的是PDF的BT/ET文本块。3.2 字体与字形信息拿宽度、字号与GlyphName叠加业务PDF里每个文本绘制指令都会选择一种字体然后绘制一组字形编码。PdfPig的Letter对象里有GlyphName、Value、FontSize、Width这些字段组合起来能还原出排版细节。我当时做印章位置检测就用到了这些字段印章文字往往字号和正文不一致而且GlyphName会带一些特殊后缀。foreach (var letter in page.Letters) { Console.WriteLine( $Glyph{letter.GlyphName}, Text{letter.Value}, $Size{letter.FontSize}, Width{letter.Width:F2}); }这里要强调一点FontSize不一定是可信的最终字号。PDF允许通过Tm矩阵缩放字体PdfPig给出的FontSize是字体字典里的规格值实际绘制尺寸可能是矩阵变换后的结果。所以做宽度计算时我一般用StartBaseLine和EndBaseLine的X坐标差值而不是Width字段。GlyphName在乱码排查时特别好用。有些PDF的字体没有ToUnicode映射Value字段拿到的是空或者乱码但GlyphName是正常的。比如GlyphName为“A”而Value为“?”时说明字体编码映射断了GlyphName可以做二次兜底。3.3 把Letters按坐标聚成ALTO XML的String节点拿到字母级坐标后的常规操作是把它们聚合成词、行、块再输出成标准交换格式。ALTO XML就是其中一种常见的版面交换格式图书馆数字化项目里几乎必用。基本映射规则是一个TextBlock对应一个段落块TextLine对应一行String对应一个词。PdfPig没有直接提供“导出ALTO”的现成方法但坐标信息足够手工拼出来。先按2.3节的Line模型分好行再在行内按词间距聚类var words page.Letters .GroupBy(letter Math.Round(letter.StartBaseLine.Y, 1)) .SelectMany(line SplitWordsBySpace(line.OrderBy(l l.StartBaseLine.X))) .ToList();词间距的判断我用了一个简单阈值两个字母之间的X距离大于前一个字母宽度的0.3倍就判定为词分隔。这个阈值来自英文排版的平均词间距规律对中文PDF不适用中文词间距接近0需要按长度或语义分词。做多语种抽取时这一步建议按文档语言分开处理。ALTO坐标系原点是左上角和PDF的左下角原点不同导出时需要翻转Y轴ALTO xmlnshttp://www.loc.gov/standards/alto/ns-v3# Layout Page WIDTH612 HEIGHT792 PrintSpace TextBlock TextLine String CONTENT合同编号 HPOS72 VPOS720 WIDTH48 HEIGHT12/ /TextLine /TextBlock /PrintSpace /Page /Layout /ALTO转换公式是altoVPOS pageHeight - pdfY - letterHeight先翻转基线位置再减去字母高度把基线上移到字母顶部。HPOS直接取PDF的X坐标不用翻转。很多新手第一次导出的ALTO文字全部镜像错位问题都出在忘了减letterHeight。4. 布局分析与文档处理器把页面还原成hOCR、PageXML4.1 ExperimentalText与布局分析段落、单词、阅读顺序PdfPig带了一套标记为Experimental的布局分析API挂在page.ExperimentalText下面。这套API解决的是从“字母”到“单词、段落”的聚合问题var words page.ExperimentalText.GetWords(); var paragraphs page.ExperimentalText.GetParagraphs(); foreach (var paragraph in paragraphs) { Console.WriteLine(paragraph.Text); }GetWords的内部逻辑是最近邻聚合把每个字母当成一个节点计算字母之间的几何距离距离小于阈值的节点合并成词。这个阈值不是固定的而是按字号、行间距动态算出来的。正因如此它对数字生成的PDF效果很好扫描件或手写体基本不能用。GetParagraphs更激进会分析行间距和缩进把行聚成段落多栏版面下表现一般需要配合坐标做二次修正。我一般把这些实验API当成“快速原型”而不是“生产依赖”。做大规模抽取时还是用2.3节的方法重建行再用行间距聚类段落这样每一步的决策阈值都可以落配置、做回归测试。ExperimentalText的好处是不用自己调参适合先跑一版看看文档结构再决定要不要定制。4.2 PdfDocumentProcessor逐页处理的文档处理器PdfPig在较新版本里引入了PdfDocumentProcessor专门解决大文档内存问题。之前一次性Open整个文档再逐页GetPage文档的交叉引用表、资源字典、字体数据都会驻留在内存里。Processor的思路是把“打开文档”和“逐页处理”拆开处理完一页就丢弃这一页的中间产物。我在某跨平台系统里处理几万份PDF时测过用Processor逐页抽取内存峰值比一次性加载低30%到40%耗时几乎没有增加。它的用法是注册一个逐页回调var processor new PdfDocumentProcessor(); processor.Process( archive.pdf, (page, pageNumber) { var lineTexts RebuildLines(page.Letters); SaveToDatabase(pageNumber, lineTexts); });细节上不同1.x小版本的Processor回调签名略有差异以NuGet包内XML注释为准。核心思想是一致的不要在回调里累积页面对象处理完立刻把结果写入外部存储。如果你用的版本没有Processor也可以用“逐页打开字节流”的办法模拟但性能不如内建的实现。4.3 导出PageXML与hOCR坐标翻转变换与命名空间布局分析和OCR领域常见的两种中间格式PdfPig都能通过坐标映射生成hOCR是嵌在HTML里的带坐标文本PageXML是专门面向版面分析场景的XML格式。hOCR的核心结构是带title属性的spanbbox表示边界框左上角为原点span classocrx_word titlebbox 64 690 112 702合同编号/span从PDF坐标转到hOCR的bbox和ALTO一样要做原点翻转。公式hocrTop pageHeight - pdfBottomhocrBottom pageHeight - pdfTop。注意PDF坐标里字母对象只有基线和边界框没有直接的top值top要从StartBaseLine.Y加上字母高度算出来。字符高度可以用EndBaseLine.Y减去StartBaseLine.Y近似也可以用Width反推。PageXML的根节点自带命名空间常见版本是2019-07-15这一套page:Page xmlns:pagehttp://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15 imageWidth612 imageHeight792 page:TextRegion page:TextLine page:Word page:Coords points64,690 112,690 112,702 64,702/ /page:Word /page:TextLine /page:TextRegion /page:PagePageXML的坐标直接放points点集比ALTO多一步要把PDF的矩形转成左上、右上、右下、左下四个点。转换时Y翻转的基准是页面高度而不是某个区块高度否则多栏页面里下栏的坐标会整体偏移。这套导出映射做好了以后整个处理链路就通了PdfPig负责PDF侧解析ALTO/PageXML负责给下游的文档分析引擎消费两边用坐标校准不再依赖脆弱的纯文本正则。5. 避坑排查PdfPig实战里绕不开的五个坑5.1 文本顺序乱序从内容流顺序到阅读顺序现象page.Text提取出来的段落句子顺序是乱的正文和页脚交替出现。 原因PDF内容流按绘制指令顺序存储文本不代表阅读顺序。页脚先画正文后画page.Text就会先输出页脚。 解决不用page.Text用page.Letters按坐标重建行和块。分桶容差先取0.1磅检查结果再按需放大。如果文档里有多栏排版还要在行分桶之后增加一列聚类按栏位切分再拼阅读顺序。5.2 扫描件没有文本层PdfPig不内置OCR现象page.Text返回空字符串或只返回极少内容但人眼能看见文字。 原因文件是扫描图片转成的PDF页面只有图像对象没有文本绘制指令PdfPig本质上是解析器不是OCR引擎。 解决先用OCR引擎给扫描件加一层文本层再用PdfPig提取。常见做法是保留原始图像坐标OCR出文本后自行映射到ALTO/PageXML。PdfPig在图像处理这个环节帮不上忙认清边界能省不少时间。5.3 字体编码映射缺失导致的乱码现象Value字段显示为空、乱码或问号但GlyphName字段正常。 原因PDF字体没有ToUnicode CMap或使用了自定义编码常见于部分国产公文软件生成的PDF。 解决排查路径分两步。先看GlyphName是否是标准Adobe字形名如果是可以建立字形名到Unicode的补全映射表如果GlyphName本身也是自定义编号基本只能靠渲染识图或人工校对。这类问题没有银弹遇到前先跑一批样本统计乱码比例再决策。5.4 大文档内存冲高一次性加载全部页现象处理3000页以上的PDF时内存持续上涨甚至OOM。 原因PdfDocument.Open后页面对象和相关资源都驻留在内存里逐页GetPage不会自动释放。 解决改用PdfDocumentProcessor逐页处理或者手动控制文档生命周期。特别注意处理完一个文档后要显式调用Dispose不能等GC否则文件句柄和对象池释放时机不可控。5.5 旋转页面的坐标错位现象提取出的文字坐标画到可视化面板上全部顺时针或逆时针偏转。 原因页面字典里的Rotate字段指定了旋转角度PdfPig的Letter坐标是未旋转的原始坐标系统。坐标标注、印章检测这类业务一旦遇到横向表格页坐标必然错位。 解决读取page.Rotation先做旋转补偿再进入业务逻辑。90度旋转时X和Y互换并翻转公式是newX pageHeight - oldYnewY oldX。这个坑排查起来很隐蔽因为页面上半部分的文字看起来仍然有序但整体坐标偏了。6. 进阶技巧用坐标重建版面矩阵并定位关键字段6.1 按y分桶重建版面矩阵当一份页面既有标题、正文、表格又有页脚时光是拼行还不够要把行还原成二维矩阵。我现在的做法是先把所有行按Y分桶再对同一桶内的词按X排序灌进一个ListList 每一行对应一行文字。var matrix page.Letters .GroupBy(letter Math.Round(letter.StartBaseLine.Y, 1)) .OrderByDescending(g g.Key) .Select(g g.OrderBy(l l.StartBaseLine.X).Select(l l.Value).ToArray()) .ToList();matrix的索引就隐含了版面位置。做“合同编号”定位时我不再全文正则匹配而是先定位到包含关键词的那一行再去相邻行里找值。这样能避免页脚干扰也能处理表格里同一字段多次出现的情况。6.2 用关键词坐标锚定字段值定位到关键词行之后下一步是取字段值。常见情况是“合同编号A-2024-001”整行都在用冒号切分就行但也常见“合同编号”和值分属两个连续行。我建议按坐标锚定而不是按字符串索引var keywordIndex matrix.FindIndex(line string.Join(, line).Contains(合同编号)); if (keywordIndex 0 keywordIndex 1 matrix.Count) { var value string.Join(, matrix[keywordIndex 1]); }坐标锚定的好处是抗干扰页脚出现的“合同编号”不会和正文的值行相邻即使两个“合同编号”都匹配到了只有和值行处于同一版面流的那一处才是目标。遇到表格类版面时这个思路还可以扩展成按列聚类思路完全一致。从那以后我每次做PDF解析上线前都会强制走一遍检查页面旋转角度、坐标原点方向、字体ToUnicode映射是否完整。这套检查我已经写进了团队的项目脚手架里省掉了无数次线上返工。希望帮到你。本文还有配套的精品资源点击获取