Ocr

Reads text from images and PDF files with the Tesseract OCR engine (LSTM mode), for scanned documents and screenshots. English (eng) and Dutch (nld) are bundled. Things to know: OCR is slow (seconds per page) and only as good as the scan; a clear, high resolution image works best. The image is converted to black and white before recognition. A call that cannot read the file is retried for about a minute before it fails.

• Kind Library, a global in every script
• Category Files & Documents
• Functions 3

Functions

• image string Recognises the text in an image or PDF file of the project (fetched from the Reflex server when it is not in the workspace) and returns it as one string.
• pages table Like `Ocr.image`, but returns a list with one text per page: a PDF gives one entry for every page, an image gives a list with one entry.
• timeout nil Sets how long the recognition of one image, or of one PDF page, may take, in seconds, for later Ocr.image and Ocr.pages calls.

image()

Ocr.image(image: string)→stringOcr.image(image: string, lang: string)→string

Recognises the text in an image or PDF file of the project (fetched from the Reflex server when it is not in the workspace) and returns it as one string. Images in any format Java can read (PNG, JPEG, GIF, BMP) are handled directly. A file whose name ends in ".pdf" is rendered page by page at 300 dpi and every page is recognised; the page texts are then joined with a form feed character ("\f"). Use `Ocr.pages` to get a list with one text per page. Pages that contain real text (not scans) are rendered as images too, so prefer a PDF text extractor for those. The language is a Tesseract code: "eng" (default) or "nld"; combinations such as "eng+nld" work when every part is installed. An unknown language raises an error that lists the available ones. A non-empty tessdata folder next to the agent replaces the bundled languages, so it must contain the ones you use. Each image or page has a time limit (default 30 seconds, see Ocr.timeout); when it is exceeded an error is raised. Read errors (missing file, not an image) are retried 60 times with a one second pause before the error is raised.

Parameters

image string

Path of the image or PDF file in the project

lang string optional

Tesseract language code: "eng" (default) or "nld"

Returns

string The recognised text; for a PDF the pages joined with "\f"

Example

local text = Ocr.image("scans/invoice.png", "nld")
local invoiceNumber = text:match("Factuurnummer:?%s*(%S+)")
Assert.notNil(invoiceNumber)

pages()

Ocr.pages(image: string)→tableOcr.pages(image: string, lang: string)→table

Like `Ocr.image`, but returns a list with one text per page: a PDF gives one entry for every page, an image gives a list with one entry. Language, time limit and error behaviour are the same.

Parameters

image string

Path of the image or PDF file in the project

lang string optional

Tesseract language code: "eng" (default) or "nld"

Returns

table List of strings, one per page

Example

local pages = Ocr.pages("scans/contract.pdf")
print(#pages)

timeout()

Ocr.timeout(sec: number)→nil

Sets how long the recognition of one image, or of one PDF page, may take, in seconds, for later Ocr.image and Ocr.pages calls. Default 30. Large scans may need more. Raises an error unless the value is from 1 to 300. Returns nothing, so it cannot be chained.

Parameters

sec number

Seconds per image or page, 1 to 300

Returns

nil Nothing.

Example

Ocr.timeout(120)
local text = Ocr.image("scans/large-contract.png")