Technical Article

Add a Searchable Text Layer to Scanned PDFs in Delphi

A search for an invoice number in a scanned PDF finds the hit, yet the highlight sits half an inch to the left of the printed digits and half an inch below them. Half an inch is 36 points, and the page in question has a CropBox of [36 36 576 756]. Whoever built that text layer turned pixel positions into page positions by dividing by the bitmap width and multiplying by the page width, which assumes the visible area starts at the origin. On a page carrying /Rotate 90 the same formula does worse: the bitmap's x axis now runs along the page's y axis, and the words land in the wrong part of the page entirely

What an invisible text layer actually is

A scanned page is one large image painted by the content stream. There is nothing to select, search, copy or index. A searchable text layer adds ordinary text objects on top of that image and sets their text rendering mode to 3, which ISO 32000-1 §9.3.6 (Table 106) defines as neither fill nor stroke: the glyphs exist for selection, search and extraction, and a viewer paints nothing for them. Done well, the reader sees the original scan and Ctrl+F finds words exactly where they are printed

In PDFium Component the whole job is one call, TPdf.ApplyOcrSearchLayer. It renders each selected page, passes the pixels to an OCR provider, filters the recognized words by confidence and writes the survivors back as invisible text objects. The page image is left as it is: the scan is not decoded, re-encoded or replaced, so a JBIG2 or CCITT G4 image keeps the exact compressed bytes it arrived with. The method ships in the Small Business and Enterprise editions, so the project needs Lib\SmallBusiness on the search path and FPdfSmallBusiness in a uses clause; without that unit the call raises EPdfSmallBusinessRequired

PDFium Component: An invisible OCR text layer aligned over an untouched scanned page makes selection and search work while the PDF image stays byte-for-byte identical
Real text objects with an invisible render mode sit over the original scan, so selection and search land exactly on the printed words

Writing an IPdfOcrProvider

Recognition itself sits behind one interface. IPdfOcrProvider.RecognizePage receives a TPdfOcrImage (page number, width, height, stride, DPI, pixel format and a TBytes buffer of top-down BGRA rows), plus a cancellation token, and returns an array of TPdfOcrWord records: Unicode text, a confidence between 0 and 1, and a four-corner quad in image pixels. The edition ships one ready-made provider, CreatePdfTesseractOcrProvider in FPdfOcrTesseract, which binds to a Tesseract library and traineddata directory that you supply. Any other engine, a cloud API or a commercial SDK, plugs in through a class like this one:

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* routines below stand for your own OCR engine binding
  Count := EngineRecognize(Image.Pixels, Image.Width, Image.Height,
    Image.Stride, Image.Dpi);
  CancellationToken.ThrowIfCancelled;   // report a cancel as a cancel

  SetLength(Words, Count);
  for I := 0 to Count - 1 do
  begin
    Words[I].Text := EngineWordText(I);
    // Many engines report 0..100; the layer expects 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;

A provider that passes Tesseract's 87.5 straight through gets every word rejected. Tesseract, for one, reports word confidence as a percentage, and the bundled adapter divides it down before returning; a custom provider has to do the same, because ApplyOcrSearchLayer treats a confidence above 1 as invalid input. The symptom is unmistakable once you know to look: Report.RejectedWordCount equals Report.DetectedWordCount and the saved file has no text at all

The token call matters for a different reason. If the provider notices cancellation and simply returns False, the page is recorded as popsFailed with whatever message you set. Calling ThrowIfCancelled raises EPdfOperationCancelled instead, which the layer catches and records as popsCancelled, with Report.Cancelled set and the loop stopped. The token is never nil inside a provider; when the caller passes none, a never-cancelled token is supplied

Quads, and words the layer refuses

Scans are rarely square to the page, so a word on a slightly skewed sheet occupies a parallelogram. TPdfOcrQuad carries TopLeft, TopRight, BottomRight and BottomLeft points for exactly that case, and FromRectangle builds the axis-aligned version for engines that only report boxes. A word is skipped and counted in RejectedWordCount when its text is empty or longer than MaxWordCharacters, when its confidence is NaN, below MinConfidence or above 1, when any corner falls outside the bitmap, or when the quad collapses to a sliver narrower than 0.01 pt after mapping

Why proportional scaling misplaces OCR words

Proportional scaling is correct only when the page has no /Rotate entry and its CropBox starts at (0, 0). Plenty of scans fail one of those conditions: a landscape sheet is often stored as a portrait page with /Rotate set, and crop boxes get offset when someone trims the margins in an editor. The opening example is the mild failure; with rotation the error stops being an offset and becomes a swapped axis

ApplyOcrSearchLayer sends each of the four corners through FPDF_DeviceToPage, using the same bitmap size and rotation that produced the pixels the provider saw. Rotation and crop-box offsets are therefore handled by the same transform the renderer used. Corners are rounded to whole pixels on the way in, which at the default 300 DPI is a quantization step of 0.24 pt, far below anything a selection highlight can show

From the mapped points, the bottom-left, bottom-right and top-left corners define an affine matrix. Three points are enough to express position, scale, rotation and shear, which is why the fourth corner is only validated, never used for fitting. The text object is created at a font size of 1, its real bounds are measured, and the matrix maps those measured bounds onto the target quad. Guessing a point size from the quad height would drift with every font's ascent and descent; measuring first makes the fit independent of the font that Options.FontName names

