Requirements
Licence
How LumiScan Text Reader is licensed depends on where you bought it and where it runs:
| Bought from | Runs on | Licensing |
|---|---|---|
HD Vision Systems |
Windows 11 or Ubuntu 24.04 |
The licence is held on your LumiScan Key. It is a one-time purchase and needs no renewal. |
ctrlX Store |
Windows 11 |
The licence is held in ctrlX WORKS. The LumiScan Key is required in addition; it protects the software against reverse engineering. |
ctrlX Store |
ctrlX OS (ctrlX CORE or IPC) |
ctrlX licence |
Each device on which LumiScan Text Reader runs at the same time needs its own LumiScan Key. Keys can be exchanged between devices.
How to install CodeMeter Runtime and how to request, renew and move licences is described in LumiScan Licensing.
On ctrlX OS, the application shuts down shortly after starting if the licence is missing; the reason is written to the system log.
A platform and its Data Layer
| Platform | Data Layer |
|---|---|
ctrlX OS (ctrlX CORE or ctrlX IPC) |
ctrlX Data Layer, provided by ctrlX OS |
a PC with Windows 11 or Ubuntu 24.04 |
LumiScan Keryx, the Data Layer of HD Vision Systems for PCs |
On ctrlX OS there is nothing to install for the Data Layer.
On a PC the application starts the LumiScan Keryx broker when none is running; installing and setting up LumiScan Keryx is described in LumiScan Keryx on a PC.
An image source on the same device
The application reads its images from another application’s Data Layer image node. That application must run on the same device as the Text Reader - the same ctrlX CORE or ctrlX IPC, or the same PC. Remote Data Layer access is not supported.
In practice this is LumiScan Cam Driver, but any application works as long as its image node provides these four children:
| Node | Type | Description |
|---|---|---|
|
array of uint8 |
Raw, uncompressed pixel data |
|
uint64 |
Image width in pixels |
|
uint64 |
Image height in pixels |
|
string |
GenICam pixel format name |
Language models
The application ships with English (eng) and the orientation model (osd) installed, which is
enough to read Latin-script text out of the box.
Other languages need their Tesseract .traineddata file placed in a directory the application can
read - on ctrlX OS the removable-media interface means a USB stick works - and
system/set-tessdata-dir pointed at it. See
Language Models.
Image quality
OCR is more demanding of the image than code reading is, and no setting recovers text the camera did not capture. As a rule of thumb:
-
characters at least 20 pixels tall, and 30 or more for small or noisy print;
-
good contrast between the marking and its background;
-
the text in focus, and not glared out by the lighting;
-
the text roughly upright, unless you enable an orientation-detecting layout.
Dot-matrix and laser-etched marking are harder than printed text. If engine = DEFAULT struggles
with them, LEGACY is worth trying before anything else.
Storage
The application stores nothing but its module list and their settings - a few kilobytes of JSON in the application’s configuration directory. On ctrlX OS that directory is part of the active solution. The language models are installed with the application and are not written to. Where the directory is on each platform is listed in Kept in the settings file.
The image stream (experimental) adds one folder beside them, settings-history/: one small JSON file
for each settings hash a module publishes, never deleted. See
Processing an Image Stream.
Timing
Reading is synchronous: the call to execute returns when the read has finished.
How long that takes is driven mostly by how much image the engine is given, which makes
input/crop the setting to reach for first when a cycle is too slow - a tight crop around the label
is both faster and more accurate than the whole frame. The AUTO_OSD and SPARSE_OSD layouts cost
noticeably more than the others, because they load a second model and work out the orientation
before reading.
See Reading Accurately.