Description

LumiScan Text Reader reads printed text out of a camera image: part numbers, batch codes, date codes, labels.

You point it at an image node, tell it where the text is and what it may contain, and it reports the text along with a confidence for every word.

It runs on ctrlX OS (ctrlX CORE or ctrlX IPC) with the ctrlX Data Layer, and on a PC (Windows 11 or Ubuntu 24.04) with LumiScan Keryx, the Data Layer of HD Vision Systems for PCs. Its nodes are the same on both, see Data Layer Reference.

What is the same for every LumiScan app - how addresses are built, the handshake, execute and stream call patterns, status codes, settings and tools - is described in the LumiScan Keryx manual. This manual covers only what is specific to LumiScan Text Reader; its own nodes are listed in the Data Layer Reference.

If the marking is a code rather than text - Data Matrix, QR, Aztec, or a barcode - use the sibling application for that code. A code carries its own error correction, so it either decodes exactly or fails; reading it as text is both slower and less reliable.

Text is not a code, and that changes how you use it

This is the most important thing to understand before putting the application into production.

A code reader gives you a decoded value or nothing. An OCR reader always gives you something, and a misread looks exactly like a correct read:

  • every word comes back with a confidence rather than a guarantee;

  • an unfamiliar character is substituted rather than rejected - O for 0, S for 5;

  • the same label reads differently depending on how it was cropped and which characters were permitted.

The application is built around that. Two settings turn a plausible read into a trustworthy one, and both default to the permissive value so that a fresh installation shows you what it can actually see:

Setting What it does

input/characters/mode

Restricts what characters may be returned. A part number that is only ever digits, read with DIGITS, cannot come back with an O in it. This removes a whole class of errors rather than filtering them afterwards.

input/min-score

The confidence a word must reach to be reported. At the default 0 everything is reported, including guesses the engine has almost no faith in.

Set both before you rely on a reading. See Reading Accurately.

What a reading contains

output/result carries the whole text as the engine laid it out, and a per-word list with a confidence and a position for each word. They answer different questions:

  • read the whole text when the shape matters - a multi-line address, a label with a header;

  • read the word list when the content matters and a wrong answer is worse than no answer.

Also in the result: the language, engine and layout that were actually used. That last point matters because a language whose model is not installed is quietly replaced by English rather than refused - see Language Models.

An empty reading is not a failure

A run that finds nothing reports success with zero words. That is the normal answer for an empty carrier, a part turned the wrong way, or a label out of frame.

Branch on the word count, not on the status code, to decide whether a part carried text. Every reason a run could genuinely fail - a camera that is not answering, an unusable setting, an engine that could not start - is reported as a negative status code instead.

One case reads as empty when the text is perfectly legible: a colour image in which a photograph or other colourful scenery shares the frame. If a reading is empty and you can see the text in the image, set input/preprocess = GRAYSCALE before investigating anything else - see Reading Accurately.