Data Layer Reference

Every address below is relative to

hdvisionsystems/lumiscan-area-detector/

Data Layer

LumiScan Area Detector offers its functions on the Data Layer under hdvisionsystems/lumiscan-area-detector.

On ctrlX OS (ctrlX CORE or ctrlX IPC), LumiScan Area Detector uses the ctrlX Data Layer.

On a PC with Windows 11 or Ubuntu 24.04, LumiScan Area Detector uses LumiScan Keryx.

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

Per-module nodes

All addresses below are under <module-id>/detect-area/.

Used by every method

Address Type Default Description

execute

method

-

Run one detection

input/input-image-address

string

(empty)

Address of the image node to search

input/method

string

FIXED

FIXED is the only one this version offers; anything else is refused

input/crop/startX

uint16

0

Left edge of the region to search

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/preprocess/method

string

NONE

NONE, LOG, DOG or DOH

input/preprocess/log/sigma-x

float64

1.0

Must be > 0

input/preprocess/log/sigma-y

float64

0.0

0 means equal to sigma-x

input/preprocess/log/kernel-size-x

uint32

0

0 computes it from the sigma, else odd

input/preprocess/log/kernel-size-y

uint32

0

0 computes it from the sigma, else odd

input/preprocess/dog/sigma-first

float64

1.0

Must differ from sigma-second

input/preprocess/dog/sigma-second

float64

2.0

Must differ from sigma-first

input/preprocess/dog/kernel-size-x

uint32

0

0 computes it from the sigma, else odd

input/preprocess/dog/kernel-size-y

uint32

0

0 computes it from the sigma, else odd

input/preprocess/doh/kernel-size

uint32

3

Must be 1, 3, 5 or 7

What counts as a region

Address Type Default Description

input/detect-dark

boolean

false

Dark regions on a light background

input/connectivity

int32

8

4 or 8; 8 joins diagonal neighbours

input/fill-holes

boolean

false

Measure a region as the shape its outline encloses

There is no area window to configure. Every region the detector separated is reported, however small or large, and whether one of them is too small to be a part or too large to be a single one is a decision about the parts — which belongs to whoever reads output/result.

The threshold

Address Type Default Description

input/method-specific/fixed/level

float64

128

The level itself, 0-255

The folder keeps its name so the address survives if the methods that took their level from the image come back.

Outputs

Address Type Description

output/result

flatbuffers

Regions of the last run

output/status-code

int16

Outcome as a number

output/status-text

string

Outcome in words

output/blob-labels/{data,width,height,pixel-type}

image (data is raw)

Mono16, one region number per pixel; 0 is background

The label image is whole-frame and holds the blobs[].label numbers, so a reported area can be traced to the pixels it was measured from. It is emptied when the next run starts. See The Label Image.

Analysing a scene

Under system/analyse-scene/ - it describes a picture, not a module. See Analysing a Scene.

Address Type Default Description

execute

method

-

Measure the image and report what a fixed level would have to be

input/input-image-address

string

(empty)

The image node to analyse; its own, not a module’s

input/crop/startX .. height

uint16

0

The region to analyse; all zero is the whole image

input/bin-size

int32

0

Measure a shrunk copy; 0 shrinks only what needs it, 1 forces full size

input/histogram-bins

int32

256

Buckets in output/histogram, 2-256. Not the same knob as bin-size

output/histogram

uint32[]

(empty)

Pixels per grey bucket, darkest first, at full size

output/recommended-settings

string[]

(empty)

node=value lines, relative to a module’s detect-area/input/

output/findings

string[]

(empty)

Why, in words, with the numbers in them

output/parts-are-dark

boolean

false

Whether the regions are darker than their background

output/parts-touching

boolean

false

Whether regions are really several parts stuck together

output/region-count

int32

0

Regions found

output/expected-region-count

int32

0

How many parts those regions look like they hold

output/illumination-spread

float64

0

[grey levels] Background variation across the frame

output/separability

float64

0

How cleanly the picture splits, 0 to 1

output/feature-thickness

float64

0

[pixel] Half the width of a typical feature

output/area-sensitivity

float64

0

[per grey level] How much the area moves with the threshold. Smaller is better; above 0.05 a fixed level is not safe to commission

Per-module image stream nodes (experimental)

All addresses below are under <module-id>/, beside detect-area/. The stream searches each frame with the inputs of detect-area, all but input/input-image-address, and publishes the measurements only: there is no stream counterpart of output/blob-labels. See Detecting Areas on an Image Stream.

Address Type Default Description

control/subscribe/input/enable

boolean

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

boolean

as applied

true also writes each stream result to detect-area/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

boolean

false

true while the stream runs

control/subscribe/output/stream/result

flatbuffers

empty

One stream_areas per searched frame. Subscribe to receive each one

control/subscribe/output/stream/last-failure

string

(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

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 searched, 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 searched

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

uint64

0

Frames lost before they arrived

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

uint64

0

Detection 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. When <module-id>.json cannot be written, both answer DL_CREATION_FAILED (on a PC CreationFailed) and change nothing.

The result flatbuffer

output/result carries hdv.area_detect.Result:

Field Type Meaning

blobs

Blob[]

All regions, sorted by area descending

blobs[].x, .y

float

[pixel] Centre of the region

blobs[].area

float

[pixel^2] Pixels the region covers, counted

blobs[].label

uint

Which region this is in output/blob-labels; 0 never occurs

blobs[].bbox_x/y/width/height

int

Tight box around the region

blob_count

uint

Number of regions

total_area

float

[pixel^2] Sum over all regions

largest_index

ulong

Index of the largest region

largest_area

float

[pixel^2] Its area

image_width, image_height

uint

The frame the coordinates are in

preprocess_method

string

NONE, LOG, DOG or DOH, as applied

timestamp

ulong

Microseconds since epoch

control/subscribe/output/stream/result carries hdv.stream.StreamAreas (stream_areas, registered as types/hdvisionsystems/lumiscan-area-detector/stream_areas): lineage, where the frame came from, and result, the hdv.area_detect.Result above. Its blobs[].label has no label image to look up.

Configuration file

The application settings file is lumiscan-area-detector.json in the application’s configuration directory:

Platform File

ctrlX OS

<active solution>/lumiscan-area-detector/lumiscan-area-detector.json, the active solution being /var/snap/rexroth-solutions/common/solutions/activeConfiguration

PC (Windows)

%APP_RESOURCE_DIR%\etc\lumiscan-area-detector\lumiscan-area-detector.json; without APP_RESOURCE_DIR, C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-areadetect\etc\lumiscan-area-detector\lumiscan-area-detector.json

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

logLevel accepts TRACE, DEBUG, INFO, WARN, ERROR, FATAL and OFF, 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 Area Detector writes an example of its settings into a folder of your choice, and ends without starting. On Windows:

lumiscan-areadetect --generate-settings C:\work\area-detector-settings

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

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