Module Configuration File

The module configuration settings are located in the <file name x>.json file (in this example, ai-object-matching-module.json), and are used to configure how the network module evaluates image data.

An example of module configuration JSON settings is shown below.

{
    "$schema": "schemas/lumiscan-ai-object-matching-module.schema.json",
    "meta":
    {
        "inputFileType": "LumiScan-CtrlX-AI-Object-Matching-Module",
        "inputFileVersion": "1.0.0",
        "targetMachine": "Example",
        "programName": "AI-Object-Matching",
        "programVersion": "1.0.0"
    },
    "name": "example",
    "neuralNetworkConfig": "models/model_description.json",
    "externalImagePath": "hdvisionsystems/lumiscan-cam-driver/camera1/output/image"
}

The description of the parameters mentioned above can be found in the following Table 6.

Table 1. Module Configuration: JSON Settings Description
Parameter	Description
meta	Place to set meta information: inputFileType and inputFileVersion are required.
inputFileType	In this case it must be: `LumiScan-CtrlX-AI-Object-Matching-Module`
inputFileVersion	Currently, only version 1.0.0 is supported.
targetMachine	Optional. Enter the name of the machine in use here to indicate that the current application configuration is being used for this particular machine.
programName	Optional. This parameter indicates by which application the current file is used. In this case: `AI-Object-Matching`
programVersion	Optional. Currently used program version.
name	A unique identifier for the neural network, which is also used as the network name in the datalayer address: `hdvisionsystems/lumiscan-ai-object-matching/<name>/...`. Only lower-case letters, digits, `-` and `_` are allowed. A module whose name has an upper-case letter or any other character is not loaded; the log says which name to write instead (`Network1` → `network1`).
neuralNetworkConfig	The file path to the neural network model parameters. These parameters are generated by the LumiScan Training Framework.
externalImagePath	Path to datalayer address that contains image. given image address must contains data, height, width, pixel-type. If not specified, the network module will create an additional path under `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input` to allow users to upload raw images to the datalayer without the need for an additional application.
stream	Experimental (from v2.2.0). Optional. Inference on an image stream, from one source: the settings below. Without this section, or without `enable` in it, the module is not in stream mode. `control/subscribe/execute` and `control/unsubscribe/execute` save `enable`, `address`, `tag`, `queueSize` and `keepLatestOutput` here before they apply them; the rest of the file stays as it was, comments included. The section has the same keys in every LumiScan application that subscribes to a stream. See Inference on an Image Stream.
stream.enable	`true`: the module starts in stream mode, and infers on the images of its source from its start. `false` by default. Needs `stream.address`: a module with `enable` set to `true` and no address is not loaded.
stream.address	The image stream to infer on: its folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. The module subscribes to the `frame` node of the folder, whose images carry their size, pixel format and lineage; the lineage of every result names the camera.
stream.tag	The tag on the module’s results: the module’s step in the lineage of each stream result carries it, so whoever reads a result downstream sees which module made it. Optional. Left out or empty: the module id, the last segment of the module’s address - `example` for `hdvisionsystems/lumiscan-ai-object-matching/example`.
stream.queueSize	How many images may wait for the inference: 1 to 64, 1 by default. 1 infers on the newest image; more keeps more images when the network falls behind. See The queue size.
stream.keepLatestOutput	`true`: each stream result also goes to the regular output (`output/result`, the timestamp and `output/package-identifier`). `false` by default. See Keeping the latest output.
stream.onEntry	The steps applied to each image as it arrives, before the inference, each an object with a `kind`. AI Object Matching has none yet: leave it out, or empty (`[]`). A step keeps the module from loading, because it would infer without the step its file asks for; the log names it.
stream.onExit	Reserved for steps applied to each result. Not read yet: the application logs a warning, and the steps are not applied.

After changing the parameters, the LumiScan AI Object Matching application should be restarted. A reset is enough for the stream section.