PDFium Component: FPDF_DeviceToPage maps each OCR word corner individually so invisible text quads stay accurate on rotated scanned PDF pages where naive proportional scaling misses
Each word corner travels through the same device-to-page transform the renderer used, so rotation and offset crop boxes cannot displace the hidden text

The font still matters for extraction even though nothing is drawn. TPdfOcrOptions.Default sets it to Arial. If that font cannot be loaded, the layer falls back to standard Helvetica, one of the standard 14 fonts, whose built-in encoding covers Latin text only. For Cyrillic, Greek or CJK output, set FontName to an installed font that covers the script

Running the layer and reading the report

ApplyOcrSearchLayer returns True only when no page failed and nothing was cancelled. That return value is the wrong thing to gate the save on. With ContinueOnError left at its default of True, a 300-page job with one unreadable page returns False while 299 pages carry a correct layer, and the failed page has already been put back the way it was. Gate the save on the report instead:

var
  Pdf: TPdf;
  Options: TPdfOcrOptions;
  Report: TPdfOcrReport;
  Cancel: IPdfCancellationTokenSource;
  I: Integer;
begin
  Cancel := TPdfCancellationTokenSource.New;  // keep it where a Cancel button can reach it
  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;

Not saving after a cancel is a judgment call, and it is the one made here. A cancelled job leaves a file that is searchable for the first part and blank for the rest, and nothing in the PDF tells the next reader where the layer stops. Re-running the whole document later is cheaper than explaining a half-indexed archive

SkipPagesWithText defaults to True and checks whether the page already yields any extractable characters. That keeps born-digital pages out of OCR, prevents a second layer on files that were processed before, and makes a repeated run over the same output a no-op. The flip side is that a single real character counts: a scan with a Bates number stamped as real text is reported as popsSkippedExistingText and gets no layer. Archives built that way need SkipPagesWithText := False and a careful page range through FirstPage and LastPage, otherwise previously processed pages acquire a duplicate layer and extraction returns every word twice

ApplyOcrSearchLayer page pipeline with confidence filtering, budget ceilings, cancellation and per-page rollback for OCR processing scanned PDFs in Delphi
Confidence filtering keeps weak words out of the index, and a page that fails midway has the text objects inserted on it removed again

Pixel budgets, cancellation and per-page rollback

Every quantity a hostile or merely enormous document can inflate has a ceiling in TPdfOcrOptions, and the pixel checks run before any bitmap is allocated. The render size is Ceil(PageWidth * Dpi / 72) by Ceil(PageHeight * Dpi / 72), so the numbers can be worked out in advance:

Page at 300 DPIBitmapPixels
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

The defaults are 100 million pixels per page and 1 billion across the job. An A0 drawing at 300 DPI therefore exceeds MaxPixelsPerPage by itself. The job-wide budget runs out sooner than the per-page one: at 8,415,000 pixels per Letter page, 118 pages fit under 1 billion and page 119 fails with a message naming MaxTotalPixels, and so does every page after it. For long scanned archives, raise MaxTotalPixels as the example above does, or split the work into ranges with FirstPage and LastPage. Skipped pages are never rendered and do not count. The bundled Tesseract adapter adds its own limit, TPdfTesseractOptions.MaxPixels, which defaults to 16,777,216; an A3 sheet at 300 DPI is just over that, so A3 batches need the adapter limit raised or the DPI lowered

DPI must lie between 36 and 1200. Doubling it from 300 to 600 quadruples the bitmap, and each pixel costs 4 bytes, so a Letter page goes from about 34 MB of BGRA to about 135 MB. For ordinary office scans 300 DPI balances recognition quality against memory; 600 is worth it for small print and footnotes, not for whole archives. Word counts are capped by MaxWordsPerPage and MaxTotalWords, and a provider that returns more words than the page allows fails that page instead of being truncated

The cancellation token reaches the progressive render, the provider call and the loop that inserts words. Cancelling during recognition of page 212 of a 400-page file stops on page 212, provided the provider honors the token it was handed. The Tesseract adapter goes one step further and registers a cancel callback with the engine, alongside a per-page timeout of 60,000 ms by default

Containment is per page. The layer keeps the handle of every text object it inserts and calls FPDFPage_GenerateContent once, after the last word on that page is placed. If anything fails in between, a font that refuses a character or a cancel arriving mid-loop, the objects already inserted on that page are removed in reverse order and the page content is regenerated, so the page goes back to carrying only what it had before. The loop then continues or stops according to ContinueOnError, and whichever page was active before the call is active again afterwards

Checking the result

Two checks cover most of what can go wrong. The first is visual: render one page from the original file and the same page from the processed file at the same size with TPdf.RenderPage, then compare the bitmaps. Expected: identical, because mode 3 paints nothing and the image stream was not touched; any pixel difference means something other than the text layer changed the page. The second checks that the words exist and sit where the scan shows them:

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;

Pick a probe word you can locate by eye on the scan, a heading or a total, and compare the reported coordinates with its position in a rendered image. On the CropBox page from the opening, the x value should start at 36 or more, never near zero. The extraction side is covered in more depth in extracting text from PDF documents, rendering pages for an alignment overlay in converting PDF pages to JPEG, and the token pattern used throughout in cancellable progressive rendering

OCR layering sits next to rendering, text extraction and page editing on the same TPdf object, in Delphi, C++Builder and Lazarus. Editions and the full API list are on the PDFium Component for Delphi product page