FAQ

Short answers to common questions about LumiScan Calibration. Each entry links to the page with the details. Problems and error messages are described in Troubleshooting.

Each entry has a fixed anchor (for example #faq-status-codes). To find an error message, search the Troubleshooting page for it.

Getting started

What does LumiScan Calibration do?

Answer

It converts 2D image coordinates into the corresponding 3D coordinates on a calibrated plane, for example for robotic bin picking or object placement. The conversion uses calibration data from a TIFF file. The application runs on ctrlX OS (ctrlX CORE or ctrlX IPC) and on a PC with Windows 11 or Ubuntu 24.04. It is configured with JSON settings files, and is controlled through the Data Layer (inputs, outputs and status): the ctrlX Data Layer on ctrlX OS, LumiScan Keryx on a PC. From v2.1.0 a module can also transform a stream of points as they arrive (experimental).

More

Description, Requirements

How do I get the TIFF calibration file?

Answer

The TIFF file is generated from calibration images and provided by HD Vision Systems:

  • Contact HD Vision Systems to obtain a calibration plate.

  • Place the plate on the plane you want to calibrate.

  • Capture at least one image of the plate with the camera.

  • Send the images to HD Vision Systems; you receive the corresponding TIFF file.

More

TIFF File

How do I upload the TIFF file and configuration files?

Answer

On ctrlX OS, most data can be uploaded directly through the ctrlX Web UI. Alternatively use WebDAV, for example with WinSCP: select WebDAV as File protocol and TLS/SSL as Encryption, log in, navigate to /solutions/webdav/appdata and drag the files into the LumiScan Calibration application folder. On a PC, the files are ordinary files: copy them into the application’s settings folder (on Windows %APP_RESOURCE_DIR%\etc\lumiscan-calibration, or without APP_RESOURCE_DIR C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc\lumiscan-calibration). The TIFF file is required; configuration files are optional.

More

Uploading Data

Configuration

Where are the configuration files and how are they structured?

Answer

On ctrlX OS, open Home > Manage app data in the ctrlX OS web interface, select File View and open the lumiscan-calibration folder. On a PC, they are in the settings folder lumiscan-calibration (on Windows under %APP_RESOURCE_DIR%\etc, or without APP_RESOURCE_DIR under C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc). The folder contains:

  • lumiscan-calibration.json: application settings; modules lists the module configuration files to load.

  • <module name>.json (for example example.json): settings of one transformation module.

  • <file name>.tiff: calibration data provided by HD Vision Systems.

  • schemas: the schemas that describe the settings files to an editor. Restart LumiScan Calibration after changing lumiscan-calibration.json. After changing a module configuration file or its TIFF file, a reset of the module (control/reset) is enough. The settings can also be read and changed on the Data Layer, on hdvisionsystems/lumiscan-calibration/system/settings.

More

LumiScan Calibration Folder Structure, Application Settings File, Settings on the Data Layer

How do I add a new transformation module?

Answer

Copy an existing module file under a new name (on ctrlX OS: three dots > Copy, enter a new file name and confirm with Copy; on a PC: copy the file in the settings folder). Then add the new file name to the modules list of lumiscan-calibration.json and restart the application. The name of the file without .json, in lower case, is the module’s name on the Data Layer: hdvisionsystems/lumiscan-calibration/<module name>. The name in the module’s transform block does not change it. Alternatively, create and activate the module through the Data Layer with system/control/create-module/execute and system/control/activate-module/execute, then restart with system/control/restart/execute.

More

Adding a New Module, Adding and removing modules

Which transformation parameters can I set?

Answer

In the transform block of a module file:

  • type: only from2dTo3d is supported; subtype: lookUpTable.

  • relativePathToTiff: path to the TIFF calibration file, relative to the module file.

  • interpolationMethod: closestPixel, linear4Neighbors or bilateralInterpolation.

  • offsetX, offsetY (default 0.0) and scaleX, scaleY (default 1.0). An optional, experimental stream section configures a stream of points to transform.

More

Module Configuration File

Operation

How do I convert a 2D image point into a 3D point?

Answer

With XXX = hdvisionsystems/lumiscan-calibration/<module name>:

  • Check that XXX/control/transform/ready is true.

  • Set XXX/input/x-coordinate and XXX/input/y-coordinate to the pixel coordinates. To convert several points at once, also write XXX/input/x-coordinate-array and XXX/input/y-coordinate-array; leave them empty to convert one point only.

  • Set XXX/control/transform/request to true, wait until ready is false, then set request to false. Wait until ready is true again. Alternatively, write any value to XXX/control/transform/execute: the write returns when the transform has finished.

  • Check that XXX/control/status/code is 0 ("ready") and read XXX/output/x-coordinate, y-coordinate and z-coordinate (and the output arrays).

More

Transforming points, Execute methods

What do the status codes mean?

Answer

hdvisionsystems/lumiscan-calibration/<module name>/control/status/code reports the outcome of the last function: 0 "ready" (last function successful), 1 "settingUp", 2 "running", 3 "waitingForClient", -1 "undefinedError", -2 "invalidSetting" (module configuration file or TIFF file could not be loaded), -3 "invalidInput" (one or more input values are invalid), -4 "missingLicense" (ctrlX OS: required licence not available), -5 "restartRequired" (settings changed on the Data Layer: restart the application), -10001 "inputXYSizeNotEqual" (the input arrays differ in length). An error status stays until the next request.

More

Status Code Values

Troubleshooting

Problems and error messages are described step by step in Troubleshooting:

Licensing and support

Which licence do I need, and what happens without one?

Answer

The ctrlX licence for LumiScan Calibration is SWL-W-XCx-CALIBRATExHDVSx-V2NN. Bought in the ctrlX Store for ctrlX OS, it is a ctrlX licence and needs no LumiScan Key. On ctrlX OS, the application shuts down shortly after starting if the licence is missing; the reason is in the system log. A licence lost while the application runs is reported as status -4 "missingLicense", and the module runs no function until it is back. For a PC, see the licensing information on the Requirements page.

More

Requirements, Licensing FAQ

Where can I find more answers or get support?

Answer

See the site-wide LumiScan FAQ. Contact HD Vision Systems customer success at customer.success@hdvisionsystems.com or +49 6221 6721905; for licences, licenses@hdvisionsystems.com.

More

Licensing FAQ, Data Layer FAQ