技術文章

在 Delphi 中為掃描 PDF 加上可搜尋文字層

在掃描 PDF 裡搜尋發票號碼找得到命中,醒目提示卻落在印刷數字左邊半英吋、下方半英吋處。半英吋是 36 點,而出事的頁面帶有 CropBox [36 36 576 756]。當初做那層文字層的人,把像素位置除以點陣圖寬度、乘上頁面寬度換算成頁面位置,這個做法假設可見區域從原點開始。在帶有 /Rotate 90 的頁面上,同一條公式錯得更離譜:點陣圖的 x 軸已經沿著頁面的 y 軸走,字詞整個落到頁面錯誤的區域

隱形文字層到底是什麼

掃描頁面是內容流繪出來的一大張影像,沒有東西可以選取、搜尋、複製或建立索引。可搜尋文字層在這張影像上頭加上普通的文字物件,並把它們的文字渲染模式設成 3——ISO 32000-1 §9.3.6(表 106)定義這個模式既不填充也不描邊:字形為了選取、搜尋與擷取而存在,檢視器卻不為它畫任何東西。做得好,讀者看到的是原始掃描圖,Ctrl+F 找到的字詞正好落在印刷的位置上

在 PDFium Component 裡,整件事就是一次呼叫:TPdf.ApplyOcrSearchLayer。它渲染每個選定的頁面,把像素交給 OCR 提供者,按信心分數過濾辨識出的字詞,再把倖存者以隱形文字物件寫回。頁面影像維持原樣:掃描圖不解碼、不重新編碼、也不被替換,JBIG2 或 CCITT G4 影像保住它抵達時被壓縮的位元組。這個方法隨 Small Business 與 Enterprise 版出貨,所以專案的搜尋路徑上要有 Lib\SmallBusiness,uses 子句裡要有 FPdfSmallBusiness;少了這個單元,呼叫會拋出 EPdfSmallBusinessRequired

PDFium Component:與未更動掃描頁對齊的隱形 OCR 文字層,讓選取與搜尋可用,而 PDF 影像保持逐位元組完全相同
帶不可見渲染模式的真文字物件疊在原始掃描上方;選取與搜尋因此精準落在印刷字上

撰寫 IPdfOcrProvider

辨識本身藏在一個介面後面。IPdfOcrProvider.RecognizePage 收到一個 TPdfOcrImage(頁碼、寬、高、stride、DPI、像素格式,以及存放由上而下 BGRA 列的 TBytes 緩衝區),外加一個取消權杖,然後回傳一組 TPdfOcrWord 記錄:Unicode 文字、0 到 1 之間的信心分數,以及以影像像素表示的四角四邊形。此版本附了一個現成的提供者,即 FPdfOcrTesseract 裡的 CreatePdfTesseractOcrProvider,它繫結到您自備的 Tesseract 程式庫與 traineddata 目錄。其他引擎——雲端 API 或商用 SDK——都透過像下面這樣的類別接進來:

uses
  System.SysUtils, PDFium, FPdfAsync, FPdfSmallBusiness;

type
  TMyOcrProvider = class(TInterfacedObject, IPdfOcrProvider)
  public
    function RecognizePage(const Image: TPdfOcrImage;
      const CancellationToken: IPdfCancellationToken;
      out Words: TPdfOcrWords; out ErrorMessage: string): Boolean;
  end;

function TMyOcrProvider.RecognizePage(const Image: TPdfOcrImage;
  const CancellationToken: IPdfCancellationToken;
  out Words: TPdfOcrWords; out ErrorMessage: string): Boolean;
var
  I, Count: Integer;
begin
  // 底下的 Engine* 常式代表您自己的 OCR 引擎繫結
  Count := EngineRecognize(Image.Pixels, Image.Width, Image.Height,
    Image.Stride, Image.Dpi);
  CancellationToken.ThrowIfCancelled;   // 讓取消以取消的身分被回報

  SetLength(Words, Count);
  for I := 0 to Count - 1 do
  begin
    Words[I].Text := EngineWordText(I);
    // 許多引擎以 0..100 回報;文字層期望 0..1
    Words[I].Confidence := EngineWordConfidence(I) / 100;
    Words[I].Quad := TPdfOcrQuad.FromRectangle(
      EngineLeft(I), EngineTop(I), EngineRight(I), EngineBottom(I));
  end;
  ErrorMessage := '';
  Result := True;
