# LumiScan Annotation 1.8.4.3 – complete documentation

> All pages of the LumiScan Annotation 1.8.4.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-annotation/1.8.4/

# LumiScan Annotation

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

|   |   |   |
| --- | --- | --- |
| ![A stack of camera images of parts](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/intro/step-1.svg)<br><br>**Collect images of your parts.** PNG images, one folder per set. | ![Annotation window with two parts framed by oriented boxes](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/intro/step-2.svg)<br><br>**Draw a box around each object.** Oriented boxes in three clicks, one label per class. | ![PNG, CSV and JSON file for one image](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/intro/step-3.svg)<br><br>**Save the training data.** Boxes as CSV next to each image, ready for LumiScan Training. |

LumiScan Annotation is the software for annotating objects in images to create training data for neural networks, for example for object detection with LumiScan AI Object Matching. You draw an oriented box around each object in three clicks and assign a label per class; the boxes are saved as a CSV file next to each image. It supports any number of users and unlimited annotations, and runs on Windows 11.

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

# Description – LumiScan Annotation

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

LumiScan Annotation is the software that allows you to annotate objects in an image, providing data for training and retraining Neural Network Models that are later used in tasks such as object detection or quality inspection.\
\
The software allows any number of users, customization of annotation settings, and an unlimited number of annotations.\
\

# Requirements – LumiScan Annotation

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

- Windows 11

## Licence {#licence}

How LumiScan Annotation 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/1.0.4/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/1.0.4/path-ctrlx-windows.html) |

Each device on which LumiScan Annotation 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/1.0.4/index.html).

# How To: Annotate Images with Oriented Bounding Boxes – LumiScan Annotation

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/how-tos/annotate-images-with-oriented-bounding-boxes.html

This guide takes you from the installation of LumiScan Annotation to a set of images annotated with oriented bounding boxes. The annotations are the training data for neural networks, for example for LumiScan AI Object Matching, trained with LumiScan Training.

When you have finished:

- LumiScan Annotation is installed and licensed,
- your images are loaded,
- the object classes are defined as labels,
- the objects in the images are marked with oriented (rotated) bounding boxes, and the annotations are saved next to the images.

This guide covers the operation of the software. How to annotate well - what a box should include, how to handle partly hidden objects - depends on the application and is agreed with the team that trains the network.

## Before you start {#prerequisites}

- Windows 11 PC with mouse and keyboard
- LumiScan Key with a licence for LumiScan Annotation, see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/requirements.html)
- The installer `Installer_LumiScan_Annotation_va_b_c_d.exe`, where `a.b.c.d` is the version
- The images to annotate, as PNG files

## How it fits together {#overview}

LumiScan Annotation shows one image at a time. You draw a box around each object and give it a label, the name of its class. Boxes can be rotated, so they fit objects that lie at any angle.

When you save, the annotations of the image are written as a CSV file next to the image. A JSON file records who saved, when, and which image and file. Several users can annotate the same folders: each save is recorded with the user selected in the application.

## Step 1 - Install CodeMeter Runtime {#step-1-codemeter}

LumiScan Annotation is licensed with the LumiScan Key and needs CodeMeter Runtime 9.00 or later.

1. Check whether CodeMeter Runtime is installed, for example in the Windows Start menu.
2. If not, install it and connect the LumiScan Key to a free USB port, as described in [Installing CodeMeter Runtime](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/installing-codemeter.html).

## Step 2 - Install LumiScan Annotation {#step-2-install}

1. Close all open applications.
2. Double-click `Installer_LumiScan_Annotation_va_b_c_d.exe`.
3. Accept the licence terms.
4. Keep the default installation folder or choose another one with **Browse**, then click **Next**.
5. Click **Install**, then **OK** and **Finish**.

LumiScan Annotation can now be started from the Windows Start menu. The detailed steps are in [Installing LumiScan Annotation on Windows](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/installing-lumiscan-annotation-on-windows.html).

## Step 3 - Prepare the images {#step-3-images}

Put the PNG images to annotate into one folder. To work on several sets, give each set its own folder below a common folder:

