--- title: "FAQ" description: "Frequently asked questions about LumiScan Calibration - TIFF calibration data, configuration files, 2D-to-3D transformation, status codes and licensing, with links to troubleshooting." product: "LumiScan Calibration" component: "lumiscan-calibration" version: "2.0.0" display_version: "2.0.0.8" latest_version: true language: "en" url: "https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/faq.html" --- # FAQ – LumiScan Calibration 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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html). > [!TIP] > Each entry has a fixed anchor (for example `#faq-status-codes`). To find an error message, search the [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html) page for it. ## Getting started ### What does LumiScan Calibration do? {#faq-what-does-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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/description.html), [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/requirements.html) ### How do I get the TIFF calibration file? {#faq-get-tiff-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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/tiff-file.html) ### How do I upload the TIFF file and configuration files? {#faq-upload-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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/uploading-data.html) ## Configuration ### Where are the configuration files and how are they structured? {#faq-config-files} - **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. - `.json` (for example `example.json`): settings of one transformation module. - `.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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/folder-structure.html#edit-with-built-in-website), [Application Settings File](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/application-settings-file.html), [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html) ### How do I add a new transformation module? {#faq-add-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/`. 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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/adding-new-module.html), [Adding and removing modules](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html#adding-and-removing-modules) ### Which transformation parameters can I set? {#faq-module-parameters} - **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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/module-configuration-file.html#table-5-module-settings) ## Operation ### How do I convert a 2D image point into a 3D point? {#faq-convert-point} - **Answer:** With `XXX` = `hdvisionsystems/lumiscan-calibration/`: - 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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/functionalities.html#transform), [Execute methods](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/functionalities.html#execute) ### What do the status codes mean? {#faq-status-codes} - **Answer:** `hdvisionsystems/lumiscan-calibration//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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/functionalities.html#status-code-values) ## Troubleshooting {#troubleshooting} Problems and error messages are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html): - [A calibration module does not appear in the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#faq-module-not-in-data-layer) - [Data Layer addresses under lumiscan-cam-calibration no longer work](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#faq-data-layer-name) - [`transform/ready` stays `false`, and the status is -2](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#faq-transform-not-ready) - [The application does not react to a request](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#faq-request-not-detected) - [The transformed coordinates do not match the image](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#faq-coordinates-wrong) - [The stream does not start](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#ts-stream-does-not-start) - [The stream runs, but no points arrive](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#ts-stream-no-points) ## Licensing and support ### Which licence do I need, and what happens without one? {#faq-licence} - **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](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/requirements.html#licence), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html) ### Where can I find more answers or get support? {#faq-support} - **Answer:** See the site-wide [LumiScan FAQ](https://docs.hdvisionsystems.com/en/faq.html). Contact HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905; for licences, [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com). - **More:** [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html), [Data Layer FAQ](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/faq.html)