---
title: "FAQ"
description: "Frequently asked questions about LumiScan Text Reader - image source and image quality, taking a reading, language models, the image stream, status codes and licensing."
product: "LumiScan Text Reader"
component: "lumiscan-text-reader"
version: "1.1.0"
display_version: "1.1.0.6"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/faq.html"
---

# FAQ – LumiScan Text Reader

Short answers to common questions about LumiScan Text Reader. Each entry links to the page with the details. Problems and error messages are described in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html).

> [!TIP]
> Each entry has a fixed anchor (for example `#faq-read-text`). To find an error message, search the [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html) page for it.

## Requirements and setup

### Which image source and pixel formats does the Text Reader need? {#faq-image-source}

- **Answer:** The application reads the image node of another application that runs on the **same device** - the same ctrlX CORE or ctrlX IPC, or the same PC (remote Data Layer access is not supported), normally LumiScan Cam Driver, for example `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. The node must provide `data` (raw, uncompressed uint8 pixel data), `width`, `height` and `pixel-type`. Supported pixel formats are `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` and `BayerRG12`; Bayer images are converted to colour and 12-bit images scaled down to 8 bit before reading. Any other pixel format is rejected with status code `-3`.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/requirements.html)

### What image quality does OCR need? {#faq-image-quality}

- **Answer:** 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;
  - text in focus and not glared out by the lighting;
  - text roughly upright, unless you use an orientation-detecting layout.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/requirements.html)

## Reading text

### How do I take a reading and evaluate the result? {#faq-read-text}

- **Answer:** Set `<module>/read-text/input/input-image-address`, write to `<module>/read-text/execute` (a blocking call) and check `output/status-code`. On `1`, read `output/result`: `text` is the whole reading as the engine laid it out and is **not** filtered by `min-score`; `words[]` holds each word with its `score` and box, filtered by `min-score`; `word_count`, `mean_score` and the `language`, `engine` and `layout` actually used are also reported. In production, check `word_count` and `words[0].score` before comparing `words[0].text` with the expected value.
- **More:** [Reading Text](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/reading-text.html), [How To: Read a Part Marking from a Camera Image](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/how-tos/read-a-part-marking-from-a-camera-image.html)

## Troubleshooting {#troubleshooting}

Problems and error messages are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html):

- [Status code 1, but no words](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-empty-reading)
- [The reading is empty although the text is clearly visible in a colour image](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-empty-colour-image)
- [Digits are read as letters (O for 0, S for 5)](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-digits-letters)
- [The reading contains extra words from the background](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-extra-words)
- [Dot-matrix or laser-etched marking reads badly](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-dot-matrix)
- [Reading is too slow](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-reading-too-slow)
- [Status code -2 (a setting is unusable)](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-status-minus-2)
- [Status code -3 (image cannot be read)](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-status-minus-3)
- [Status code -7 (OCR engine could not start)](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-status-minus-7)
- [A reading with AUTO_OSD or SPARSE_OSD is refused ("also needs osd.traineddata beside …")](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-osd-beside-language)
- [An uploaded model does not appear on system/languages](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-languages-list)
- [The text is read in another language than input/language](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#ts-wrong-language)
- [read-text answers -1 (busy) while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-stream-busy)
- [A stream frame fails with "the frame was read with 'eng' instead and its result dropped"](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-stream-language-dropped)
- [My settings or modules are gone after a restart](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-settings-lost)

## Language models

### How do I read another language? {#faq-add-language}

- **Answer:** English (`eng`) and `osd` ship with the application.
  - Download the `.traineddata` file from `github.com/tesseract-ocr/tessdata_fast` (smaller and quicker, the right default for part markings) or `tessdata_best`.
  - Upload it, without renaming, into the directory named on `system/tessdata-dir`: on ctrlX OS over the ctrlX file interface, on a PC by copying the file there.
  - Set `<module>/read-text/input/language` to the file name without `.traineddata`, for example `deu`. Codes are not all three letters (for example `chi_sim`).
  - The model is usable on the very next reading, with no restart. Uploading never removes the shipped models.
- **More:** [Language Models](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/language-models.html)

### I replaced a model file - does the reader use the new one? {#faq-replaced-model}

- **Answer:** Yes, from the next `read-text` on, without a restart. The recognition engine is built once per module and kept, but before every read the reader checks the model file’s size and time and, when either changed, compares its content with the one the engine was built from. A changed model is loaded again; the log says `The '<language>' model in '<directory>' changed on disk; loading it again`. An image stream also reads the next frame with the model as it is on disk.
- **Cause:** If a read fails with `-7` right after the replacement, the file could not be loaded yet - an upload still in progress, for example.
- **Solution:** Read again once the upload has completed; that read loads the new model.
- **More:** [Language Models](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/language-models.html)

## Image stream

### How do I read the text on every frame of a camera stream? {#faq-stream}

- **Answer:** Subscribe a module to the Cam Driver’s stream (experimental): write the camera’s stream folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, to `<module>/control/subscribe/input/address`, set `control/subscribe/input/enable` to `true` and write to `control/subscribe/execute`. Each frame is read with the inputs of `read-text`, and one result per frame is published on `control/subscribe/output/stream/result`. To read the latest result as a plain `read-text/output/result`, set `control/subscribe/input/keep-latest-output` to `true`.
- **More:** [Reading Text on an Image Stream](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/processing-an-image-stream.html), [Streams](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html)

## Status codes and errors

### How do I know whether a reading worked, and where is the reason for a failure? {#faq-status-codes}

- **Answer:** Check the sign of `output/status-code`: greater than 0 is success, `0` means the operation has not run since the application started, less than 0 means it failed and produced nothing. The reason is on `output/status-text`. A failed write to `execute` answers only with a status code (over REST, a bare `400`), so read `output/status-text` afterwards; the text is also in the application log: on ctrlX OS in the ctrlX Logbook or `journalctl`, on a PC in the application’s console output. `-1` means the module was busy; nothing was done and the previous reading is left alone. Every other `execute` empties `output/result` as it starts, so read the result before triggering the next reading.
- **More:** [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/execute-a-method.html), [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/execution-status.html), [Reading Text](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/reading-text.html)

## Modules, licensing and support

### Which licence do I need, and how many modules does it cover? {#faq-licence}

- **Answer:** One licence covers ten modules; the eleventh module acquires a second licence of the same key, and a module is refused with status `-11` when no licence on the device covers it. Purchase routes:
  - Bought from HD Vision Systems: the licence is on a LumiScan Key (Windows 11 or Ubuntu 24.04). One LumiScan Key is needed per device running the software at the same time; keys can be exchanged between devices.
  - Bought in the ctrlX Store for Windows 11: ctrlX WORKS plus a LumiScan Key.
  - Bought in the ctrlX Store for ctrlX OS (ctrlX CORE or IPC): a ctrlX licence, no key.
  - On ctrlX OS, the application shuts down shortly after starting if the licence is missing; the reason is written to the system log.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/requirements.html#licence), [Module Management](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/module-management.html), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)

### Where can I find more answers or get support? {#faq-support}

- **Answer:** See the site-wide [LumiScan FAQ](https://docs.hdvisionsystems.com/en/faq.html). Contact HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905; for licences, [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).
- **More:** [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)