Recursive AI

Map OCR boxes to PDF in C#

OneOcr is a free, open-source OCR library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Use ToPdf to place OCR boxes on the original PDF. Try it on scan.pdf from the zip.

ToPdf is a 2D affine matrix (A–F) that maps OneOcr’s top-left, Y-down page points into PDF user space.

Terminal
dotnet add package RecursiveAI.OneOcr
dotnet add package RecursiveAI.OneOcr.Pdf

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneOcr;
using OneOcr.Pdf;
 
var engine = OcrEngine.LoadBundled();
var pages = PdfOcr.Read("scan.pdf", engine);
var page = pages[0];
var map = page.ToPdf!.Value;
var word = page.Words.First();
var box = word.Box;
Console.WriteLine($"{word.Text} ({word.Source})");
double[] rows = [box.Top, box.Bottom];
double[] cols = [box.Left, box.Right];
foreach (var y in rows)
foreach (var x in cols)
{
    var pdfX = map.A*x + map.C*y + map.E;
    var pdfY = map.B*x + map.D*y + map.F;
    Console.WriteLine($"{pdfX:F2}, {pdfY:F2}");
}

Unzip the example, then dotnet run.

Prints the word, its source, and the PDF coordinates of its four corners, in top-left, top-right, bottom-left, bottom-right order as viewed on screen:

Text
Hello (Ocr)
85.55, 70.55
85.55, 115.66
101.39, 70.55
101.39, 115.66

The full program

The sample has no text layer. Its page dictionary sets /MediaBox [0 0 240 340], /CropBox [20 30 220 310] and /Rotate 90. The program maps the recognized word and checks that all four viewed page corners land on the expected crop corners.

C#
using System.Globalization;
using OneOcr;
using OneOcr.Pdf;
 
CultureInfo.CurrentCulture = CultureInfo.InvariantCulture;
var page = PdfOcr.Read("scan.pdf", OcrEngine.LoadBundled())[0];
var map = page.ToPdf ?? throw new InvalidOperationException("No PDF map");
var word = page.Words.First(w => w.Source == OcrSource.Ocr);
var box = word.Box;
Console.WriteLine($"{word.Text} ({word.Source})");
foreach (double y in new[] { box.Top, box.Bottom })
foreach (double x in new[] { box.Left, box.Right })
    Console.WriteLine($"{map.A*x + map.C*y + map.E:F2}, {map.B*x + map.D*y + map.F:F2}");
 
Console.WriteLine($"Viewed page: {page.Width} x {page.Height} pt");
var expected = new[] { (20.0, 30.0), (20.0, 310.0), (220.0, 30.0), (220.0, 310.0) };
int corner = 0;
foreach (double y in new[] { 0, page.Height })
foreach (double x in new[] { 0, page.Width })
{
    var actual = (map.A*x + map.C*y + map.E, map.B*x + map.D*y + map.F);
    if (actual != expected[corner++])
        throw new InvalidOperationException($"Unexpected crop corner {actual}");
    Console.WriteLine($"Page ({x}, {y}) -> PDF {actual}");
}

dotnet run prints:

Text
Hello (Ocr)
85.55, 70.55
85.55, 115.66
101.39, 70.55
101.39, 115.66
Viewed page: 280 x 200 pt
Page (0, 0) -> PDF (20, 30)
Page (280, 0) -> PDF (20, 310)
Page (0, 200) -> PDF (220, 30)
Page (280, 200) -> PDF (220, 310)

The snippet at the top expects at least one word. If no word is returned on your file, check page.Words.Count and read page.Diagnostics before indexing or calling First().

Variations

Get an enclosing PDF rectangle. In the full program, use the same map and box. Take the minimum and maximum after mapping so a rotated page doesn’t give you reversed edges.

C#
var corners = from x in new[] { box.Left, box.Right }
              from y in new[] { box.Top, box.Bottom }
              select (X: map.A*x + map.C*y + map.E,
                      Y: map.B*x + map.D*y + map.F);
var points = corners.ToArray();
var rect = (points.Min(p => p.X), points.Min(p => p.Y),
            points.Max(p => p.X), points.Max(p => p.Y));
Console.WriteLine(rect);

The short answer

For a PDF, call PdfOcr.Read and apply page.ToPdf to each corner of word.Box. The PDF bridge renders regions for OCR and scales the recognizer’s pixel boxes back to points before returning them. The matrix then maps points on the upright, cropped page back to PDF user space, the coordinate system used by the original page. Don’t apply another DPI conversion or flip Y again to these boxes.

Where is the origin of a PDF bounding box?

OneOcr’s PDF page model uses the top-left corner of the viewed crop box as (0, 0), with Y increasing downward and 72 points per inch. That is useful for drawing over a page image oriented the same way. It isn’t the original PDF user space. In the sample, the visible page is 280 points wide, not 240: the 200-by-280 crop rectangle is turned 90 degrees. Viewed (0, 0) lands at PDF (20, 30), and moving across the top edge of the view increases PDF Y, not PDF X. ToPdf also accounts for /UserUnit when the file sets it. A plain image OCR result has no PDF mapping of its own.

How do you convert pixel coordinates to PDF coordinates?

If you OCR a separate raster yourself, first check that it’s a render of the same upright crop, without padding or later rotations. Scale a raster X coordinate by page.Width / rasterWidth and Y by page.Height / rasterHeight, using the actual raster dimensions so rounding at render time doesn’t shift an edge. Then apply the page’s ToPdf to the result. If the image covers just a subsection, scale to that subsection and add its viewed-page offset first. An image resized or rotated after rendering needs that transform reversed as well. If you use PdfOcr.Read from the start, the bridge does the raster-to-page step for you.

Why don’t image and PDF bounding boxes line up?

Check whether the destination expects PDF user space, or coordinates on the already rotated page as displayed. The latter needs the viewed coordinates, not the mapped ones. Check word.Source, too: Ocr boxes are estimated from the ink, while TextLayer boxes come from glyph metrics. They needn’t trace the same edges even on the same page. Compare a known crop corner before changing your scaling or compensating for a word’s shape.

All oneocr recipes