Functionalities

Each module configuration file listed in the application settings is one module. Its nodes are at hdvisionsystems/lumiscan-calibration/<module name>/, where the module name is the name of the module configuration file without .json, in lower case. A module offers two functions:

transform converts 2D image coordinates into 3D coordinates with the module’s lookup table.
reset reads the module configuration file and its lookup table again.

Each function can be started in two ways, and both lead to the same result:

the ready/request handshake, see General Concept of Handshake;
a single write to its execute method, see Execute methods.

A module can also transform a stream of points as they arrive, see Transforming a Stream (Experimental).

Data Layer

LumiScan Calibration offers its functions on the Data Layer under hdvisionsystems/lumiscan-calibration.

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

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

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

Addresses

All addresses below start with hdvisionsystems/lumiscan-calibration/<module name>/.

Table 1. Table 2: Functionality Addresses
Function	Address	Permission	Meaning
transform	`control/transform/ready`	Read-Only	`true` when a transform can be requested.
	`control/transform/request`	Writable	Requests a transform, see the handshake.
	`control/transform/execute`	Method	Runs one transform and returns when it has finished.
reset	`control/reset/ready`	Read-Only	`true` when a reset can be requested.
	`control/reset/request`	Writable	Requests a reset, see the handshake.
	`control/reset/execute`	Method	Runs one reset and returns when it has finished.
status	`control/status/code`	Read-Only	The status of the last function, see Status Code Values.
status	`control/status/text`	Read-Only	The same status as text.
input	`input/x-coordinate`	Writable	The `x` (pixel column) of one point.
	`input/y-coordinate`	Writable	The `y` (pixel row) of one point.
	`input/x-coordinate-array`	Writable	The `x` of each of several points.
	`input/y-coordinate-array`	Writable	The `y` of each of several points, as many as `input/x-coordinate-array` has.
output	`output/x-coordinate`, `output/y-coordinate`, `output/z-coordinate`	Read-Only	The 3D coordinates of the point on `input/x-coordinate` and `input/y-coordinate`.
	`output/x-coordinate-array`	Read-Only	The `x` of each point of the input arrays, in their order.
	`output/y-coordinate-array`	Read-Only	The `y` of each point of the input arrays.
	`output/z-coordinate-array`	Read-Only	The `z` of each point of the input arrays.
	`output/timestamp/seconds`	Read-Only	When the last transform finished, in whole seconds, by the clock of the device.
	`output/timestamp/milliseconds`	Read-Only	The milliseconds of that time, 0 to 999.
	`output/timestamp/macroseconds`	Read-Only	The microseconds of that time, 0 to 999.
	`output/package-identifier`	Read-Only	Counts the transforms that finished, starting from `1`. A new value means new outputs.
	`output/source`	Read-Only	The module name.
stream	`control/subscribe/…`, `control/unsubscribe/…`, `setting/stream/…`		On every module; without a `stream` section, a module streams plain. See Transforming a Stream.

The application itself reports at hdvisionsystems/lumiscan-calibration/system/:

found-modules: the names of the modules it serves.
status-text: "Initialized" once it serves its modules, or why it serves none.
meta/subscription-schema: what the node a module’s stream subscribes to may hold, as a JSON Schema. See What a source may hold.

Transforming points

One transform converts the point on input/x-coordinate and input/y-coordinate and every point of input/x-coordinate-array and input/y-coordinate-array. Leave the arrays empty to convert one point only.

Write the inputs.
Start the transform with the handshake or with control/transform/execute.
When it has finished, read the outputs. output/package-identifier has grown by one.

Good to know:

control/transform/ready is false while the module has no lookup table. Correct the module configuration file or the TIFF file, then reset the module.
If the two input arrays differ in length, the status is -10001 (inputXYSizeNotEqual). The single point is converted, but the output arrays, the timestamp and output/package-identifier are not written.
A point outside the lookup table is not reported as an error: the result is a value from the edge of the table. Keep the points within the image the table was made for.

Reloading the settings

A reset reads the module configuration file and the TIFF file it names again, and the next transform uses them. No restart of the application is needed. The reset also reads the stream section again, its source and stream mode included, and sets control/subscribe/input/… to it.

If the reset succeeds, the status is 0 and control/transform/ready is true.
If it fails, for example because the TIFF file is missing, the status is -2 (invalidSetting) and the module has no lookup table: control/transform/ready stays false until a reset succeeds. The log says why. The module does not keep transforming with the old table, so that a corrected file is never mixed with an outdated one.
A changed stream section is applied with the reset, see Configuring a stream.
Loading the example table took about 30 ms on a PC. A larger table, or a ctrlX CORE, can take longer.

Execute methods

control/transform/execute and control/reset/execute run their function once and return when it has finished. Write any value to them. The function uses the same inputs and writes the same outputs and status as the handshake.

Whether the function could be started at all is reported by the write itself. A rejected write is never queued. The results are named below as on the ctrlX Data Layer; LumiScan Keryx reports the same results under its own names, see Results of a method call:

Result Meaning What to do

Result	Meaning	What to do
OK	The function ran. Its outcome is on `control/status/code`.	Read the status and the outputs.
`DL_TOO_MANY_OPERATIONS`	Another transform or reset of this module is running, through the handshake or another `execute`.	Retry. The same write succeeds once the running function finishes.
`DL_INVALID_OPERATION_MODE`	`transform`: the module has no lookup table, or no licence. `reset`: no licence.	Do not retry in a loop. Correct the cause first: for a missing table, correct the files and reset.
`DL_RESOURCE_UNAVAILABLE`	The application is stopping.	Wait for the application to start again.

The function ran. Its outcome is on control/status/code.

Read the status and the outputs.

DL_TOO_MANY_OPERATIONS

Another transform or reset of this module is running, through the handshake or another execute.

Retry. The same write succeeds once the running function finishes.

DL_INVALID_OPERATION_MODE

transform: the module has no lookup table, or no licence. reset: no licence.

Do not retry in a loop. Correct the cause first: for a missing table, correct the files and reset.

DL_RESOURCE_UNAVAILABLE

The application is stopping.

Wait for the application to start again.

A running stream never makes an execute busy.

Status Code Values

control/status/code and control/status/text report the outcome of the last function. An error status stays until the next request: a module that waits for its next request does not overwrite it with 0. Codes 0 to -5 are the module status codes shared by the LumiScan applications, see Status Codes and Results; -10001 is LumiScan Calibration’s own.

Table 2. Table 3: Status Code Values
Status Code	String	Meaning
0	`"ready"`	The last function completed successfully, and the module is ready for the next one.
1	`"settingUp"`	The module is being initialized.
2	`"running"`	A function is running.
3	`"waitingForClient"`	The module waits for the client to set `request` back to `false`.
-1	`"undefinedError"`	An unspecified error occurred.
-2	`"invalidSetting"`	The module configuration file or its TIFF file could not be loaded, so the module has no lookup table. Correct them, then reset the module.
-3	`"invalidInput"`	One or more input values are invalid.
-4	`"missingLicense"`	The required licence is not available.
-5	`"restartRequired"`	The settings files were changed on the Data Layer: restart the application. See Settings on the Data Layer.
-10001	`"inputXYSizeNotEqual"`	`input/x-coordinate-array` and `input/y-coordinate-array` differ in length.