Data Layer Reference

Every address below is relative to

hdvisionsystems/lumiscan-text-reader/

Data Layer

LumiScan Text Reader offers its functions on the Data Layer under hdvisionsystems/lumiscan-text-reader.

On ctrlX OS (ctrlX CORE or ctrlX IPC), LumiScan Text Reader uses the ctrlX Data Layer.

On a PC with Windows 11 or Ubuntu 24.04, LumiScan Text Reader uses LumiScan Keryx.

The node addresses, types and call patterns are the same on both. LumiScan Text Reader offers:

How addresses are built, how to call functions, the status codes and the tools are described in LumiScan Keryx.

Application-wide nodes

Address Type Access Description

system/modules

string[]

read

The modules that exist right now

system/create-module/execute

method

write

Add a module

system/create-module/input/module-id

string

read/write

Name for the new module

system/remove-module/execute

method

write

Remove a module

system/remove-module/input/module-id

string

read/write

Module to remove

system/save-current-modules/execute

method

write

Persist the module list

system/save-module-inputs/execute

method

write

Persist one module’s settings

system/save-module-inputs/input/module-id

string

read/write

Module to save

system/tessdata-dir

string

read

Where to upload your own models; the first directory searched

system/tessdata-dirs

string[]

read

Every directory searched, in order

system/languages

string[]

read

Language codes found across all of them

system/set-tessdata-dir/execute

method

write

Use another upload directory

system/set-tessdata-dir/input/tessdata-dir

string

read/write

Directory to upload to and search first

system/refresh-languages/execute

method

write

Re-read the directories and update languages

system/meta/subscription-schema

string

read

What the node a module subscribes to must hold, as a JSON Schema (draft-04) of its JSON form: here a stream_image, the frame node of the stream folder, with lineage and image. The same for every module. Experimental

Every method also serves output/status-code and output/status-text.

system/tessdata-dir, system/tessdata-dirs and system/languages are read-only outputs of set-tessdata-dir and refresh-languages, so the listing can never describe a directory that is not in use. Note that languages is a listing only: reading with a newly uploaded model does not wait for a refresh. See Language Models.

Per-module nodes

All addresses below are under <module-id>/read-text/.

Address Type Default Description

execute

method

-

Run one reading

input/input-image-address

string

(empty)

Address of the image node to read

input/crop/startX

uint16

0

Left edge of the region to read

input/crop/startY

uint16

0

Top edge

input/crop/width

uint16

0

Width; 0 reaches the right edge

input/crop/height

uint16

0

Height; 0 reaches the bottom edge

input/language

string

eng

A code from system/languages

input/engine

string

DEFAULT

DEFAULT, LSTM, LEGACY or COMBINED

input/layout

string

SINGLE_BLOCK

See the table below

input/preprocess

string

NONE

NONE, GRAYSCALE or BINARIZE_OTSU

input/characters/mode

string

ALL_SYMBOLS

ALL_SYMBOLS, ALL_LETTERS, DIGITS, LOWERCASE_LETTERS, UPPERCASE_LETTERS, SPECIAL_SYMBOLS or CUSTOM

input/characters/allow

string

(empty)

Characters added to the set

input/characters/deny

string

(empty)

Characters removed from the set

input/min-score

float64

0.0

Confidence a word must reach to be reported, 0 to 1

output/result

flatbuffers

empty

text_read_result - the reading

output/status-code

int16

0

Outcome as a number; negative is always an error

output/status-text

string

(empty)

Outcome in words

Accepted input/layout values

SINGLE_BLOCK

One uniform block of text - the default

SINGLE_LINE

Exactly one line

SINGLE_WORD

Exactly one word

SINGLE_CHAR

Exactly one character

RAW_LINE

One line, with no structure analysis

AUTO

Find and segment text regions across the whole image

AUTO_OSD

As AUTO, and detect the orientation and script

SPARSE

Find text wherever it appears, assuming no layout

SPARSE_OSD

As SPARSE, and detect the orientation

SINGLE_COLUMN

A single column of text

SINGLE_BLOCK_VERT

A single block of vertically aligned text

CIRCLE_WORD

A single word arranged in a circle

Per-module image stream nodes (experimental)

All addresses below are under <module-id>/, beside read-text/. The stream reads each frame with the inputs of read-text, all but input/input-image-address. See Reading Text on an Image Stream.

Address Type Default Description

control/subscribe/input/enable

bool

as applied

Stream mode: true runs the stream, false stops it

control/subscribe/input/address

string

as applied

The one source, a camera’s stream folder, e.g. hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream. Another address replaces it

control/subscribe/input/tag

string

