Data Layer Reference

Complete node listing. All paths start with:

hdvisionsystems/lumiscan-template-finder/

Data Layer

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

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

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

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

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

Address pattern

hdvisionsystems/lumiscan-template-finder/
├── system/                              application-wide management
│   ├── modules
│   ├── template-dir                     the one directory templates live in
│   ├── templates                        what is in it
│   ├── set-template-dir/
│   ├── create-template/                 application-wide, not per module
│   ├── create-module/
│   ├── remove-module/
│   ├── save-current-modules/
│   ├── save-module-inputs/
│   └── meta/subscription-schema         what the stream's source must hold
└── <module-id>/                         one per configured instance, e.g. module-1
    ├── find-template/
    │   ├── execute
    │   ├── input/...
    │   └── output/{result, status-code, status-text}
    ├── control/subscribe/               the image stream (experimental)
    │   ├── execute
    │   ├── input/{enable, address, tag, queue-size, keep-latest-output}
    │   └── output/stream/...
    ├── control/unsubscribe/{execute, input/address}
    └── setting/{stream, settings-hash}

Every operation has execute, output/status-code and output/status-text. Anything else under output/ is present only where the operation has more to report.

A fresh installation serves one module, module-1, and more can be created at runtime. On ctrlX OS, one licence covers ten modules. See Module Management.

system

Node Type Description

system/modules

string array

The modules that currently exist

system/template-dir

string

Directory every module reads templates from and writes them to, relative to the configuration directory. Read-only - change it with set-template-dir

system/templates

string array

Templates available in that directory, without the .png extension. Read-only

system/set-template-dir/execute

method

Point the application at another template directory

system/set-template-dir/input/template-dir

string

Directory to switch to. It must already exist

system/create-template/execute

method

Cut a template out of a live image and save it into template-dir. Application-wide: the template is usable by every module. Its inputs and outputs are listed under system/create-template

system/create-module/execute

method

Create a module and its node subtree

system/create-module/input/module-id

string

Name of the module to create

system/remove-module/execute

method

Remove a module and its node subtree

system/remove-module/input/module-id

string

Name of the module to remove

system/save-current-modules/execute

method

Persist the module list, so the same modules return after a restart

system/save-module-inputs/execute

method

Persist one module’s inputs

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

string

Module whose inputs to persist

system/meta/subscription-schema

string

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. Read-only. Experimental

<module-id>/find-template

Inputs

Node Type Default Description

input/input-image-address

string

(empty)

Address of the image node to search

input/template-name

string

(empty)

Template to search for, as listed on system/templates. .png is appended when no extension is given

input/crop/startX

uint16

0

Left edge of the region to search, pixels

input/crop/startY

uint16

0

Top edge of the region to search, pixels

input/crop/width

uint16

0

Width of the region. 0 reaches the right edge

input/crop/height

uint16

0

Height of the region. 0 reaches the bottom edge

input/result-coordinate

string

IMAGE

IMAGE or CROP: which image the positions in the result are measured against

input/scale/min-scale

double

1.0

Smallest scaling factor

input/scale/max-scale

double

1.0

Largest scaling factor

input/scale/step-scale

double

1.0

Increment between scales

input/rotation/min-rot

double

0.0

Smallest rotation, degrees

input/rotation/max-rot

double

0.0

Largest rotation, degrees

input/rotation/step-rot

double

1.0

Increment between rotations, degrees

input/match-thresh

double

0.9

Minimum acceptable score, 0-1

input/match-mode

string

TM_SQDIFF_NORMED

Matching algorithm

input/use-grayscale

bool

true

Match on grayscale

input/preprocess/blur-sigma-x

double

1.0

Blur strength in X; 0 or less disables

input/preprocess/blur-sigma-y

double

0.0

Blur strength in Y; 0 means same as X

input/preprocess/blur-kernel-size-x

uint32

0

Blur kernel width; 0 derives from strength

input/preprocess/blur-kernel-size-y

uint32

0

Blur kernel height; 0 derives from strength

input/preprocess/bin-size

int32

1

Downsample factor; 1 disables

Outputs

Node Type Description

output/result

flatbuffer

Matches, sorted by confidence

output/status-code

int16

Execution status

output/status-text

string

Outcome in words

<module-id> image stream (experimental)

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

Inputs

Node 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 searched, 1-64

control/subscribe/input/keep-latest-output

bool

as applied

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

control/unsubscribe/input/address

string

(empty)

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

Methods

Node Type Description

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

Settings and outputs

Node Type Description

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

as the inputs

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

true while the stream runs

control/subscribe/output/stream/result

flatbuffer

One stream_template_matches per searched frame. Subscribe to receive each one

control/subscribe/output/stream/last-failure

string

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

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

uint64

Milliseconds since the stream started

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

uint64

Frames the subscription delivered

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

uint64

Frames searched, each with a result

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

uint64

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

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

uint64

Frames that could not be searched

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

uint64

Frames lost before they arrived

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

uint64

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.

system/create-template

Inputs

Node Type Default Description

input/input-image-address

string

(empty)

Address of the image node to cut from

input/crop/startX

int32

0

Left edge of the region, pixels

input/crop/startY

int32

0

Top edge of the region, pixels

input/crop/width

int32

0

Width of the region, pixels

input/crop/height

int32

0

Height of the region, pixels

input/template-name

string

(empty)

Name to save under, inside system/template-dir. Use lower case: only lower case .png files are listed

Outputs

Node Type Description

output/template-path

string

Path of the written file, relative to the configuration directory

output/status-code

int16

Execution status

output/status-text

string

Outcome in words

Result flatbuffer

output/result is a hdv.template_match.Result:

Field Type Description

matches

array of Match

One entry per occurrence, sorted by confidence

best_index

ulong

Index of the best match; always 0

best_score

float

Confidence of the best match; 0.0 if none

template_name

string

Template used

match_mode

string

Algorithm used

match_thresh

float

Threshold applied

image_width

uint

Width of the searched image

image_height

uint

Height of the searched image

timestamp

ulong

Microseconds since the epoch

Match:

Field Type Description

oriented_bounding_box

struct

center_x, center_y, width, height in pixels; angle in degrees

confidence

float

Score, 0-1

scale

float

Scaling factor of this match

rotation

float

Rotation of this match, degrees

control/subscribe/output/stream/result is a hdv.stream.StreamTemplateMatches (stream_template_matches, registered as types/hdvisionsystems/lumiscan-template-finder/stream_template_matches): lineage, where the frame came from, and result, the hdv.template_match.Result above.

Image node expected at input-image-address

The address must name an image node of another application on the same device - the same ctrlX CORE or ctrlX IPC, or the same PC - providing:

Child Type Description

data

array of uint8

Raw pixel data

width

uint64

Width in pixels

height

uint64

Height in pixels

pixel-type

string

GenICam pixel format name

An address inside this application is rejected with status code -2.

Status codes

See Execution Status for the full table. Negative is always an error; 0 means not yet run; positive means success. These are the finders' own codes, not the module status of the other LumiScan apps, see Execution status of the finders.