# LumiScan Training 2.3.0.3 – complete documentation

> All pages of the LumiScan Training 2.3.0.3 manual (language: en) by HD Vision Systems GmbH, in navigation order. Each page starts with a level-1 heading followed by its URL; cite that URL. Manual: https://docs.hdvisionsystems.com/en/lumiscan-training/

# LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/index.html

|   |   |   |
| --- | --- | --- |
| ![Three folders of annotated images and a JSON configuration](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/intro/step-1.svg)<br><br>**Prepare the data.** Annotated images for training, validation and test. | ![Training curve falling over the epochs](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/intro/step-2.svg)<br><br>**Train the network.** From scratch or continuing an existing network. | ![ONNX and HEF model files for AI Object Matching, LumiScan VGR and Hailo TPU](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/intro/step-3.svg)<br><br>**Export the model.** As ONNX, or converted for a Hailo TPU. |

LumiScan Training trains neural networks for object detection and localization, from scratch or by continuing an existing network. Training, validation, testing and inference are set up in one JSON configuration, and the finished model is exported as ONNX for LumiScan AI Object Matching and LumiScan VGR. The optional Hailo PlugIn converts it for a Hailo TPU. It runs on Windows 11 with an NVIDIA RTX graphics card, locally or on a shared training server.

For licensing, see [Licence](https://docs.hdvisionsystems.com/en/lumiscan-training/requirements.html#licence). Questions or an error message? See the [FAQ](https://docs.hdvisionsystems.com/en/lumiscan-training/faq.html).

# Description – LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/description.html

LumiScan Training is an application for training neural networks for computer vision tasks, including object detection and localization.

The application can train a network from scratch or continue training an existing network with additional data. Training, validation, testing, and inference are controlled through a JSON configuration that defines the data sets, classes, network type, training profile, and export settings.

Trained models can be exported in ONNX format for use in supported applications. If a Hailo TPU is used, the optional Hailo PlugIn can additionally convert an ONNX model into a Hailo-compatible model for deployment on the TPU.

# Requirements – LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/requirements.html

## Operating System

LumiScan Training requires one of the following operating systems:

- Windows 11 Professional
- Windows 11 Enterprise

## Hardware

The following hardware is required:

- NVIDIA RTX graphics card
- Up to 15 GB of free disk space

## Software

The following software is required:

- CUDA Toolkit 11.8
- CodeMeter 9.00 or later

## Licence {#licence}

How LumiScan Training is licensed depends on where you bought it and where it runs:

| Bought from | Runs on | Licensing |
| --- | --- | --- |
| HD Vision Systems | Windows 11 | The licence is held on your LumiScan Key. It is an annual subscription and must be renewed every year; the renewal requires a valid subscription.<br><br>[Licensing path: bought from HD Vision Systems](https://docs.hdvisionsystems.com/en/lumiscan-licensing/path-hdvs.html) |
| ctrlX Store | Windows 11 | The licence is held in ctrlX WORKS. The LumiScan Key is required in addition; it protects the software against reverse engineering.<br><br>[Licensing path: ctrlX Store, Windows](https://docs.hdvisionsystems.com/en/lumiscan-licensing/path-ctrlx-windows.html) |

Each device on which LumiScan Training runs at the same time needs its own LumiScan Key. Keys can be exchanged between devices.

How to install CodeMeter Runtime and how to request, renew and move licences is described in [LumiScan Licensing](https://docs.hdvisionsystems.com/en/lumiscan-licensing/index.html).

## Additional Requirements for the Hailo PlugIn

The following additional requirements apply only if the Hailo PlugIn is used for model conversion:

- At least 24 GB of system memory (DRAM). The model conversion runs in a virtual machine configured with 18 GB of memory.
- Hardware that supports Hyper-V. See [Hyper-V host hardware requirements](https://learn.microsoft.com/en-us/windows-server/virtualization/hyper-v/host-hardware-requirements?pivots=windows).

For information about installing the required components, see [\[installing-podman\]](https://docs.hdvisionsystems.com/en/lumiscan-training/requirements.html#installing-podman).

# LumiScan Training Installation

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html

LumiScan Training is installed using a setup program whose file name begins with `Installer_` and ends with the version number, for example `Installer_LumiScanTrainingFramework_v2_1_0_0.exe`.

The setup program contains all required components, including its own Python environment. A separate Python or Anaconda installation is not required.

If a Hailo TPU is used, install Podman and the Hailo PlugIn **before** installing LumiScan Training. See [Installing Podman (Optional)](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-podman). The application uses Podman for the **Model Conversion** function, and the setup program reports if the Hailo PlugIn is missing during installation.

## Installing Podman (Optional) {#installing-podman}

This section is only required if a Hailo TPU is used.

The **Model Conversion** function converts a trained network into a Hailo model. See [Model Conversion: ONNX to Hailo](https://docs.hdvisionsystems.com/en/lumiscan-training/model-conversion.html). The conversion runs inside a container and therefore requires Podman and the Hailo PlugIn.

If you do not use a Hailo TPU, skip this section and [Installing the Hailo PlugIn](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-hailo-plugin), and continue with [Installing LumiScan Training](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-lumiscan-training).

> [!NOTE]
> Hyper-V does not need to be enabled beforehand. The Hailo PlugIn installer checks whether it is available and offers to enable it if necessary. Hyper-V is not available on Windows Home editions, so the Hailo PlugIn cannot be used there.

> [!IMPORTANT]
> The Hailo PlugIn includes a Podman virtual machine image built for **Podman 6.0**. Install a matching **Podman 6.0.x** CLI to ensure compatibility between the CLI and the provided image. A newer Podman CLI may still work, but is not tested with the provided image. If <https://podman.io/> only offers a newer version, use **Other Install Options** to obtain a 6.0.x release.

To install Podman:

1. Open <https://podman.io/> in a web browser.

2. Open the **Download** menu and select **Podman CLI for Windows amd64** (Fig. 1).

   ![The download menu on the podman.io website with the entry Podman CLI for Windows amd64 selected](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/download_podman_installer.png)

   *Figure 1. Fig. 1: Podman: Download of the Podman CLI for Windows*

3. Start the downloaded setup program.

4. Select **Windows Hyper-V** as the virtualization provider (Fig. 2), and click **Next**.

   ![The Podman CLI Setup Wizard with Windows Hyper-V selected as the virtualization provider](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/podman-install-with-hyperV.png)

   *Figure 2. Fig. 2: Podman CLI Setup: Selection of the Virtualization Provider*

5. Follow the remaining installation steps and close the setup program with **Finish** (Fig. 3).

   ![The Podman CLI Setup Wizard reporting that the installation has been completed](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/podman-installation-finished.png)

   *Figure 3. Fig. 3: Podman CLI Setup: Completed Installation*

> [!TIP]
> Install Podman before the Hailo PlugIn, as described in the next section. The Hailo PlugIn checks its prerequisites one after another and stops at the first missing prerequisite. Installing the components in a different order may therefore require additional installation attempts.

## Installing the Hailo PlugIn {#installing-hailo-plugin}

The Hailo PlugIn provides the container image used to convert a trained network into a Hailo model. Like Podman, it is only required if a Hailo TPU is used.

The setup program file name begins with `Installer-LumiScanTraining-HailoPlugIn`. The installer configures Podman, creates and starts a virtual machine, and loads the model-conversion image into it.

> [!IMPORTANT]
> The installation can take 10 to 20 minutes, or longer during the first installation. Do not interrupt the installation process.

The installer requires approximately 5 GB of free disk space while it is running. The virtual machine and model-conversion image require several additional gigabytes of storage, and their storage usage may increase during operation.

To install the Hailo PlugIn:

1. Double-click the setup program and confirm the Windows prompt for administrator rights.

2. Accept the suggested installation folder or select a different one, then click **Next** (Fig. 4).

   ![The Hailo PlugIn setup program showing the Select Destination Location page with the default installation folder](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/hailo_plugin_install-1-install-with-default.png)

   *Figure 4. Fig. 4: Hailo PlugIn Setup: Selection of the Installation Folder*

3. A message describes the following installation steps and their expected duration. Confirm it with **OK** (Fig. 5).

   ![A message from the setup program explaining that Podman is configured, a virtual machine is created and started, and a 4 GB image is loaded into it](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/hailo_plugin_install-2-start.png)

   *Figure 5. Fig. 5: Hailo PlugIn Setup: Installation Duration*

4. Windows Firewall may report that features of `podman.exe` have been blocked and ask whether network access should be allowed (Fig. 6).\
   It is recommended to decline this request with **Cancel**. Model conversion runs entirely on the local computer, so Podman does not need to be accessible from other computers on the network. Model conversion also works if network access is declined.

   ![The Windows Security dialog asking whether public, private, and domain networks should be allowed to access podman.exe](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/hailo_plugin_install-3-reject-access-internet.png)

   *Figure 6. Fig. 6: Windows Firewall: Network Access Request for podman.exe*

5. The setup program performs the required steps and displays the progress in a live log (Fig. 7). Wait until the process is complete.

   ![The setup program during installation, showing the current setup step and a live log of the Podman machine setup](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/hailo_plugin_install-4-install-running.png)

   *Figure 7. Fig. 7: Hailo PlugIn Setup: Installation in Progress*

6. A message confirms that the image was installed successfully. Click **OK** (Fig. 8).

   ![A message from the setup program reporting that the Hailo model-conversion image was installed successfully](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/hailo_plugin_install-5-install-success.png)

   *Figure 8. Fig. 8: Hailo PlugIn Setup: Successful Image Installation*

7. Close the setup program with **Finish** (Fig. 9).

   ![The final page of the Hailo PlugIn setup wizard with the complete installation log and the Finish button](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/hailo_plugin_install-6-finished.png)

   *Figure 9. Fig. 9: Hailo PlugIn Setup: Completed Installation*

## Installing LumiScan Training {#installing-lumiscan-training}

To install LumiScan Training:

1. Double-click the setup program.
2. Confirm the Windows prompt for administrator rights.\
   Administrator rights are required when installing to the default location under `C:\Program Files`.
3. Select the installation language. English and German are available.
4. If the Hailo PlugIn is not installed, a message reports that the **Model Conversion** function will not be available.\
   Select **Yes** to continue the installation without the plugin, or **No** to cancel and install the plugin first. See [Installing Podman (Optional)](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-podman).
5. Accept the suggested installation folder or select a different one.\
   By default, the application is installed under `C:\Program Files\HD Vision Systems GmbH{page-component-title}`.
6. Optionally, select **Create a desktop icon** if you want to start the application from the desktop.
7. Start the installation and wait until it is complete.

The setup program creates an entry named **LumiScan Training** in the Windows Start menu and, if selected, a desktop shortcut. You can start the application from either location.

If you encounter problems during installation, contact HD Vision Systems.

# User Interface – LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/user-interface.html

After starting the program, the standard user interface opens (Fig. 10).

The elements of the user interface are described in Table 1.

![LumiScan Training Framework user interface with options to select a configuration file, start training, testing, and inference, convert a model, and cancel the current process](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/trainingframework_started.jpg)

*Figure 1. Fig. 10: LumiScan Training Framework User Interface*

**Table 1. Table 1: LumiScan Training Framework User Interface Description**

| No. | Description |
| --- | --- |
| 1 | **Select Config File/Browse** is used to select the configuration file. |
| 2 | **Process Status** displays the current status of the process.<br> Possible messages include:<br><br>- **Waiting for configuration file!** The program is waiting for a configuration file to be selected.<br>- **Testing Network!** Appears after clicking **Start Testing** and indicates that an existing network is being tested with a test data set.<br>- **Waiting for deployment!** Appears after training while the network is being prepared for conversion and export to an ONNX file.<br>- **Finished cleanup** indicates that the process has finished.<br>- **Time Remaining** displays the estimated remaining process time.<br>- **Latest test scores** displays a metric for evaluating trained networks. The value should be used primarily to compare networks tested with the same data set rather than as an absolute measure of performance. |
| 3 | **Start Training** starts the training process using the selected configuration. |
| 4 | **Start Testing** tests the network using the test data set specified in the configuration. The results are stored in the Export folder. |
| 5 | **Start Inference** opens a dialog for selecting a folder containing images. The trained network is then applied to these images, and the prediction results are saved in the `predictions` folder within the export directory. |
| 6 | **Model Conversion** opens a dialog for converting a trained ONNX model to a Hailo model. See [Model Conversion: ONNX to Hailo](https://docs.hdvisionsystems.com/en/lumiscan-training/model-conversion.html).<br> This function requires the Hailo PlugIn. |
| 7 | **Cancel** interrupts an ongoing training, testing, or inference process. |

For successful training, all relevant parameters must be configured in the JSON settings beforehand. An example configuration is provided in the next section.

# App Settings: Local and Remote Backends – LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/app-settings.html

By default, LumiScan Training starts its own backend on the same computer and requires no additional configuration.

The **App Settings** tab in the application navigation bar can also be used to configure a shared backend server. Other computers can then either access the frontend in a web browser or run their own LumiScan Training installation and connect it to the shared backend instead of starting a local backend.

## Setting Up a Shared Backend Server {#app-settings-server}

1. Install LumiScan Training on the computer that should act as the server, as described in [\[installing-lumiscan-training\]](https://docs.hdvisionsystems.com/en/lumiscan-training/app-settings.html#installing-lumiscan-training).

2. Start the application and open the **App Settings** tab.

3. Under **Backend connection**, make sure **Start backend locally** is enabled.

4. Under **Backend bind address**, select the network interface that other computers should use to access the server.

   Do not select `localhost (127.0.0.1)`, as this address only accepts connections from the same computer.

   Select the computer’s network IP address, for example `192.168.1.50`, or `0.0.0.0 (all interfaces)` to accept connections on all available network interfaces.

5. Enable **Autostart backend as a service**.

   This starts the backend automatically when the Windows user logs in, without opening the application window. The backend therefore remains available even if LumiScan Training itself is not open.

6. Click **Save**.

7. Restart LumiScan Training, or log out of Windows and log back in, for the changes to take effect.

> [!NOTE]
> Windows Firewall may ask whether the backend should be allowed to communicate over the network when it is first bound to a network-reachable address. Allow access for **Private networks** so that other computers can connect to the server.

## Connecting from a Client Computer {#app-settings-client}

There are two ways to connect another computer to the shared backend.

### Browser Access Without Installation

Open a web browser and navigate to:

`http://<server-ip>:8420`

Replace `<server-ip>` with the IP address of the server, for example:

`http://192.168.1.50:8420`

The full frontend runs in the browser, and no local installation of LumiScan Training is required.

### Installing LumiScan Training on the Client

1. Install LumiScan Training on the client computer, as described in [\[installing-lumiscan-training\]](https://docs.hdvisionsystems.com/en/lumiscan-training/app-settings.html#installing-lumiscan-training).
2. Start the application and open the **App Settings** tab.
3. Under **Backend connection**, disable **Start backend locally**.
4. Enter the server IP address, for example `192.168.1.50`, under **Remote backend address**.
5. Click **Save**.
6. Restart LumiScan Training.

The application now connects to the shared backend instead of starting a local backend.

## Troubleshooting {#app-settings-troubleshooting}

Problems with the shared backend are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html):

- [A client cannot connect to the shared backend](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-client-cannot-connect)

# JSON Settings – LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/json-settings.html

## [source,json]

{ "trainingData": "C:/Users/user_name/Desktop/recordings/raw", "validationData": "C:/Users/user_name/Desktop/recordings/raw", "exportDirectory": "C:/Users/user_name/Desktop/recordings/network", "finetuneDataRoot": "C:/Users/user_name/Desktop/recordings/raw", "classes": [ "Arrow", "Disk" ], "nonRotables": [ "Disk" ], "imageScale": 0.5, "networkBase": null, "networkType": "ORTMS", "schedule": "Full", "trainingProfile": "B8x1", "deploymentConfiguration": "LumiScanVGR", "tmpFiles": "tmp" } -

These are standard parameters of the JSON configuration. Their meaning is explained in [Table 2](https://docs.hdvisionsystems.com/en/lumiscan-training/json-settings.html#json-parameters-description). The required parameters depend on the application and training workflow.

## JSON Parameters Description {#json-parameters-description}

> [!NOTE]
> When specifying paths, use forward slashes (`/`) instead of backslashes (`\`).

> [!NOTE]
> If no value is specified for a parameter that supports an empty value, use `null` exactly as shown. Do not use quotation marks or capital letters.

**Table 1. Table 2: LumiScan Training JSON Settings**

| Parameter | Description |
| --- | --- |
| `trainingData` | Path to the training data.<br> This folder is typically generated by LumiScan Annotation and contains the images and corresponding annotation data in CSV or JSON format. Each image should have a corresponding annotation file. |
| `validationData` | Path to the validation data used to evaluate the network during training.<br> This can be set to the same path as `trainingData`. |
| `testData` | Optional. Path to the data set used when **Start Testing** is selected. |
| `exportDirectory` | Optional. Path used to store exported ONNX models and other training results.<br> If no path is specified, the results are stored in the directory containing the training data specified in `trainingData`. |
| `finetuneDataRoot` | Path to the data used for fine-tuning. This is typically the same path as `validationData`. |
| `classes` | List of classes or labels that the network should recognize. The class names must match the labels used in the annotation data. |
| `nonRotables` | List of classes without a defined orientation, for example a disk or a scratch.<br> Each entry must exactly match a class name defined in `classes`. |
| `Arrow`, `Disk` | Examples of class names. |
| `imageScale` | Specifies the image scaling factor relative to the original image size. Supported values are `0.5` and `1.0`. |
| `networkBase` | Path to an existing trained network that should be used as the starting point for training.<br> Set the value to `null` to start training without an existing network. |

| Parameter | Description |
| --- | --- |
| `networkType` | Specifies the network type. The available values depend on the target application and whether the object’s orientation or only its rotation needs to be determined.<br><br>For **LumiScan VGR**:<br><br>- `ORTML`, `ORTMM`, `ORTMS`, `ORTMXS`: Oriented models. Use these when the object has a meaningful orientation, for example a distinguishable top side, that must be identified in addition to its position.<br>- `RRTML`, `RRTMM`, `RRTMS`, `RRTMXS`: Rotated models. Use these when only the rotation of the object needs to be determined and no specific side or orientation needs to be distinguished.<br>- `LumiScanOOD` (deprecated): Previous model type for oriented object detection.<br>- `LumiScanROD` (deprecated): Previous model type for rotated object detection.<br><br>For **AI Object Matching**:<br><br>- `OOD`: For objects with a meaningful orientation that must be identified.<br>- `ROD`: For objects where only the rotation needs to be determined.<br><br>The final letters of the `ORTM…` and `RRTM…` values specify the network size:<br><br>- `L`: large<br>- `M`: medium<br>- `S`: small<br>- `XS`: extra small<br><br>Larger networks can provide higher accuracy but require more memory and generally take longer to train.<br><br>**Note:** Enter the value exactly as listed, including the size suffix. `ORTM` and `RRTM` without a size suffix are not valid values. |
| `schedule` | Specifies the training schedule. Supported values are `Full` and `Finetune`.<br><br>- `Full`: Performs a new training run. Use this option for initial training.<br>- `Finetune`: Continues training using an existing network and the data specified in `finetuneDataRoot`. Use this option for subsequent refinement steps. |
| `trainingProfile` | Specifies the training profile and influences GPU memory usage. Currently, only one GPU is supported.<br><br>Available values:<br><br>- `B8x1`: Default value.<br>- `B4x1`: Use this option if training fails with `B8x1` because of insufficient GPU memory or if training is using shared GPU memory.<br><br>Shared GPU memory usage can be checked in the Windows Task Manager. An unusually long training time can also indicate insufficient GPU memory. |
| `deploymentConfiguration` | Specifies the target deployment configuration. For LumiScan VGR, the value is `LumiScanVGR` and should not be changed. |
| `tmpFiles` | Path used to store temporary files during training. The application must have write permission for this location. Temporary files are deleted after training. |

# Model Conversion: ONNX to Hailo – LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/model-conversion.html

A network that has been trained and exported as an ONNX file can be converted into a Hailo model for execution on a Hailo TPU.

The conversion runs inside the Hailo conversion container. It is therefore only available if the **Hailo PlugIn** (`Installer-LumiScanTraining-HailoPlugIn`) is installed in addition to LumiScan Training. If the plugin is missing, the application reports that the `podman` command or the required conversion image could not be found.

## Starting the Program

Start LumiScan Training as described in [LumiScan Training Installation](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html). The splash screen (Fig. 11) is displayed while the application is loading.

![The LumiScan Training splash screen showing the HD Vision Systems logo, the text Loading LumiScan Training, and a progress bar](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/splashscreen.jpg)

*Figure 1. Fig. 11: LumiScan Training: Splash Screen*

After loading, the main window opens (Fig. 12). Model conversion is started using the **Model Conversion** button.

![The LumiScan Training Framework main window with the Select Config File and Process Status areas and the buttons Start Training, Start Testing, Start Inference, and Model Conversion](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/trainingframework_started.jpg)

*Figure 2. Fig. 12: LumiScan Training Framework: Main Window with Model Conversion Button*

## Preparing the Calibration Images

During conversion, the network is quantized. A set of calibration images is required to determine the value ranges that occur within the network.

> [!IMPORTANT]
> The calibration images must have the **same resolution as the training images**. Images with a different resolution can result in an unusable model.

The quality and representativeness of the calibration images influence the accuracy of the converted model. Therefore:

- Record the images under **real production conditions**, using the same camera, optics, working distance, and objects as in later operation.
- Include representative **lighting conditions**. For example, use different exposure times if the exposure time also varies during operation, or record image sets under different ambient lighting conditions.

Store the images in a single folder, referred to below as the **calibration folder**. Supported image formats include `.png`, `.jpg`, `.jpeg`, `.bmp`, and `.tiff`.

## Performing the Conversion

Click **Model Conversion** to open the **Model Conversion (ONNX → Hailo)** dialog (Fig. 13). Use the corresponding **Browse** buttons to select the three paths described in [Table 3](https://docs.hdvisionsystems.com/en/lumiscan-training/model-conversion.html#model-conversion-parameters).

![The Model Conversion dialog with the fields ONNX model file, Calibration folder, and Output folder, each with a Browse button, as well as the Start Conversion button and the status Ready](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/select_model_and_calibration_dir.jpg)

*Figure 3. Fig. 13: LumiScan Training: Model Conversion Dialog*

**Table 1. Table 3: LumiScan Training Model Conversion Parameters**

| Field | Description |
| --- | --- |
| **ONNX model file** | The trained network in ONNX format. It is normally located in the folder specified by `exportDirectory` in the [JSON Settings](https://docs.hdvisionsystems.com/en/lumiscan-training/json-settings.html). |
| **Calibration folder** | The folder containing the calibration images described in the previous section. |
| **Output folder** | The folder in which the converted model and associated files are stored. By default, the folder containing the ONNX file is selected. |

Click **Start Conversion** to begin the conversion (Fig. 14).

While the conversion is running:

- The status changes to **Converting…**.
- The **Start Conversion** button changes to **Stop Conversion**, which can be used to cancel the running conversion.
- The input fields are disabled.
- The progress of the conversion is displayed in the log console at the bottom of the window.

![The Model Conversion dialog during conversion, showing the Stop Conversion button, the status Converting, and the log console with container output](https://docs.hdvisionsystems.com/en/lumiscan-training/_images/start_conversion.jpg)

*Figure 4. Fig. 14: LumiScan Training: Model Conversion in Progress*

> [!NOTE]
> The first conversion can take longer because the Podman machine is started first if it is not already running.

> [!NOTE]
> The conversion container can access the `C:` drive directly. If the ONNX file, calibration folder, or output folder is located on another drive, for example `E:`, or on a network share, the required files are automatically transferred to the container before conversion. The results are transferred back after conversion is complete. No additional configuration is required. The log console displays the additional transfer steps, and the overall conversion time may increase depending on the size of the calibration data.

When the conversion is complete, the message **Conversion finished successfully.** is displayed.

The following files are created in the output folder, where `<name>` is the name of the ONNX file:

- `<name>.hef` - Model for the Hailo TPU.
- `<name>.har` - Intermediate archive created during conversion.
- `<name>_hailo.onnx` - ONNX model adapted for Hailo.
- `convert_parameters.json` - Parameters used for the conversion.

If the conversion fails, the exit code is displayed in the status line and additional information is shown in the log console.

Problems during the model conversion are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html):

- [**Model Conversion** is not available, or `podman` or the conversion image cannot be found](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-model-conversion-unavailable)
- [The model conversion fails with exit code 137](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-exit-code-137)
- [The model conversion takes longer than expected](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-conversion-slow)

If you encounter other problems during model conversion, contact HD Vision Systems.

# FAQ – LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/faq.html

Short answers to common questions and error messages for LumiScan Training. Each entry links to the page with the details.

> [!TIP]
> Search this page for the exact error message. Each entry has a fixed anchor (for example `#faq-json-paths-null`).

## Requirements and installation

### What are the system requirements? {#faq-system-requirements}

- **Answer:**
  - Windows 11 Professional or Windows 11 Enterprise
  - NVIDIA RTX graphics card
  - CUDA Toolkit 11.8
  - CodeMeter 9.00 or later
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-training/requirements.html)

### How do I install LumiScan Training, and do I need Python? {#faq-installation}

- **Answer:** Run the setup program (file name starts with `Installer_` and ends with the version number, for example `Installer_LumiScanTrainingFramework_v2_1_0_0.exe`) and confirm the prompt for administrator rights; they are required for the default location under `C:\Program Files`. The setup program contains its own Python environment, so a separate Python or Anaconda installation is not required. English and German are available as installation languages.
- **More:** [LumiScan Training Installation](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-lumiscan-training)

### In which order do I install the components for a Hailo TPU? {#faq-hailo-installation-order}

- **Answer:** Only needed if a Hailo TPU is used. Keep this order: the Hailo PlugIn checks its prerequisites one after another and stops at the first missing one, so a different order may require additional installation attempts.
  1. Podman CLI 6.0.x for Windows, with **Windows Hyper-V** as the virtualization provider (the Hailo PlugIn image is built for Podman 6.0; newer CLIs are not tested).
  2. The Hailo PlugIn (setup file name begins with `Installer-LumiScanTraining-HailoPlugIn`). The installation can take 10 to 20 minutes or longer; do not interrupt it.
  3. LumiScan Training.
- **More:** [Installing Podman](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-podman), [Installing the Hailo PlugIn](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-hailo-plugin)

### What does the computer need for the Hailo PlugIn? {#faq-hailo-requirements}

- **Answer:** At least 24 GB of system memory (DRAM), because the model conversion runs in a virtual machine configured with 18 GB of memory, and hardware that supports Hyper-V. Hyper-V does not need to be enabled beforehand; the Hailo PlugIn installer offers to enable it. Hyper-V is not available on Windows Home editions, so the Hailo PlugIn cannot be used there.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-training/requirements.html), [Installing Podman](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-podman)

### Windows Firewall asks whether `podman.exe` may access the network. What should I do? {#faq-podman-firewall}

- **Answer:** It is recommended to decline the request with **Cancel**. Model conversion runs entirely on the local computer and also works if network access is declined.
- **More:** [Installing the Hailo PlugIn](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-hailo-plugin)

## Troubleshooting {#troubleshooting}

Problems and error messages are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html):

- [**Model Conversion** is not available, or `podman` or the conversion image cannot be found](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-model-conversion-unavailable)
- [Training fails because of insufficient GPU memory or takes unusually long](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-gpu-memory)
- [The model conversion fails with exit code 137](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-exit-code-137)
- [The model conversion takes longer than expected](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-conversion-slow)
- [A client cannot connect to the shared backend](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#faq-client-cannot-connect)

## Configuration and training

### How do I write paths and empty values in the JSON configuration? {#faq-json-paths-null}

- **Answer:** Use forward slashes (`/`) instead of backslashes (`\`) in paths, for example `C:/Users/user_name/Desktop/recordings/raw`. For a parameter that supports an empty value, write `null` exactly like this, without quotation marks or capital letters (for example `"networkBase": null` to train without an existing network).
- **More:** [JSON Parameters Description](https://docs.hdvisionsystems.com/en/lumiscan-training/json-settings.html#json-parameters-description)

### Which value do I use for `networkType`? {#faq-network-type}

- **Applies to:** LumiScan VGR and AI Object Matching
- **Answer:**
  - LumiScan VGR: `ORTML`, `ORTMM`, `ORTMS` or `ORTMXS` (oriented models) if the object has a meaningful orientation that must be identified; `RRTML`, `RRTMM`, `RRTMS` or `RRTMXS` (rotated models) if only the rotation is needed. The suffix sets the size (L, M, S, XS); `ORTM` and `RRTM` without suffix are not valid.
  - AI Object Matching: `OOD` for objects with a meaningful orientation, `ROD` if only the rotation is needed.
- **More:** [JSON Parameters Description](https://docs.hdvisionsystems.com/en/lumiscan-training/json-settings.html#json-parameters-description)

### Where are the trained models and results stored? {#faq-results-location}

- **Answer:** Exported ONNX models and other training results are stored in `exportDirectory`; if no path is specified, in the directory of the training data (`trainingData`). **Start Testing** stores its results in the export folder, and **Start Inference** saves the predictions in the `predictions` folder within the export directory.
- **More:** [JSON Parameters Description](https://docs.hdvisionsystems.com/en/lumiscan-training/json-settings.html#json-parameters-description), [User Interface](https://docs.hdvisionsystems.com/en/lumiscan-training/user-interface.html)

### What do the messages in **Process Status** mean? {#faq-process-status}

- **Answer:**
  - `Waiting for configuration file!`: no configuration file has been selected yet (use **Select Config File/Browse**).
  - `Testing Network!`: an existing network is being tested with the test data set after **Start Testing**.
  - `Waiting for deployment!`: after training, the network is being prepared for conversion and export to an ONNX file.
  - `Finished cleanup`: the process has finished.
  - **Latest test scores**: a metric to compare networks tested with the same data set, not an absolute measure of performance.
- **More:** [User Interface](https://docs.hdvisionsystems.com/en/lumiscan-training/user-interface.html)

## Model conversion (ONNX to Hailo)

### Which calibration images do I need for the model conversion? {#faq-calibration-images}

- **Answer:** The calibration images must have the same resolution as the training images; otherwise the model can be unusable. Record them under real production conditions (same camera, optics, working distance and objects) and include representative lighting conditions. Store them in a single folder; supported formats include `.png`, `.jpg`, `.jpeg`, `.bmp` and `.tiff`.
- **More:** [Model Conversion: ONNX to Hailo](https://docs.hdvisionsystems.com/en/lumiscan-training/model-conversion.html)

### Which files does the conversion create? {#faq-conversion-output}

- **Answer:** After `Conversion finished successfully.`, the output folder contains `<name>.hef` (model for the Hailo TPU), `<name>.har` (intermediate archive), `<name>_hailo.onnx` (ONNX model adapted for Hailo) and `convert_parameters.json` (conversion parameters), where `<name>` is the name of the ONNX file. By default, the output folder is the folder containing the ONNX file.
- **More:** [Model Conversion Parameters](https://docs.hdvisionsystems.com/en/lumiscan-training/model-conversion.html#model-conversion-parameters)

## Shared backend

### How can several computers use one LumiScan Training backend? {#faq-shared-backend}

- **Answer:** On the server, open **App Settings**, keep **Start backend locally** enabled, set **Backend bind address** to the computer’s network IP address or `0.0.0.0 (all interfaces)` (not `localhost (127.0.0.1)`), enable **Autostart backend as a service**, click **Save** and restart. Clients either open `http://<server-ip>:8420` in a web browser, or disable **Start backend locally** in their own installation and enter the server under **Remote backend address**.
- **More:** [Setting Up a Shared Backend Server](https://docs.hdvisionsystems.com/en/lumiscan-training/app-settings.html#app-settings-server), [Connecting from a Client Computer](https://docs.hdvisionsystems.com/en/lumiscan-training/app-settings.html#app-settings-client)

## Licensing and support

### How is LumiScan Training licensed? {#faq-licence}

- **Answer:** LumiScan Training needs CodeMeter 9.00 or later. Bought from HD Vision Systems, the licence is on the LumiScan Key and is an annual subscription. Bought in the ctrlX Store for Windows 11, it uses ctrlX WORKS together with the LumiScan Key. One LumiScan Key is needed per device that runs the software at the same time; keys can be exchanged between devices.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-training/requirements.html#licence), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/faq.html)

### Where can I get further help? {#faq-support}

- **Answer:** See the site-wide [LumiScan FAQ](https://docs.hdvisionsystems.com/en/faq.html). Contact customer support at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905. For licences, write to [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

# Troubleshooting – LumiScan Training

URL: https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html

This page starts with general checks that you do first. Then find your symptom and work through the diagnostic procedure and the resolution. If the problem persists, send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#support-information) to support.

## General checks {#general-checks}

- Check that the computer meets the [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-training/requirements.html): Windows 11 Professional or Windows 11 Enterprise, an NVIDIA RTX graphics card, up to 15 GB of free disk space, CUDA Toolkit 11.8 and CodeMeter 9.00 or later.
- Check the licence (see [Licence](https://docs.hdvisionsystems.com/en/lumiscan-training/requirements.html#licence)). Licence problems with the LumiScan Key - a key that is not detected, the message `User maximum reached!`, an engineering app that no longer starts because the annual subscription has expired - are described in [Licensing: Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-licensing/troubleshooting.html).
- Only if a Hailo TPU is used: check that the computer has at least 24 GB of system memory (DRAM) and hardware that supports Hyper-V, and that Podman 6.0.x and the Hailo PlugIn were installed before LumiScan Training (see [Installing Podman](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-podman)).
- Check the JSON configuration: paths use forward slashes (`/`) instead of backslashes (`\`), and an empty value is written as `null`, without quotation marks or capital letters (see [JSON Parameters Description](https://docs.hdvisionsystems.com/en/lumiscan-training/json-settings.html#json-parameters-description)).
- Read the **Process Status** area of the main window. `Waiting for configuration file!` means that no configuration file has been selected yet (**Select Config File/Browse**); the other messages are described under [User Interface](https://docs.hdvisionsystems.com/en/lumiscan-training/user-interface.html).
- During a model conversion, the log console at the bottom of the **Model Conversion (ONNX → Hailo)** dialog shows the progress and, if the conversion fails, additional information.

## Problem: **Model Conversion** is not available, or `podman` or the conversion image cannot be found {#faq-model-conversion-unavailable}

**Symptoms**

- During the installation of LumiScan Training, the setup program reports that the **Model Conversion** function will not be available.
- The application reports that the `podman` command or the required conversion image could not be found.

**Possible causes**

- The Hailo PlugIn is not installed. The model conversion runs inside the Hailo conversion container and is only available if the Hailo PlugIn (`Installer-LumiScanTraining-HailoPlugIn`) is installed in addition to LumiScan Training.
- Podman was not installed before the Hailo PlugIn. The Hailo PlugIn checks its prerequisites one after another and stops at the first missing prerequisite.
- Hyper-V is not available. Hyper-V is not available on Windows Home editions, so the Hailo PlugIn cannot be used there.

**Diagnostic procedure**

1. Check that the Podman CLI for Windows is installed in version 6.0.x with **Windows Hyper-V** as the virtualization provider - expected: Podman 6.0.x is installed. The Hailo PlugIn image is built for Podman 6.0; a newer Podman CLI is not tested with it.
2. Check that the setup program of the Hailo PlugIn was run to the end - expected: a message confirmed that the image was installed successfully, and the setup program was closed with **Finish**.
3. Check the Windows edition and the hardware - expected: Windows 11 Professional or Windows 11 Enterprise, hardware that supports Hyper-V, at least 24 GB of system memory.

**Resolution**

- **If the Hailo PlugIn is not installed:** install Podman and the Hailo PlugIn as described under [Installing Podman](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-podman) and [Installing the Hailo PlugIn](https://docs.hdvisionsystems.com/en/lumiscan-training/lumiscan-training-installation.html#installing-hailo-plugin). The installation of the Hailo PlugIn can take 10 to 20 minutes or longer; do not interrupt it.
- **If Podman was not installed before the Hailo PlugIn:**
  1. Install the Podman CLI 6.0.x for Windows with **Windows Hyper-V** as the virtualization provider.
  2. Run the setup program of the Hailo PlugIn again and wait until it reports that the image was installed successfully.
- **If Hyper-V is not available:** use a computer with Windows 11 Professional or Windows 11 Enterprise and hardware that supports Hyper-V. The Hailo PlugIn installer checks whether Hyper-V is available and offers to enable it if necessary.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#support-information) to support, together with the exact message, the installed Podman version and the installation log shown in the setup program of the Hailo PlugIn.

## Problem: Training fails because of insufficient GPU memory or takes unusually long {#faq-gpu-memory}

**Symptoms**

- Training with the training profile `B8x1` fails because of insufficient GPU memory.
- Training takes unusually long.

**Possible causes**

- The GPU memory is insufficient for the training profile `B8x1` (the default value).
- Training is using shared GPU memory. An unusually long training time can also indicate insufficient GPU memory.

**Diagnostic procedure**

1. Check the value of `trainingProfile` in the JSON configuration - expected: `B8x1` (default) or `B4x1`.
2. While training runs, check the shared GPU memory usage in the Windows Task Manager - expected: training does not use shared GPU memory.

**Resolution**

- **If the GPU memory is insufficient for `B8x1` or training uses shared GPU memory:**
  1. Set `trainingProfile` to `B4x1` in the JSON configuration (see [JSON Parameters Description](https://docs.hdvisionsystems.com/en/lumiscan-training/json-settings.html#json-parameters-description)).
  2. Select the configuration file and click **Start Training** again.

> [!NOTE]
> Currently, only one GPU is supported.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#support-information) to support, together with the JSON configuration file and the graphics card model.

## Problem: The model conversion fails with exit code 137 {#faq-exit-code-137}

**Symptoms**

The model conversion fails. The status line of the **Model Conversion (ONNX → Hailo)** dialog shows the exit code `137`, and the log console shows additional information.

**Possible causes**

- The Podman machine has run out of memory during quantization.

**Diagnostic procedure**

1. Read the exit code in the status line - expected for this problem: `137`. For another exit code, see [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#support-information).
2. Read the log console - expected: it shows how to assign additional memory to the virtual machine.
3. Check the system memory of the computer - expected: at least 24 GB (DRAM). The model conversion runs in a virtual machine configured with 18 GB of memory.

**Resolution**

- **If the Podman machine has run out of memory:**
  1. Assign additional memory to the virtual machine as described in the log console.
  2. Click **Start Conversion** again.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#support-information) to support, together with the exit code, the complete content of the log console and the size of the system memory.

## Problem: The model conversion takes longer than expected {#faq-conversion-slow}

**Symptoms**

After **Start Conversion**, the status shows **Converting…** for longer than expected.

**Possible causes**

- It is the first conversion: the Podman machine is started first if it is not already running.
- The ONNX file, the calibration folder or the output folder is located on another drive than `C:`, for example `E:`, or on a network share. The required files are then transferred to the container before the conversion and the results are transferred back afterwards. Depending on the size of the calibration data, this increases the conversion time.

**Diagnostic procedure**

1. Check whether this is the first conversion since the Podman machine was last started - expected: the first conversion takes longer.
2. Check the paths in **ONNX model file**, **Calibration folder** and **Output folder** - expected: all three are on the `C:` drive. If not, the log console displays the additional transfer steps.

**Resolution**

- **If it is the first conversion:** wait until the conversion is complete. The message `Conversion finished successfully.` is displayed when it is done.
- **If the files are on another drive or a network share:** wait until the conversion is complete. The conversion container can access the `C:` drive directly; no transfer is needed for files stored there.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#support-information) to support, together with the three paths of the conversion and the complete content of the log console.

## Problem: A client cannot connect to the shared backend {#faq-client-cannot-connect}

**Symptoms**

A client computer cannot connect to the shared backend server: in a web browser at `http://<server-ip>:8420`, or in a LumiScan Training installation with **Start backend locally** disabled and the server under **Remote backend address**.

**Possible causes**

- The **Backend bind address** of the server is `localhost (127.0.0.1)`. This address only accepts connections from the same computer.
- Windows Firewall on the server does not allow the backend to communicate over the network.
- The backend on the server is not running.
- The server address on the client is not correct.

**Diagnostic procedure**

1. On the client computer, open `http://<server-ip>:8420/api/v1/health` in a web browser - expected: the endpoint responds immediately. If there is no response, continue with the next steps.
2. On the server, open the **App Settings** tab and check **Backend bind address** - expected: the network IP address of the computer, for example `192.168.1.50`, or `0.0.0.0 (all interfaces)`; not `localhost (127.0.0.1)`.
3. On the server, check that Windows Firewall allows the backend to communicate over the network - expected: access is allowed for **Private networks**.
4. On the server, open **App Settings** and check **Backend connection** - expected: **Start backend locally** and **Autostart backend as a service** are enabled. With autostart, the backend starts automatically when the Windows user logs in, even if LumiScan Training itself is not open.
5. On the client, check the server address - expected: the IP address of the server in the browser address or under **Remote backend address**.

**Resolution**

- **If the bind address is `localhost (127.0.0.1)`:**
  1. On the server, select the network IP address of the computer or `0.0.0.0 (all interfaces)` under **Backend bind address**.
  2. Click **Save**.
  3. Restart LumiScan Training, or log out of Windows and log back in.
- **If Windows Firewall blocks the backend:** allow access for **Private networks** on the server. Windows Firewall may ask for this when the backend is first bound to a network-reachable address.
- **If the backend is not running:** on the server, enable **Start backend locally** and **Autostart backend as a service**, click **Save**, and restart LumiScan Training or log out of Windows and log back in.
- **If the server address is wrong:** enter the IP address of the server under **Remote backend address** (or in the browser address), click **Save** and restart LumiScan Training.

See also [Setting Up a Shared Backend Server](https://docs.hdvisionsystems.com/en/lumiscan-training/app-settings.html#app-settings-server) and [Connecting from a Client Computer](https://docs.hdvisionsystems.com/en/lumiscan-training/app-settings.html#app-settings-client).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-training/troubleshooting.html#support-information) to support, together with the IP address of the server, the **Backend bind address** and the result of `http://<server-ip>:8420/api/v1/health` on the client.

## Information for support {#support-information}

Have this information ready when you contact support:

- Product and version: LumiScan Training and its version. The file name of the setup program ends with the version number, for example `Installer_LumiScanTrainingFramework_v2_1_0_0.exe`.
- Operating system: Windows 11 Professional or Windows 11 Enterprise, the graphics card model and the installed CUDA Toolkit and CodeMeter versions. If a Hailo TPU is used: the Podman version and the size of the system memory.
- Where you bought the software: HD Vision Systems or the ctrlX Store.
- The serial number of the LumiScan Key (`3-…`, printed on the key).
- The exact error message, a screenshot and the date and time the problem occurred. For training: the message in **Process Status**. For the model conversion: the exit code in the status line and the complete content of the log console.
- For the shared backend: the settings in **App Settings** on the server and the client (**Start backend locally**, **Backend bind address**, **Remote backend address**) and the result of `http://<server-ip>:8420/api/v1/health`.
- The JSON configuration file used for training.

Contact customer support at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or by phone at +49 6221 6721905. For licences, write to [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).
