Data Layer Reference

Every address below is relative to

hdvisionsystems/lumiscan-object-finder/

Data Layer

LumiScan Object Finder offers its functions on the Data Layer under hdvisionsystems/lumiscan-object-finder.

On ctrlX OS (ctrlX CORE or ctrlX IPC), LumiScan Object Finder uses the ctrlX Data Layer.

On a PC with Windows 11 or Ubuntu 24.04, LumiScan Object Finder uses LumiScan Keryx.

The node addresses, types and call patterns are the same on both. LumiScan Object Finder 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/object-dir

string

read

Directory object pictures are read from, relative to the configuration directory

system/objects

string[]

read

Objects that can be searched for, one per .png

system/set-object-dir/execute

method

write

Switch to another object directory

system/set-object-dir/input/object-dir

string

read/write

Directory to switch to

system/create-object/execute

method

write

Save a crop of a live image as an object

system/create-object/input/input-image-address

string

read/write

Image to cut from

system/create-object/input/object-id

string

read/write

The object’s name; also the file name. Overwrites an existing one

system/create-object/input/crop/startX

int32

read/write

Left edge of the region to cut

system/create-object/input/crop/startY

int32

read/write

Top edge

system/create-object/input/crop/width

int32

read/write

Width, must be > 0

system/create-object/input/crop/height

int32

read/write

Height, must be > 0

system/create-object/output/object-path

string

read

File written by the last run

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/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. On ctrlX OS, one licence covers ten modules, see Module Management.

Per-module nodes

All addresses below are under <module-id>/find-object/.

Address Type Access Default Description

execute

method

write

-

Run one detection

input/input-image-address

string

read/write

(empty)

Address of the image node to search

input/object-id

string

read/write

(empty)

Object to look for. Required - an empty value is refused

input/confidence-threshold

float64

read/write

0.6

Smallest acceptable score, 0 to 1

input/nms-min-dist

float64

read/write

0.0

Minimum pixel distance between two matches

input/pyramid

uint8[]

read/write

[1,2]

Image pyramid levels to search at. Not a speed setting

input/result-coordinate

string

read/write

IMAGE

IMAGE or CROP

input/crop/startX

uint16

read/write

0

Left edge of the region to search

input/crop/startY

uint16

read/write

0

Top edge

input/crop/width

uint16

read/write

0

Width; 0 reaches the right edge

input/crop/height

uint16

read/write

0

Height; 0 reaches the bottom edge

input/preprocess/bin-size

int32

read/write

1

Search at 1/N resolution: faster, less precise. 1 disables it

input/preprocess/blur-sigma-x

float64

read/write

0.0

Gaussian blur in X; 0 or less disables it

input/preprocess/blur-sigma-y

float64

read/write

0.0

Gaussian blur in Y; 0 means same as X

input/preprocess/blur-kernel-size-x

uint32

read/write

0

Blur kernel in X; 0 computes it, else odd

input/preprocess/blur-kernel-size-y

uint32

read/write

0

Blur kernel in Y; 0 computes it, else odd

output/result

flatbuffers

read

empty

Matches of the last run

output/status-code

int16

read

0

Outcome as a number

output/status-text

string

read

(empty)

Outcome in words

Per-module image stream nodes (experimental)

All addresses below are under <module-id>/, beside find-object/. The stream searches each frame with the inputs of find-object, all but input/input-image-address. See Finding Objects on an Image Stream.

Address Type Access Default Description

control/subscribe/input/enable

bool

read/write

as applied

Stream mode: true runs the stream, false stops it

control/subscribe/input/address

string

read/write

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

read/write

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

read/write

as applied

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

control/subscribe/input/keep-latest-output

bool

read/write

as applied

true also writes each stream result to find-object/output/result

control/subscribe/execute

method

write

-

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

write

-

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

read/write

(empty)

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

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

as the inputs

read

stream in <module-id>.json

What control/subscribe/execute or control/unsubscribe/execute applied last

setting/settings-hash

string

read

-

Hash of what the results are made with, 16 hex digits

control/subscribe/output/stream/active

bool

read

false

true while the stream runs

control/subscribe/output/stream/result

flatbuffers

read

empty

One stream_object_matches per searched frame. Subscribe to receive each one

control/subscribe/output/stream/last-failure

string

read

(empty)

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

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

uint64

read

0

Milliseconds since the stream started

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

uint64

read

0

Frames the subscription delivered

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

uint64

read

0

Frames searched, each with a result

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

uint64

read

0

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

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

uint64

read

0

Frames that could not be searched

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

uint64

read

0

Frames lost before they arrived

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

uint64

read

0

Search time of all searched frames, 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 (Rejected, ctrlX: DL_INVALID_VALUE). When <module-id>.json cannot be written, both answer CreationFailed (ctrlX: DL_CREATION_FAILED) and change nothing. The stream nodes are the same in every consumer, see Streams.

The result flatbuffer

output/result carries hdv.object_find.Result:

Field Type Meaning

matches

Match[]

All matches, sorted by score descending

matches[].x, .y

int

Top left corner of the matched template, in pixels

matches[].width, .height

int

Size of the template that matched

matches[].score

float

0.0 to 1.0 similarity

matches[].object_id

string

The object that was found; the same on every match of one run

best_index

ulong

Index of the best match; 0 when there are none

best_score

float

Score of the best match; 0.0 when there are none

best_object_id

string

Object of the best match; empty when there are none

image_width, image_height

uint

The frame the coordinates are in

confidence_threshold

float

The threshold that was applied

timestamp

ulong

Microseconds since epoch, when the run completed

control/subscribe/output/stream/result carries hdv.stream.StreamObjectMatches (stream_object_matches, registered as types/hdvisionsystems/lumiscan-object-finder/stream_object_matches): lineage, where the frame came from, and result, the hdv.object_find.Result above.

Configuration file

The application settings file lumiscan-object-finder.json is in the configuration directory:

Platform File

ctrlX OS

<active solution>/lumiscan-object-finder/lumiscan-object-finder.json

PC (Windows)

%APP_RESOURCE_DIR%\etc\lumiscan-object-finder\lumiscan-object-finder.json; without APP_RESOURCE_DIR, C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-obj-find\etc\lumiscan-object-finder\lumiscan-object-finder.json

 
{
    "system": { "logLevel": "INFO" },
    "object-dir": "templates",
    "modules": [ { "id": "module-1", "advanced": false } ]
}

logLevel accepts TRACE, DEBUG, INFO, WARN, ERROR, FATAL and OFF, and is read at startup. Each module’s saved settings are in <module-id>.json beside it, and so are its image stream’s mode, source, queue size and keep-latest-output, under stream.

Starting from an Example (PC)

On a PC, the Object Finder writes an example of its settings into a folder of your choice, and ends without starting. For example, on Windows:

lumiscan-obj-find --generate-settings C:\work\object-finder-settings

Without a folder (-g alone) it writes into the current folder. The example is the application settings file lumiscan-object-finder.json, which names the module module-1, and the module file module-1.json beside it: every input of find-object 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-object-finder.schema.json, lumiscan-object-finder-module.schema.json, and stream.schema.json for the stream section of a module file. They describe every key the Object Finder reads - each input of find-object 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 Object Finder says which.

The Object Finder then names the folder it reads its settings from - on Windows by default C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-obj-find\etc\lumiscan-object-finder. Edit the example, copy it there, and start the Object Finder. See also Where the files are (Windows).