```
<data folder>
├── <set A>
│   ├── image_001.png
│   └── image_002.png
└── <set B>
    ├── image_003.png
    └── image_004.png
```

You then select the common folder once and switch between the sets in the application. See [Folder Structure](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/folder-structure.html).

## Step 4 - Start the application and select the images {#step-4-start}

1. Start LumiScan Annotation. On the first start, the window is empty.

2. Click **Menu > Settings**.

3. Click **Set Folder** and select the folder with the images, or the common folder of several sets.

   ![Settings window of LumiScan Annotation with the fields Data Directory](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/howto-obb-settings.png)

   *Figure 1. Settings window with the data directory*

4. Optional: click **User Management** and add your user name, then select it in the **User** field of the main window. Every save is recorded with this name.

5. Close the settings window.

Expected: the images are listed under **List of Pictures**. With several sets, the **Folder** field at the top selects the set.

![Main window of LumiScan Annotation with two annotated packages in the central view](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/howto-obb-main.jpg)

*Figure 2. Main window with an annotated image*

The main window shows, from left to right, the image with its boxes, the list of images, the list of labels, the field to add labels, and sliders for brightness and contrast. The buttons below the image go to the previous image, save, and go to the next image. All elements are described in [User Interface](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html).

## Step 5 - Create the labels {#step-5-labels}

A label is the name of an object class, for example `back` or `foliert`. Create one label for each class the network is to tell apart.

1. Type the name in the field under **Add Label**.
2. Click **Add Label**.

The label appears in the label list with a number. The selected label is given to every new box.

![Label list with the entries 1: back and 2: foliert](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/howto-obb-labels.png)

*Figure 3. Label list and the Add Label field*

## Step 6 - Draw an oriented bounding box {#step-6-draw}

1. Select the label of the object in the label list.
2. Double-click on the image where the **bottom edge** of the box is to be. This edge is always drawn green.
3. Click on the **top edge** of the object, without holding the mouse button. This sets the height.
4. Click on a **side** of the object, again without holding the button. This sets the width.

The box is drawn with the selected label. Its green edge marks the bottom of the object, so the box also records which way the object faces.

![Rotated bounding box around a package](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/howto-obb-box.jpg)

*Figure 4. An oriented bounding box around a package; the green edge marks its bottom*

## Step 7 - Correct and delete boxes {#step-7-correct}

Click a box to select it. A selected box shows four yellow corner handles. Then:

- drag inside the box to move it,
- drag an edge to change its size in that direction,
- drag a corner to rotate it around its centre,
- select another label, or press its number `1` to `9`, to change the label,
- right-click the box to delete it.

For fine adjustments, use the keyboard: `Ctrl`/`Shift` with `i`, `j`, `k`, `l` moves the box by one or ten pixels, with `u` and `o` rotates it by one or ten degrees. All shortcuts are listed in [Image Annotation](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/image-annotation.html) and [Shortcuts for Common Operations](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/shortcuts-for-common-operations.html).

## Step 8 - Save and go to the next image {#step-8-save}

1. Click **save** below the image, or press `s`.
2. Click **next**, or press `d`, to go to the next image. **previous**, or `a`, goes back.

![Buttons previous (a)](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/howto-obb-navigation.png)

*Figure 5. Navigation buttons below the image*

Expected: next to the image, a CSV file with its boxes and a JSON file with the user name, the time, the image name and the name of the CSV file. The image is highlighted in the image list.

> [!TIP]
> When consecutive images differ only a little, press `Alt` + `s` to save and copy the boxes to the next image. Then only correct what has changed.

## Result {#result}

- LumiScan Annotation is installed and licensed.
- The images are loaded, and the object classes are defined as labels.
- The objects are marked with oriented bounding boxes, and the annotations are saved next to the images.

The folders with the images and their annotation files are the input for training. Answers to common questions are in the [FAQ](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/faq.html), problems in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/troubleshooting.html).

# Before Installation – LumiScan Annotation

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/before-installation.html

## Installing CodeMeter Runtime {#installing-the-codemeter-runtime-environment-2}