end;

把 Tesseract 的 87.5 原樣傳回去的提供者,會讓每個字詞都被拒收。至少 Tesseract 是把字詞信心當百分比回報,內建的配接器回傳前會先除下來;自訂提供者也必須照做,因為 ApplyOcrSearchLayer 把高於 1 的信心分數當成無效輸入。知道要往哪看之後,症狀一目了然:Report.RejectedWordCount 等於 Report.DetectedWordCount,而存出來的檔案裡一個文字都沒有

呼叫權杖這件事則有另一個理由。如果提供者發現取消,只是單純回傳 False,該頁會被記成 popsFailed,附上您設定的訊息。改呼叫 ThrowIfCancelled 會拋出 EPdfOperationCancelled,文字層會接住它並記成 popsCancelled,同時設定 Report.Cancelled 並停止迴圈。提供者內的權杖絕不會是 nil;呼叫端沒傳時,會補上一個永不取消的權杖

四邊形,以及文字層拒收的字詞

掃描圖很少與頁面擺正,稍微歪斜的紙頁上,一個字詞佔的就是平行四邊形。TPdfOcrQuad 為這種情況備了 TopLeft、TopRight、BottomRight 與 BottomLeft 四個點,只回報方框的引擎則可用 FromRectangle 建出軸對齊版本。字詞會被跳過並計入 RejectedWordCount 的情況包括:文字為空或超過 MaxWordCharacters;信心分數是 NaN、低於 MinConfidence 或高於 1;任一角落在點陣圖之外;或是四邊形在映射後塌陷成寬度不足 0.01 pt 的細條

等比例縮放為何會放錯 OCR 字詞的位置

只有在頁面沒有 /Rotate 項目、且 CropBox 從 (0, 0) 開始時,等比例縮放才會正確。很多掃描檔至少違反一條:橫向的紙頁常被存成帶 /Rotate 設定的直向頁面,而有人在編輯器裡修掉邊界時,裁切框就跟著偏移。開頭的例子還算輕微;一旦有旋轉,誤差就不再是偏移量,而是軸整個對調

ApplyOcrSearchLayer 把四個角逐一送過 FPDF_DeviceToPage,用的正是產生提供者所見像素的同一組點陣圖尺寸與旋轉。因此旋轉與裁切框偏移都由渲染器用的同一個變換處理。角落進去前會先化成整數像素,在預設 300 DPI 下這是 0.24 pt 的量化步進,遠低於選取醒目提示能呈現的任何程度

從映射後的點來看,左下、右下與左上三個角定義出一個仿射矩陣。三個點足以表達位置、縮放、旋轉與剪切,這也是第四個角只用於驗證、不參與擬合的原因。文字物件以字級 1 建立,量出實際邊界後,再用矩陣把量到的邊界貼到目標四邊形上。用四邊形高度去猜字級,會隨每種字體的上升與下降部而漂移;先量再貼,貼合結果就與 Options.FontName 指定的字體無關

PDFium Component:FPDF_DeviceToPage 逐一映射 OCR 詞的四個角,讓隱形文字四邊形在旋轉的掃描 PDF 頁面上保持準確——直接的比例縮放會失準
單字的每個角都走過渲染器用過的同一套裝置對頁面變換;旋轉與偏移的裁剪框因此挪不動隱藏文字

即使什麼都不畫,字型對擷取仍然有影響。TPdfOcrOptions.Default 把它設成 Arial。若載入不到這個字型,文字層會退回標準的 Helvetica——標準 14 字型之一,其內建編碼只涵蓋拉丁文字。要輸出西里爾、希臘或 CJK 文字時,請把 FontName 設成已安裝、且涵蓋該文字系統的字型

執行文字層並讀取報告