as applied

The tag on the module’s results: the module’s step in the lineage of each stream result carries it. Empty: the module id, e.g. module-1. A new tag keeps the source; the next result carries it

control/subscribe/input/queue-size

uint32

as applied

Frames that may wait while one is read, 1-64

control/subscribe/input/keep-latest-output

bool

as applied

true also writes each stream result to read-text/output/result

control/subscribe/execute

method

-

Check the inputs of control/subscribe together, save them in <module-id>.json as stream, then apply them. Writing an input alone changes nothing

control/unsubscribe/execute

method

-

Drop the source named by control/unsubscribe/input/address, which ends stream mode; the tag stays. Saved in <module-id>.json like a subscribe

control/unsubscribe/input/address

string

(empty)

The source to drop, as setting/stream/address shows it

setting/stream/{enable, address, tag, queue-size, keep-latest-output}

as the inputs

stream in <module-id>.json

What control/subscribe/execute or control/unsubscribe/execute applied last. Read-only

setting/settings-hash

string

-

Hash of what the results are made with, 16 hex digits. Read-only

control/subscribe/output/stream/active

bool

false

true while the stream runs

control/subscribe/output/stream/result

flatbuffers

empty

stream_texts - one per frame read. Subscribe to receive each one

control/subscribe/output/stream/last-failure

string

(empty)

Why the last frame that could not be read failed, naming the source by its address

control/subscribe/output/stream/statistics/elapsed-ms

uint64

0

Milliseconds since the stream started

control/subscribe/output/stream/statistics/received-frames

uint64

0

Frames the subscription delivered

control/subscribe/output/stream/statistics/processed-frames

uint64

0

Frames read, each with a result

control/subscribe/output/stream/statistics/skipped-frames

uint64

0

Frames pushed out of the queue, or waiting when the source was replaced or dropped

control/subscribe/output/stream/statistics/failed-frames

uint64

0

Frames that could not be read

control/subscribe/output/stream/statistics/lost-frames

uint64

0

Frames lost before they arrived

control/subscribe/output/stream/statistics/processing-us

uint64

0

Reading time of all frames read, summed, microseconds

The inputs of control/subscribe start with what is applied, and only control/subscribe/execute applies them. control/subscribe/execute is refused for stream mode without an address or a queue size outside 1-64, control/unsubscribe/execute for an address that is not the source. When <module-id>.json cannot be written, both answer DL_CREATION_FAILED (on a PC CreationFailed) and change nothing.

The result flatbuffer

output/result is registered as types/hdvisionsystems/lumiscan-text-reader/text_read_result.

Field Type Description

text

string

The whole reading, lines separated by newlines. Not filtered by min_score

words[].text

string

One recognised word

words[].score

float

Its confidence, 0 to 1

words[].bbox_x

int

Box around the word, in the coordinates of the region that was read

words[].bbox_y

int

words[].bbox_width

int

words[].bbox_height

int

word_count

uint

How many words are reported

mean_score

float

Average confidence over the reported words; 0 when there are none

min_score

float

The threshold that was applied

language

string

The language actually used

engine

string

The engine actually used

layout

string

The layout actually used

image_width

uint

The region that was read

image_height

uint

timestamp

ulong

Microseconds since the epoch, when the reading finished

control/subscribe/output/stream/result is registered as types/hdvisionsystems/lumiscan-text-reader/stream_texts: a hdv.stream.StreamTexts with lineage, where the frame came from, and result, the table above.

Starting from an Example (PC)

On a PC, the Text Reader writes an example of its settings into a folder of your choice, and ends without starting. On Windows:

lumiscan-text-read --generate-settings C:\work\text-reader-settings

Without a folder (-g alone) it writes into the current folder. The example is the application settings file lumiscan-text-reader.json, which names the module module-1, and the module file module-1.json beside it: every input of read-text with the value it has by default, except the image address, which is the Cam Driver’s camera1. Beside them, in schemas/, are the schemas the two files name in "$schema": lumiscan-text-reader.schema.json, lumiscan-text-reader-module.schema.json, and stream.schema.json for the stream section of a module file. They describe every key the Text Reader reads - each input of read-text with its type, its default and the range a run accepts - so an editor that understands JSON Schema can check the files and show what each value means. Copy the schemas folder along with the files: system/save-module-inputs keeps the "$schema" of a module file it saves. Existing files are never overwritten: when one of them is in the folder already, nothing is written and the Text Reader says which.

The Text Reader then names the folder it reads its settings from, on Windows by default C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-text-read\etc\lumiscan-text-reader. Edit the example, copy it there, and start the Text Reader. See also Where the files are.