LumiScan Annotation is licensed with the LumiScan Key and needs CodeMeter Runtime 9.00 or later. Install CodeMeter Runtime and connect the LumiScan Key as described in [Installing CodeMeter Runtime](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/installing-codemeter.html).

# Installing LumiScan Annotation on Windows

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/installing-lumiscan-annotation-on-windows.html

1. Close all open applications on your computer.
2. Navigate to the location of the LumiScan installer.
3. Double-click on the file: `Installer_LumiScan_Annotation_va_b_c_d.exe`\*.
4. The installation is prepared and the license agreement window opens.
5. Accept the license terms by clicking on **Accept**.
6. If you want to change the default installation location, click **Browse**.
7. Navigate to the desired storage location.
8. Press **OK** to confirm your selection.
9. Otherwise, click the **Next** button to continue.
10. If desired, select the **Start Menu** folder for the program links.
11. If you do not want to create shortcuts, select the **Do not create links** option.
12. Then click on **Install**.
13. When the installation is complete, you will see a dialog box.
14. Click **OK**.
15. Click **Finish**.
    - where **a**, **b**, **c**, **d** are variables that depend on the version of the software.

> [!NOTE]
> When you first start the program json settings file named **settings.json** (see JSON Settings Example) will be automatically generated at:\
> `C:\Users\<USER>\AppData\Local\HD Vision Systems GmbH\LumiScan Annotation`

# User Interface – LumiScan Annotation

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

When you start LumiScan Annotation for the first time, an empty window opens (Fig.12).

To start the program:

1. Click on the **Menu \*\*button**.
2. Select the **Settings**.
3. Specify the **Data Directory** in the **Settings** window.

The various elements of the user interface are annotated in [Fig. 13](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example) and explained in [Table 8](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example).

## JSON Settings Example {#json-settings-example}

This JSON settings file is automatically created at `C:\Users\<USER>\AppData\Local\HD Vision Systems GmbH\LumiScan Annotation` the first time the application is started. The `labels` section will be empty at first. You can enter labels there and they will be added automatically.\
If desired, ROI values can also be specified here and loaded automatically.

See below for an example of the default json settings.

```json
{
    "meta": {
        "inputFileType": "LumiScan Annotation Settings",
        "inputFileVersion": "1.6.0.0",
        "targetMachine": "TargetMachine",
        "programName": "LumiScan Annotation",
        "programVersion": "1.6.0.0"
    },
    "labels": ["stuff", "labelB", "somethingElse"],
    "roiSettings": {
        "x": 1.0,
        "y": 1.0,
        "width": 1.0,
        "height": 1.0
    }
}
```

**Table 1. Table 8: LumiScan Annotation: User interface description**

| Nr. | Description |
| --- | --- |
| 1 | Menu: Access to ROI settings, program settings and help. |
| 2 | Folder: Combobox for folder selection. |
| 3 | User: Combobox for user selection.<br><br>- Selected user is saved when changes are made. |
| 4 | List of images from the selected folder.<br><br>- When a new class is saved, the changed image is highlighted.<br>- The highlighting disappears when you change the folder (see **2** in this table) or reload the program. |
| 5 | List of all available labels in the selected folder. |
| 6 | Central view with display of the currently selected image and labels.<br> Image can be deleted by right-clicking. **NOTE: This will also remove the deleted image from the record.** |
| 7 | Shows the selected labels. |
| 8 | Adds a new label. |
| 9 | Adjusting the brightness and contrast of the image. |
| 10 | Navigation menu (see also Navigation). |

![A top-down view shows a person’s hand near a keyboard and mouse next to a tray containing several rectangular objects with green text labels on them](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/example2.png)

# Menu – LumiScan Annotation

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/menu.html

You can select ROI Settings, Settings, and Help from the menu.

![A dark, textured fabric is displayed within a software interface labeled LumScan Annotation, showing options for folder selection, user input, picture list, labels, and brightness and contrast adjustments](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/windowsettings.png)

## ROI Settings {#roi-settings}