只有在沒有頁面失敗、也沒有取消發生時,ApplyOcrSearchLayer 才回傳 True。拿這個回傳值決定要不要存檔,是錯的開關。ContinueOnError 維持預設 True 時,一份 300 頁、只有一頁讀不出來的工作會回傳 False,但其餘 299 頁都帶了正確的文字層,失敗那頁也已經復原成原樣。存檔與否請看報告:

var
  Pdf: TPdf;
  Options: TPdfOcrOptions;
  Report: TPdfOcrReport;
  Cancel: IPdfCancellationTokenSource;
  I: Integer;
begin
  Cancel := TPdfCancellationTokenSource.New;  // 放在「取消」按鈕搆得到的地方
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'scanned-contract.pdf';
    Pdf.LoadDocument;

    Options := TPdfOcrOptions.Default;      // 300 DPI、MinConfidence 0.5、Arial
    Options.MinConfidence := 0.6;
    Options.MaxTotalPixels := Int64(4000) * 1000 * 1000;

    Pdf.ApplyOcrSearchLayer(TMyOcrProvider.Create, Options, Report,
      Cancel.Token);

    for I := 0 to High(Report.Pages) do
      if Report.Pages[I].Status = popsFailed then
        Writeln(Format('page %d failed: %s',
          [Report.Pages[I].PageNumber, Report.Pages[I].ErrorMessage]));
    Writeln(Format('%d inserted, %d rejected, %d skipped, %d failed',
      [Report.InsertedWordCount, Report.RejectedWordCount,
       Report.SkippedPageCount, Report.FailedPageCount]));

    if not Report.Cancelled and (Report.InsertedWordCount > 0) then
      Pdf.SaveAs('scanned-contract-searchable.pdf');
  finally
    Pdf.Free;
  end;
end;

取消之後不存檔是個判斷題,這裡選擇不存。被取消的工作會留下一個前半可搜尋、後半空白的檔案,而 PDF 裡沒有任何東西告訴下一位讀者文字層到哪裡停。之後整份文件重跑一次,比解釋「為什麼檔案只索引了一半」便宜

SkipPagesWithText 預設 True,會檢查頁面是否已經萃取得出任何字元。這讓數位原生頁面不必進 OCR,避免處理過的檔案被加上第二層,也讓同一份輸出重跑一次毫無作用。代價是只要有一個真字元就算數:掃描圖上若有一個以真實文字蓋上去的 Bates 編號,就會被回報為 popsSkippedExistingText,拿不到文字層。那類典藏檔需要 SkipPagesWithText := False,並用 FirstPage 與 LastPage 小心圈出頁面範圍,否則先前處理過的頁面會多出一層重複的文字層,萃取時每個字詞都出現兩次

ApplyOcrSearchLayer 頁面管線:信心分數過濾、預算上限、取消與逐頁回滾,用於在 Delphi 對掃描 PDF 做 OCR 處理
信心分數過濾把薄弱的字詞擋在索引外,中途失敗的頁面則會把已插入的文字物件重新移除

像素預算、取消與逐頁回滾

敵意文件、或者只是大得離譜的文件,能灌大的每個量在 TPdfOcrOptions 裡都有上限,而像素檢查在任何點陣圖配置之前就先跑。渲染尺寸是 Ceil(PageWidth * Dpi / 72) 乘 Ceil(PageHeight * Dpi / 72),所以這些數字可以事先算出來:

頁面(300 DPI)點陣圖像素
US Letter,612 × 792 pt2550 × 33008,415,000
A4,595 × 842 pt2480 × 35098,702,320
A3,842 × 1191 pt3509 × 496317,415,167
A0,2384 × 3370 pt9934 × 14042139,493,228