The stream layouts of earlier test builds are no longer read: the top-level subscriptions and streamQueueSize, and stream.subscriptions (a map of several sources). A module has one source now: move its address into stream.address, and streamQueueSize into stream.queueSize. The application logs a warning while a module file still has one of them.

Automatic Copying of External Image

To automatically copy an external image from another application, the application must provide an address containing the following parameters:

Table 2. Parameters of External Image
Address	Type
`<address>/data`	array of uint8_t
`<address>/height`	uint32_t
`<address>/width`	uint32_t
`<address>/pixel-type`	string, possible values: Mono8, RGB8

<address> is the image field specified in externalImagePath in the module configuration file.

This interface is designed and tested for use with the LumiScan Cam Driver. Compatibility with image data provided by other applications cannot be guaranteed.

Complete reference

Every setting of this file as its JSON Schema lumiscan-ai-object-matching-module.schema.json defines it, generated for version 2.1.0:

Setting Type Default Allowed values Description

Setting	Type	Allowed values	Description
`meta`	object		Required.
`meta/inputFileType`	string	not empty	Required.
`meta/inputFileVersion`	string	not empty	Required.
`meta/targetMachine`	string	not empty	Required.
`meta/programName`	string	not empty	Required.
`meta/programVersion`	string	not empty	Required.
`name`	string	pattern `^[a-zA-Z0-9_-]+$`	Required. only [a-Z], [0-9], '-' and '_' are allowed. Unique ID of the camera configuration. This is used to identify different camera on datalayer.
`neuralNetworkConfig`	string	not empty	Required. Path to network description file.
`externalImagePath`	string	not empty	If specified, the image will be loaded from the specified path instead of the ai-object-matching app managed input image.
`cropImage`	object		If specified, input image will be cropped and then used for inference. Note that the detected pixel position is related to original image. Use it if you want to accelerate the inference by reducing the image size.
`cropImage/startX`	number	≥ 0	Required.
`cropImage/startY`	number	≥ 0	Required.
`cropImage/width`	number		Required.
`cropImage/height`	number		Required.
`simulateResult`	string	not empty	If specified, the result will be simulated. This is useful for testing the application without the actual neural network.
`classIndexRemapping`	object		If specified, the detected object's index will be remapped to other index. Ke
`classIndexRemapping/<name>`	integer

meta

object

Required.

meta/inputFileType

string

not empty

Required.

meta/inputFileVersion

string

not empty

Required.

meta/targetMachine

string

not empty

Required.

meta/programName

string

not empty

Required.

meta/programVersion

string

not empty

Required.

name

string

pattern ^[a-zA-Z0-9_-]+$

Required. only [a-Z], [0-9], '-' and '_' are allowed. Unique ID of the camera configuration. This is used to identify different camera on datalayer.

neuralNetworkConfig

string

not empty

Required. Path to network description file.

externalImagePath

string

not empty

If specified, the image will be loaded from the specified path instead of the ai-object-matching app managed input image.

cropImage

object

If specified, input image will be cropped and then used for inference. Note that the detected pixel position is related to original image. Use it if you want to accelerate the inference by reducing the image size.

cropImage/startX

number

≥ 0

Required.

cropImage/startY

number

≥ 0

Required.

cropImage/width

number

Required.

cropImage/height

number

Required.

simulateResult

string

not empty

If specified, the result will be simulated. This is useful for testing the application without the actual neural network.

classIndexRemapping

object

If specified, the detected object's index will be remapped to other index. Ke

classIndexRemapping/<name>

integer

JSON Schemas

The application keeps the JSON Schemas of its settings files in its schemas folder; those copies always match the installed version. The schemas of LumiScan AI Object Matching 2.1.0 can also be downloaded: JSON Schemas of LumiScan AI Object Matching 2.1.0.

To have an editor such as Visual Studio Code check a copy of a settings file that you edit on your PC, point its $schema entry at the published schema:

{
  "$schema": "https://docs.hdvisionsystems.com/schemas/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching-module.schema.json",
  ...
}

Leave the $schema entry of the files on the device as the application wrote it.