In this setting window, you can define the region of interest (ROI) for training the neural network. The ROI defines the part of the captured image in which the network will search for markers. By default, the ROI is set to the entire image size. In the center view, the borders of the ROI are colored blue.

![A software window titled ROI S shows input fields for xmin, ymin, width, and height with values set to 0, 0, 1280, and 960 respectively, and a Close button below](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/roi.png)

## Settings {#settings}

![A software settings window shows options for selecting a data directory labeled Input_Images, adjusting thickness with a slider set to 1.00, and displays the version number 1.3.1.0 with buttons for setting the folder and closing the window](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/menusettings.png)

In this settings window you can:

- Specify the directory from which the marker should load images.
- Open the User Management window.
- Modify the Thickness slider to set the thickness of the bounding box frame.

To specify an input folder, click **Set Folder** and select the folder that contains the images.

### User Management {#user-management}

After you click the User Management button, the Users window opens, where you can add new users or delete existing ones.

To add a new user, type the desired name in the lower edit box, then click **+**. To delete an existing user, select the user in the list and click **-**.

![A dark-themed user interface window titled Users with an empty main area, a text input field at the bottom, and disabled plus and minus buttons](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/users.png)

# Image Annotation – LumiScan Annotation

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/image-annotation.html

Oriented bounding boxes can be manually changed or added in the central view (6 in [Fig. 13](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example)):

\*Adding new boxes: \*There are three steps to adding new boxes:

1. First, double-click with the left mouse button on the position where you want the bottom edge of the bounding box to be. This border will always be green ([Fig. 14](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example)).
2. Without holding down the mouse button, click with the left mouse button on the upper edge of the object to set the height of the bounding box.
3. To determine the width of the bounding box, click on any side point of the object with the left mouse button, again without holding down the mouse button.

The box label corresponds to the active class in the list (**5** auf [Fig. 13](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example)).

**Selecting a bounding box: \*Existing boxes can be selected with a simple left-click. A selected box is highlighted by a slightly different color and four yellow, circular corner handles ([Fig. 14](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example)).** \*

**Modification of existing boxes:** As long as a bounding box is selected, you can change its label by selecting another label from the label overview or by typing a new label.

**Correcting the bounding box**: A selected box can be manipulated in several ways:

- Drag the inside of an active box to move it.
- Dragging the edges of an active box changes its size in that direction.
- Drag the corners of an active box to rotate it around its center.

**Deleting the bounding box**: Right-click an active box to remove it.

| Keyboard shortcut | Operation |
| --- | --- |
| Ctrl/Shift + i/j/k/l | Move current box one/ten pixels in the corresponding direction |
| Ctrl/Shift + u/o | Rotate current box one/ten degrees counter/clockwise. |
| Ctrl/Shift + v/b | Increase/decrease current box height by one/ten pixels |
| Ctrl/Shift + n/m | Increase/decrease current box width by one/ten pixels |

After each saved annotation, the LumiScan Annotation Framework also writes the following information to a JSON file:

- User name
- Unix timestamp
- Image name (PNG)
- Save file name (CSV)

The JSON file is saved in the raw directory under the name of the saved image. Sequential comments are appended so you can track who made a change and when.

# Shortcuts for Common Operations – LumiScan Annotation

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/shortcuts-for-common-operations.html

To perform typical bounding box manipulations, such as rotating, moving, expanding, or extruding, you can use the keyboard shortcuts described in the following table.

**Table 1. Table 9: Keyboard shortcuts for common operations**

| Button | Keyboard shortcut | Operation |
| --- | --- | --- |
| previous | a | Switch to previous image. |
| save | s | Save image. |
| next | d | Switch to next image. |
|   | alt + s | Save and copy labels to next image.<br> Useful when content changes little between images. |
|   | 1-9 | Set label for selected region.<br> This option can also be used to change the label of the bounding box. After selecting the desired box (left mouse button), the name can be changed by entering the desired label number (1 - 9). |

# Navigation – LumiScan Annotation

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/navigation.html

To view the previous or next image, or to save your changes, you can use the button in the navigation menu (10 in [Fig. 13](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example)) or the shortcut keys.\

Table 10: Navigation keys

