Initializing the Inference

This page lists the control nodes of a module and describes how to run an inference. The nodes of the image stream are listed in Inference on an Image Stream, the system nodes in 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:

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

Addresses

Table 1. Functionality Addresses
Functionality Permission Address

Inference

Read-Only

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/ready

Writable

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/request

Write-Only (method)

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/execute

Reset

Read-Only

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/reset/ready

Writable

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/reset/request

Write-Only (method)

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/reset/execute

Status

Read-Only

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/status/code

Read-Only

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/status/text

Result counter

Read-Only

hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/package-identifier

output/package-identifier grows by one with every successful inference, and only then.

Steps To Run Inference with External Image

To avoid repeating the entire address, in this section the invariant part containing the parent address has been replaced by XXX.

Thus, the address: hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/ready will be written as XXX/inference/ready.

Accordingly, the address: hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/request will be written as XXX/inference/request.

The application reads the image from the external address configured for the network, as it is when the inference starts. It does not check whether the image is new: an image that has not changed since the last inference is inferred again.

To start running inference:

  1. Check XXX/inference/ready = True.[1]

The application will automatically load configurations and setup neural networks. XXX/inference/ready is False while they are set up, while the image stream runs, without a licence, and after the settings were changed on the Data Layer (status/code -5, restart required). Please check XXX/status/code and the log for more information.

  1. Note the value of output/package-identifier.

  2. Set XXX/inference/request := True

  3. Wait until XXX/inference/ready = False. The inference is already running.

If the application hasn’t seen that the variable has changed:

  1. Make sure that only one process is accessing XXX/inference/request at a time.

  2. If the last inference failed, the module ignores every request but reset. Request a reset.

  3. Contact hdvisionsystems.

  1. Set XXX/inference/request := False

  2. Wait until XXX/inference/ready = True.

  3. Check that output/package-identifier has grown by one.
    status/code is 3 now, whether the inference succeeded or not: see Outcome of an Inference.
    You can now check result at hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/result

Steps to Run Inference with Input Image

To avoid repeating the entire address, in this section the invariant part containing the parent address has been replaced by XXX.

Thus, the address: hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/ready will be written as XXX/inference/ready.

Accordingly, the address: hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/request will be written as XXX/inference/request.

To set input image:

  1. Find the following address in the datalayer[2]: hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image

  2. Copy raw image into the following address: hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image

  3. Set corresponding image width and height and PixelFormat under the path hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image

For the RGB image, data layout is height, width, channel. In other words, the RGB value of a pixel is displayed next to each other in the raw data.

To start running inference:

  1. Check XXX/inference/ready = True.[1]

The application will automatically load configurations and setup neural networks. As long as XXX/inference/ready is True, you can run inference.

  1. Note the value of output/package-identifier.

  2. Set XXX/inference/request := True

  3. Wait until XXX/inference/ready = False. The inference is already running.

If the application hasn’t seen that the variable has changed:

  1. Make sure that only one process is accessing XXX/inference/request at a time.

  2. If the last inference failed, the module ignores every request but reset. Request a reset.

  3. Contact hdvisionsystems.

  1. Set XXX/inference/request := False

  2. Wait until XXX/inference/ready = True.

  3. Check that output/package-identifier has grown by one.
    status/code is 3 now, whether the inference succeeded or not: see Outcome of an Inference.
    You can now check result at hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/result

Execute a Method

Each function can also be started with a single write to its execute node instead of the handshake:

hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/<function>/execute

for inference, reset, list-result-files, load, save, save-result-image and remove. The write returns when the function has finished. It runs the same code as the handshake, and its results appear on the same output nodes.

Two results have to be kept apart:

  • Whether the function could be started at all is reported by the write itself. A refused write is never queued. The results have different names on the two Data Layers; their meaning is the same (see also Results of a method call):

    ctrlX Data Layer LumiScan Keryx Meaning What to do

    DL_OK

    Ok

    The function ran.

    Read control/status/code for its outcome.

    DL_TOO_MANY_OPERATIONS

    TooManyOperations

    Another function of the module runs, through the handshake or another execute.

    Retry.

    DL_INVALID_OPERATION_MODE

    InvalidOperationMode

    The function’s ready is False, for example inference while the image stream runs.

    Bring the module into the state first; retrying alone keeps failing.

    DL_RESOURCE_UNAVAILABLE

    ResourceUnavailable

    The application is shutting down; or the settings were changed on the Data Layer and a restart is required (status/code -5); or the module is in error after a failed inference. reset/execute is never refused for the error.

    After an error, run reset. After a settings change, restart the application, see Settings on the Data Layer.

  • Whether the function succeeded is reported on control/status/code and control/status/text. Unlike the handshake, execute leaves the outcome there: after inference/execute it is 0, 100001 or -1.

Keep each call short: a client gives up waiting after a few seconds (on LumiScan Keryx after 2 s by default, see Execute Methods). Inference on a large image or a slow device can take longer; use the handshake then.

Status Code Values

The values 0 to 3 and -1 to -5 are the module status codes common to the LumiScan applications, see Status Codes and Results. 100001 and 100002 are specific to AI Object Matching.

Table 2. Status Code Values Description
Status Code Number String Meaning

0

"ready"

The last functionality is successfully executed, the application is ready to execute the next functionality.

1

"settingUp"

The module or function is still setting up.

2

"running"

The function is currently running.

3

"waitingForClient"

Waiting for the client (usually for XXX/request to fall). Also the end of every inference requested through the handshake, whether it succeeded or not: see Outcome of an Inference.

100001

"ImageQueueEmpty"

The image could not be read: the image node (input/image, or the external image address) has no data, or could not be read. Not an error: provide an image and run the inference again.

100002

"StreamActive"

An inference was requested while the image stream runs. It is refused, not an error. See Inference on an Image Stream.

-1

"undefinedError"

Something went wrong and we did not create a special error code for it.

-2

"invalidSetting"

The supplied settings file could not be loaded.

-3

"invalidInput"

One of the input fields was not valid.

-4

"MissingLicense"

Make sure you have the correct licence installed.

-5

"restartRequired"

The settings files were changed on the Data Layer: restart the application. See Settings on the Data Layer.
1. The meaning of all status code values is explained in the Status Code Values table at the end of this chapter.
2. If the application is configured to use an input image, the specified address should be there.