Settings on the Data Layer

Data Layer

LumiScan AI Object Matching offers its functions on the Data Layer under hdvisionsystems/lumiscan-ai-object-matching.

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

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

The node addresses, types and call patterns are the same on both. LumiScan AI Object Matching offers:

ready/request handshakes
execute methods
a stream subscription to one source (experimental)

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

LumiScan AI Object Matching shows the settings it was started with on the Data Layer, on hdvisionsystems/lumiscan-ai-object-matching/system/settings. You can read them there without access to the configuration folder, and change them there: the application checks a change, saves it to its settings files, and asks to be restarted. hdvisionsystems/lumiscan-ai-object-matching/system/control/restart/execute restarts it.

This works the same on the ctrlX Data Layer and on LumiScan Keryx. The system node of the LumiScan applications is described in general in Settings, Modules and Restart. Where a method answers differently on the two Data Layers, both names are given below as ctrlX Data Layer / LumiScan Keryx.

What the node shows

settings holds one JSON document, as text:

the application settings file, lumiscan-ai-object-matching.json, as it was read;
in its modules list, each module configuration file’s content instead of the file’s name. "$file" names the file each module came from;
a module file that could not be read appears as {"$file": ..., "$error": ...}, where "$error" says why. That is also why the module did not start;
every value named password shows as "***".

For example:

{
  "$schema": "schemas/lumiscan-ai-object-matching.schema.json",
  "meta": { ... },
  "modules": [
    {
      "$file": "lumiscan-ai-object-matching-example-module.json",
      "$schema": "schemas/lumiscan-ai-object-matching-module.schema.json",
      "name": "ood",
      "neuralNetworkConfig": "models/ood-description.json",
      ...
    }
  ],
  "system": { ... }
}

Comments in the files are not shown.

The node shows the files as the application read them at start. A module’s reset reads its module file again (see General Concept of Handshake), and the node then shows that file as it was read. A reset applies only part of the file: the network and the stream section. What control/subscribe/execute and control/unsubscribe/execute save - the stream section - shows here at once.

Changing the settings

Read settings, change what you need, and write the whole document back. These rules apply:

Each module keeps its "$file". It must name one of the application’s module files: a module cannot be added here. To add one, see Adding and removing modules.
A module left out of modules is no longer listed in lumiscan-ai-object-matching.json. Its file stays where it is.
"***" for a password keeps the password the file has. Any other value replaces it.
A file whose content does not change is not written. A changed file is changed only where its content changed: comments and layout stay. A new key or list element goes after the last one there; a removed key goes with its line, a comment on that line included. Only an object that both gained and lost keys, or a list that lost an element, is written anew, without the comments inside it. The previous file is kept beside it as <file>.bak.
A key such as "_comment" is content like any other, so it is shown and kept.

The application checks the change before anything is written: the application configuration file and each changed module configuration file have to pass the checks the application makes at start. For example, the network description has to exist. An edit the check refuses, or that is not valid JSON, is answered with DL_INVALID_VALUE / Rejected. The reason is in the log, and nothing is written.

An edit that writes nothing answers DL_OK / Ok and changes nothing.

Restart required

A change that was saved takes effect only with the next start. Until then the application runs with settings that are no longer those of its files, so it stops working:

hdvisionsystems/lumiscan-ai-object-matching/system/restart-required is true;
hdvisionsystems/lumiscan-ai-object-matching/system/status-text says which files changed;
every module reports status -5 (restartRequired). It answers no request, and its ready signals are false;
every execute method of a module answers DL_RESOURCE_UNAVAILABLE / ResourceUnavailable. That includes reset, which would otherwise load part of the new settings;
a running image stream stops.

Only a restart ends this. A reset does not. The log has the message at error level.

Further changes are possible in the meantime. After a change, settings shows the files as saved, which is what the next start loads, not what the application runs with.

If a file could not be saved, the write answers DL_CREATION_FAILED / CreationFailed. Files changed before it stay changed, so the application requires a restart all the same. Correct the files, then restart.

