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 recognised 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
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 quantisation 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
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 whilst 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 judgement 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
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 DPI | Bitmap | Pixels |
|---|---|---|
| US Letter, 612 × 792 pt | 2550 × 3300 | 8,415,000 |
| A4, 595 × 842 pt | 2480 × 3509 | 8,702,320 |
| A3, 842 × 1191 pt | 3509 × 4963 | 17,415,167 |
| A0, 2384 × 3370 pt | 9934 × 14042 | 139,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 honours 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