This table, along with shortcuts for common operations, can also be accessed via **Menu > Help** (Fig. 19).

![A software help window displays keyboard shortcuts in German for navigating and classifying images, with options to close the window](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/_images/helpinfo.png)

# Folder Structure – LumiScan Annotation

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/folder-structure.html

To annotate a single folder of images, simply select the folder containing the png images and start annotating.\
To load multiple folders of images, the images should be located on your hard disk in the following folder structure:

\<Any Folder Name>

\|-----\<Any Folder Name>

```
|
```

```
|---- .png
```

```
|---- *.csv
```

```
|----.json
```

\|-----\<some other folders>

In this case, you can select a folder that contains one or more folders of png images and then use the folder drop-down menu at the top to select the correct folder you want to annotate.

# FAQ – LumiScan Annotation

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

Short answers to common questions and error messages for LumiScan Annotation. 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-settings-file`).

## Requirements, installation and licensing

### Which operating system does LumiScan Annotation require? {#faq-system-requirements}

- **Answer:** Windows 11.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/requirements.html)

### How do I install LumiScan Annotation? {#faq-installation}

- **Answer:** Install CodeMeter Runtime 9.00 or later and connect the LumiScan Key first. Then close all open applications, double-click `Installer_LumiScan_Annotation_va_b_c_d.exe` (a, b, c, d depend on the software version), accept the licence terms with **Accept** and follow the setup wizard to **Finish**.
- **More:** [Installing CodeMeter Runtime](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/before-installation.html#installing-the-codemeter-runtime-environment-2), [Installing LumiScan Annotation on Windows](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/installing-lumiscan-annotation-on-windows.html)

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

- **Answer:** LumiScan Annotation is licensed with the LumiScan Key and needs CodeMeter Runtime 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-annotation/1.8.4/requirements.html#licence), [Installing CodeMeter Runtime](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/installing-codemeter.html), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)

## Getting started

### How must the images be organized? {#faq-folder-structure}

- **Answer:** To annotate a single folder, select the folder containing the PNG images. To work with several folders, select a parent folder that contains one or more folders of PNG images (with their CSV and JSON files) and choose the folder to annotate in the folder drop-down menu at the top.
- **More:** [Folder Structure](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/folder-structure.html)

### Where is the settings file and what can I configure in it? {#faq-settings-file}

- **Answer:** `settings.json` is created automatically at the first start in `C:\Users\<USER>\AppData\Local\HD Vision Systems GmbH\LumiScan Annotation`. Its `labels` section is empty at first; labels you enter there are added automatically. ROI values can also be specified in the `roiSettings` section and are loaded automatically.
- **More:** [JSON Settings Example](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example)

### How do I add or delete users? {#faq-users}

- **Answer:** Open **Menu** > **Settings** and click **User Management**. In the **Users** window, type a name in the lower edit box and click **+** to add a user; select a user in the list and click **-** to delete it. The user selected in the user combobox is saved when changes are made.
- **More:** [User Management](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/menu.html#user-management)

### What is the ROI and how do I set it? {#faq-roi}

- **Answer:** The region of interest (ROI) defines the part of the captured image in which the trained network will search. By default it covers the entire image. Set it in **Menu** > **ROI Settings** or in the `roiSettings` section of `settings.json`; in the central view the ROI borders are shown in blue.
- **More:** [ROI Settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/menu.html#roi-settings)

## Annotating images

### How do I add an oriented bounding box? {#faq-add-bounding-box}

- **Answer:** In the central view (the box gets the label of the active class in the label list):
  1. Double-click with the left mouse button where the bottom edge of the box should be (this edge is always green).
  2. Without holding the mouse button, left-click on the upper edge of the object to set the height.
  3. Left-click on any side point of the object to set the width.
- **More:** [Image Annotation](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/image-annotation.html)

### How do I move, resize or rotate a bounding box? {#faq-edit-bounding-box}

- **Answer:** Select the box with a left-click (it shows four yellow corner handles). Drag its inside to move it, its edges to resize it and its corners to rotate it around its center. With the keyboard, Ctrl/Shift + i/j/k/l moves the box by one/ten pixels, Ctrl/Shift + u/o rotates it by one/ten degrees, Ctrl/Shift + v/b changes the height and Ctrl/Shift + n/m the width by one/ten pixels.
- **More:** [Image Annotation](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/image-annotation.html)

### How do I change the label of a bounding box? {#faq-change-label}

- **Answer:** Select the box with a left-click, then select another label in the label overview, type a new label, or press the label number 1-9.
- **More:** [Image Annotation](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/image-annotation.html), [Shortcuts for Common Operations](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/shortcuts-for-common-operations.html)

### Which keys switch images and save annotations? {#faq-navigation-shortcuts}

- **Answer:** `a` switches to the previous image, `s` saves the image, `d` switches to the next image, and `alt + s` saves and copies the labels to the next image (useful when the content changes little between images). The table of shortcuts can also be opened via **Menu > Help**.
- **More:** [Shortcuts for Common Operations](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/shortcuts-for-common-operations.html), [Navigation](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/navigation.html)

### Can I see who changed an annotation and when? {#faq-change-history}

- **Answer:** Yes. After each saved annotation, LumiScan Annotation writes the user name, a Unix timestamp, the image name (PNG) and the save file name (CSV) to a JSON file. This file is saved in the raw directory under the name of the saved image; later entries are appended.
- **More:** [Image Annotation](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/image-annotation.html)

## Troubleshooting {#troubleshooting}

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

- [The window is empty](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/troubleshooting.html#faq-first-start-empty-window)

## Support

### 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 Annotation

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/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-annotation/1.8.4/troubleshooting.html#support-information) to support.

## General checks {#general-checks}

- Check that the computer runs Windows 11 (see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/requirements.html)).
- Check that CodeMeter Runtime 9.00 or later is installed and the LumiScan Key is connected (see [Installing CodeMeter Runtime](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/before-installation.html#installing-the-codemeter-runtime-environment-2)). Licence problems - 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/1.0.4/troubleshooting.html).
- The settings file `settings.json` is created automatically at the first start in `C:\Users\<USER>\AppData\Local\HD Vision Systems GmbH\LumiScan Annotation`. Labels and ROI values entered there are loaded automatically (see [JSON Settings Example](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/user-interface.html#json-settings-example)).

## Problem: The window is empty {#faq-first-start-empty-window}

**Symptoms**

When you start LumiScan Annotation, an empty window opens. The list of images stays empty.

**Possible causes**

- No data directory has been specified yet. At the first start, the window is empty until a data directory is specified.
- The selected folder does not contain the PNG images in the structure described under [Folder Structure](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/folder-structure.html).

**Diagnostic procedure**

1. Click **Menu** and select **Settings** - expected: the **Settings** window shows the data directory from which the images are loaded.
2. Check the selected folder - expected: it contains the PNG images or, to work with several folders, it contains one or more folders of PNG images (with their CSV and JSON files).
3. If you selected a folder that contains several folders, check the folder drop-down menu at the top - expected: the folder you want to annotate is selected and its images are listed.

**Resolution**

- **If no data directory has been specified:**
  1. Click **Menu** and select **Settings**.

  2. Click **Set Folder** and select the folder that contains the images.

     The images of the folder are listed in the window.

- **If the folder structure does not match:** select the folder that contains the PNG images or, for several folders, a parent folder as described under [Folder Structure](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/folder-structure.html). Then select the folder you want to annotate in the folder drop-down menu at the top.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-annotation/1.8.4/troubleshooting.html#support-information) to support, together with the path of the selected data directory and a screenshot of the **Settings** window.

## Information for support {#support-information}

Have this information ready when you contact support:

- Product and version: LumiScan Annotation and its version number. The **Settings** window (**Menu** > **Settings**) shows the version number; the version is also part of the installer file name `Installer_LumiScan_Annotation_va_b_c_d.exe`.
- Operating system: Windows 11.
- 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.
- The settings file `settings.json` from `C:\Users\<USER>\AppData\Local\HD Vision Systems GmbH\LumiScan Annotation`.

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).