Adding and removing modules

Three methods of hdvisionsystems/lumiscan-ai-object-matching/system handle modules, each under control/<method>/ as control/restart is. Each takes the module’s id, the name of its file without .json, in control/<method>/input/module-id:

Method What it does

Method	What it does
`create-module`	Writes the module file `<module-id>.json` with the JSON in `control/create-module/input/content`. The application checks it as it checks a changed module file. The module is not active yet, so nothing has to be restarted. An existing file is not overwritten: change it through `settings`.
`activate-module`	Adds `<module-id>.json`, which has to exist, to the `modules` list, after the application has checked the module. It runs from the next start, so the application then requires a restart (see Restart required).
`deactivate-module`	Takes `<module-id>.json` off the `modules` list. The file stays, so `activate-module` can list it again. It stops with the next start, so the application then requires a restart.

create-module

Writes the module file <module-id>.json with the JSON in control/create-module/input/content. The application checks it as it checks a changed module file. The module is not active yet, so nothing has to be restarted. An existing file is not overwritten: change it through settings.

activate-module

Adds <module-id>.json, which has to exist, to the modules list, after the application has checked the module. It runs from the next start, so the application then requires a restart (see Restart required).

deactivate-module

Takes <module-id>.json off the modules list. The file stays, so activate-module can list it again. It stops with the next start, so the application then requires a restart.

AI Object Matching runs one module. activate-module is refused while a module is active: deactivate it first.

Each method reports on control/<method>/output/status-code and control/<method>/output/status-text:

Code	Meaning
1	Done.
-2	The input or the module was refused: `status-text` says why. Nothing was written.
-6	A file could not be written.
-9	`activate-module`: there is no such file. `deactivate-module`: the module is not active.
-10	`create-module`: the file exists. `activate-module`: the module is active already.

The method answers DL_OK / Ok when it is done, DL_INVALID_VALUE / Rejected when it refused, and DL_CREATION_FAILED / CreationFailed when a file could not be written. For example, to add the module ood2:

Write the module’s JSON to hdvisionsystems/lumiscan-ai-object-matching/system/control/create-module/input/content and ood2 to control/create-module/input/module-id, then call control/create-module/execute.
Write ood2 to control/activate-module/input/module-id, then call control/activate-module/execute.
Call hdvisionsystems/lumiscan-ai-object-matching/system/control/restart/execute.

Restarting the application

hdvisionsystems/lumiscan-ai-object-matching/system/control/restart/execute ends the application and starts it again. It reads its settings files anew, which also applies changes made to the files by hand, and ends restart-required.

On ctrlX OS: the application ends, and ctrlX OS starts it again after about five seconds.
On a PC: the application starts itself again once it has released everything it held. It uses the same program, arguments and working folder. It is a new process, in the same console, and its output goes where the first one’s went.

The method answers DL_OK / Ok as soon as the restart has begun. The application’s nodes then disappear until it is up again: wait until hdvisionsystems/lumiscan-ai-object-matching/system/restart-required can be read again.

A restart is not tied to a change. It also restarts an application whose settings did not change.

Starting from an Example (PC)

On a PC, the AI Object Matching writes an example of its settings into a folder of your choice, and ends without starting:

Example (Windows)

lumiscan-ai-obj-mat --generate-settings C:\work\ai-object-matching-settings

Without a folder (-g alone) it writes into the current folder. The example is the application settings file lumiscan-ai-object-matching.json, its example module file lumiscan-ai-object-matching-example-module.json, the network description that module names, models\example-network-description.json, and the five schemas in schemas\ that an editor uses to check them. The model file the description names, example.onnx, is not part of it: that one is yours to supply. Existing files are never overwritten: when one of them is in the folder already, nothing is written and the AI Object Matching says which.

The AI Object Matching then names the folder it reads its settings from, by default (Windows) C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-ai-obj-mat\etc\lumiscan-ai-object-matching. Edit the example, copy it there, and start the AI Object Matching.