預設值是單頁 1 億像素、整個工作 10 億。因此一張 300 DPI 的 A0 圖面自己就會超過 MaxPixelsPerPage。整體預算會比單頁預算先用完:Letter 每頁 8,415,000 像素,118 頁還擠得進 10 億,第 119 頁就會失敗,訊息指名 MaxTotalPixels,之後每一頁也一樣。長篇掃描典藏請像上面的範例那樣調高 MaxTotalPixels,或用 FirstPage 與 LastPage 把工作切成段落。被跳過的頁面不會渲染,也不計入。內附的 Tesseract 配接器另有一個自己的限制 TPdfTesseractOptions.MaxPixels,預設 16,777,216;300 DPI 的 A3 剛好超過一點,所以 A3 批次得調高配接器限制,或把 DPI 降下來

DPI 必須落在 36 到 1200 之間。從 300 加倍到 600,點陣圖變四倍,每個像素要 4 位元組,一頁 Letter 的 BGRA 就從約 34 MB 漲到約 135 MB。對一般辦公室掃描,300 DPI 在辨識品質與記憶體之間取得平衡;600 留給小字與註腳,不值得整批典藏都開。字詞數量由 MaxWordsPerPage 與 MaxTotalWords 封頂,回傳字詞數超過頁面上限的提供者會讓該頁失敗,而不是被截斷

取消權杖會傳到漸進式渲染、提供者呼叫與插入字詞的迴圈。400 頁的檔案在第 212 頁辨識途中取消,就會停在第 212 頁——前提是提供者尊重遞給它的權杖。Tesseract 配接器更進一步,向引擎註冊取消回呼,另外每頁預設有 60,000 ms 的逾時

故障隔離以頁為單位。文字層記下它插入的每個文字物件控制代碼,在該頁最後一個字詞放好之後呼叫一次 FPDFPage_GenerateContent。中間任何環節出錯——字型拒收某個字元、或取消訊號在迴圈半路到達——該頁已插入的物件會依相反順序移除並重新產生頁面內容,頁面於是回到原本只帶著舊有內容的狀態。之後迴圈按 ContinueOnError 決定繼續或停止,呼叫前作用中的頁面在呼叫後依然是作用頁面

驗證結果

兩項檢查涵蓋大部分會出錯的地方。第一項是視覺的:用 TPdf.RenderPage 把原始檔的某一頁和處理後檔案的同一頁渲染成相同尺寸,比較兩張點陣圖。預期結果是完全相同,因為模式 3 什麼都不畫,影像串流也沒被碰過;任何像素差異都代表動到頁面的是文字層以外的東西。第二項檢查字詞確實存在、而且落在掃描圖顯示的位置上:

procedure CheckOcrPage(Pdf: TPdf; PageNo: Integer; const Probe: WString);
const
  TEXT_MODE_INVISIBLE = 3;   // FPDF_TEXTRENDERMODE_INVISIBLE
var
  TextObjects: TPdfIntegerArray;
  I, Invisible, Hit: Integer;
  Box: TPdfRectangle;
begin
  Pdf.PageNumber := PageNo;
  TextObjects := Pdf.GetObjectsByType(otText);
  Invisible := 0;
  for I := 0 to High(TextObjects) do
    if Pdf.GetTextRenderMode(TextObjects[I]) = TEXT_MODE_INVISIBLE then
      Inc(Invisible);
  Writeln(Format('page %d: %d invisible text objects', [PageNo, Invisible]));

  Hit := Pdf.FindFirst(Probe);
  if Hit >= 0 then
  begin
    Box := Pdf.CharacterRectangle[Hit];
    Writeln(Format('"%s" starts at x=%.1f, y=%.1f pt',
      [Probe, Box.Left, Box.Bottom]));
  end;
end;

挑一個您能在掃描圖上用眼睛找到的探測詞——標題或合計金額都行——把回報的座標跟它在渲染影像裡的位置對一對。開頭那個 CropBox 頁面,x 值應該從 36 起跳,絕不會接近零。擷取的部分在從 PDF 文件擷取文字有更深入的討論;渲染頁面做對齊疊圖見把 PDF 頁面轉成 JPEG;全篇使用的權杖模式則見可取消的漸進式渲染

OCR 文字層與渲染、文字擷取、頁面編輯共用同一個 TPdf 物件,在 Delphi、C++Builder 與 Lazarus 上皆可使用。版本差異與完整 API 清單見PDFium Component for Delphi 產品頁