# LumiScan Annotation Web 2.4.1.2 – complete documentation

> All pages of the LumiScan Annotation Web 2.4.1.2 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-web/

# LumiScan Annotation Web

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

|   |   |   |
| --- | --- | --- |
| ![Browser window: images of parts framed by oriented boxes, two people working at once](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/intro/step-1.svg)<br><br>**Annotate in the browser.** Oriented boxes as center-line rectangles in three clicks, by any number of people at once. | ![Two annotators' boxes over the same part, compared: agreement and one difference marked](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/intro/step-2.svg)<br><br>**Check the quality.** Compare annotators, review the differences, see the agreement. | ![Image (PNG) with its annotation files (CSV boxes, JSON save history), read by LumiScan Training](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/intro/step-3.svg)<br><br>**Train your network.** The boxes are saved as CSV next to each image, ready for LumiScan Training. |

LumiScan Annotation Web is the browser version of LumiScan Annotation. A server on Windows or Linux holds the images and the annotations; annotators only need a web browser and sign in with a local account, the company directory or single sign-on. Work is organised in projects with their own images, members and settings. Several annotators can annotate the same image independently: the server compares their boxes, writes the reference when they agree and shows reviewers where they differ. Box suggestions from your trained networks speed up the work. The files are exactly those of the desktop tool, so LumiScan Training reads them unchanged.

To get started, see [Annotate Your First Images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/annotate-your-first-images.html). Installing the server: [Before Installation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/before-installation.html). Questions or an error message? See the [FAQ](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/faq.html) and [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html).

# Description – LumiScan Annotation Web

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

LumiScan Annotation Web creates the training data for neural networks that detect and locate objects, for example for LumiScan AI Object Matching or LumiScan VGR. You draw an **oriented bounding box** (a rectangle that can be rotated) around each object in an image and give it a label, the class of the object. LumiScan Training learns from these boxes.

It is the successor of the desktop tool LumiScan Annotation. The annotation logic runs in a server; people annotate in their web browser, from any PC in the company network, without installing anything.

## What it offers

- **Annotating:**
  - Oriented boxes drawn as [center-line rectangles](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-line-rectangle) in three clicks, moved, resized and rotated with the mouse or the keyboard.
  - A magnifier with crosshair at the mouse pointer for edges to a tenth of a pixel.
  - Labels with keys 1 to 9, brightness and contrast, a region of interest.
  - For image series: boxes from the previous image, onto the next images, copy and paste, and box templates per label.
  - Undo and redo, and a history of every saved state of every image.
- **Working as a team:**
  - **Projects**: independent annotation jobs, each with its own images, settings and members.
  - **Roles**: annotator, reviewer, project admin and server admin. The server enforces them.
  - **Sign-in** with local accounts, the company directory (Active Directory / LDAP) or single sign-on (OpenID Connect, for example Keycloak or Microsoft Entra ID).
  - **Edit locks**: an image being edited is read-only for the others.
  - **Revision notes**: a reviewer leaves an instruction on an image for an annotator.
- **Quality:**
  - **Several annotators per image**: each annotates the image independently, without seeing the others' boxes.
  - The server compares their boxes. When all agree, it writes the reference annotation itself.
  - Reviewers see the differences numbered on the image and decide with one click.
  - Agreement statistics per annotator, per pair of annotators and per folder.
- **Speed:**
  - **Box suggestions** from your trained LumiScan networks (ONNX), or from an open-vocabulary detector for parts without a network yet. You accept, correct or discard them.
  - **Active learning**: the network rates every image; the ones it is least sure about are annotated first.
  - Search and filters: by file name, without boxes, by label, with notes for you, marked done, by training / validation / test set.
  - **Done marks**: mark an image as finished, also without boxes; `Shift+D` marks and goes on.
- **Data:**
  - The annotation files are byte-identical to those of the desktop tool: a CSV file with the boxes and a JSON file with the save history next to each image. LumiScan Training and other tools read them unchanged.
  - Projects in folders on the server or a network share, or in an S3 bucket (AWS S3, MinIO, SeaweedFS).
  - Export and import of whole projects, for example to send a project to HD Vision Systems for annotation.
  - Images in PNG, JPEG, BMP and TIFF, also multi-page TIFF (page by page), added from the server’s folders or [from the browser](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/adding-images.html).
  - **Export for LumiScan Training**: a ready Training project with a stable split into training, validation and test images; the same images and split also in the **COCO** format for other tools.
  - A **single-PC installation** for one person on one PC, in its own window, without sign-in.
  - Automatic backups of everything the server keeps.

## How it works

The **server** (`lumiscan-annotation-server`, Windows or Linux) serves the web pages and the REST API. It reads the images, writes every annotation file, checks every input and enforces the roles. Its own data (accounts, projects, history, notes) is kept in a database file next to its configuration.

The **browser** shows the images and draws the boxes. Nothing is saved without the server.

The optional **box suggestion service** runs the networks on a computer with a GPU and answers the server’s requests. Images never leave the company network.

```none
browser  --HTTP(S)-->  lumiscan-annotation-server  --->  project folders or S3 bucket
                              |                            <image>.png, .csv, .json
                              +--->  box suggestion service (optional, GPU)
```

## Terms

- **Annotation:** the boxes of one image, saved in `<image>.csv`.
- **Label:** the class of an object, for example `bracket`. The labels of a project are shared by everyone in it.
- **Bottom edge:** the edge of a box drawn in green. It gives the box its direction: an angle of 0 means the box top points up.
- **Reference annotation:** with several annotators per image, the annotation training uses. Written automatically when the annotators agree, or decided by a reviewer.
- **Region of interest (ROI):** the part of the images that is annotated. Suggestions outside it are left out.

# Requirements – LumiScan Annotation Web

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

## Server

|   |   |
| --- | --- |
| Operating system | Windows 11 or Ubuntu 24.04 (64 bit) |
| Storage | Disk space for the images and annotation files. The database (accounts, history, notes) must be on a **local disk** of the server, not on a network share. The project folders may be on a share. |
| Network | One TCP port for the browsers, default `8080`. HTTPS by default (self-signed certificate, your own certificate or a reverse proxy such as nginx or IIS). |
| Optional | Access to the company directory (LDAP/LDAPS) or to an OpenID Connect provider for sign-in; access to an S3 store for projects in buckets. |

## Users

- A current version of Google Chrome, Microsoft Edge or Mozilla Firefox.
- Recommended: a screen of 1280 × 800 pixels or more and a mouse with a wheel. On smaller screens the panels are stacked.
- Nothing to install.

## Box suggestion service (optional)

|   |   |
| --- | --- |
| Operating system | Ubuntu 24.04, Windows 11 or macOS |
| Software | Python 3.12 (the installers set up everything else) |
| Hardware | An NVIDIA GPU (CUDA 11.8 or 12) is recommended. On Windows any DirectX 12 GPU works for your ONNX networks; Apple Silicon works on macOS. A CPU works too, but suggestions then take seconds per image. |
| Networks | Your trained networks as exported by LumiScan Training (`network.onnx` and `network_description.json`) |

See [Box Suggestion Service](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestion-service.html).

## Licence {#licence}

This version of LumiScan Annotation Web runs without a LumiScan Key. For licensing questions, contact HD Vision Systems.

# Annotate Your First Images – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/annotate-your-first-images.html

This guide takes you from signing in to your first saved annotations. You need the address of the server (for example `https://annotation.example.com`) and an account; your administrator gives you both.

## 1. Sign in

1. Open the address in Chrome, Edge or Firefox.
2. Sign in:
   - with your user name and password, or
   - with **Sign in with …** when your company uses single sign-on.
3. At the first sign-in with a local account you choose your own password (at least 10 characters).

![Login page of LumiScan Annotation: product name, sign-in with single sign-on or user name and password, next to an overview of the LumiScan apps Annotation, Training and VGR](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/login.jpg)

## 2. Open a project and an image

1. In the top bar, choose the **Project**. Only projects you take part in are listed; with only one, the list is hidden.
2. Choose the **Folder**, usually one folder per day of recording.
3. Click an image in the list on the left. Images with a filled dot have boxes already.

## 3. Draw a box

Boxes are drawn as a [center-line rectangle](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-line-rectangle): the center line from bottom to top, then the width.

1. Choose the label first: click it in the **Labels** list on the right, or press its number key.
2. Double-click the image where the **bottom** of the object is (or press `N` and click).
3. Click where the **top** of the object is. This draws the center line and sets the height and the angle.
4. Move the mouse sideways and click again. This sets the width on both sides of the center line.

|   |   |   |
| --- | --- | --- |
| ![First click on the bottom edge, the dashed line follows the mouse to the top](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/draw-1.png) | ![Second click on the top: the box follows the mouse sideways; the green line is the bottom edge](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/draw-2.png) | ![Third click: the finished box, selected, with the label bracket and four corner handles](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/draw-3.png) |
| Click bottom, move to the top | Click top, move sideways | Click: the box is finished |

The green edge is the **bottom** of the box. Draw every object of a kind in the same direction, for example bottom always where the part lies flat. The network learns this direction.

> [!TIP]
> The magnifier next to the mouse pointer shows the pixels under it, enlarged, with the position to 0.1 pixel. Switch it off and on with `M`.

## 4. Correct a box

- Drag the box to move it, drag an edge to resize it, drag a corner to rotate it.
- Keys: arrow keys move by 1 pixel (with `Shift` 10 pixels); see [Keyboard Shortcuts](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/keyboard-shortcuts.html).
- Number keys 1 to 9 change the label of the selected box.
- Right-click or `Delete` deletes the selected box. `Ctrl+Z` undoes.

## 5. Save and continue

- **Save** (`S`) writes the boxes. The status in the top bar confirms it, for example **Saved part_002.png**.
- **Save and copy to next** (`Alt+S`) saves, opens the next image and copies the boxes onto it: useful for image series where the parts barely move.
- `A` and `D` open the previous and the next image. If you have unsaved changes, you are asked first.
- **Only images without boxes** shows what is left to do.

Next: [Annotating Images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html) has every function in detail.

# Set Up a Project for a Team – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/set-up-a-project-for-a-team.html

A project is an independent annotation job: one folder of images, its labels and settings, and the people who work on it. This guide sets up a project for a team of annotators with a reviewer. You need the role **Admin** (server administrator).

## 1. Put the images in place

Copy the images (PNG, JPEG, BMP or TIFF) into a folder the server can read, or add them later in the browser ([Adding Images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/adding-images.html)); the folder can be for example `D:\LumiScan\Line7` or a network share mounted on the server. Either the images are directly in that folder, or in one level of sub-folders, typically one per day:

```none
D:\LumiScan\Line7\
    2026-11-02\  image_001.png  image_002.png ...
    2026-11-03\  ...
```

The annotation files are written next to the images. Folders that already contain annotations from the desktop tool are used as they are.

## 2. Create the project

1. Click your name at the top right, then **Projects**.
2. Click **New project**.
3. Enter a **Name** and, if you like, a **Description**.
4. Under **Existing folder on the server** enter the folder, for example `D:\LumiScan\Line7`. Left empty, the server creates an empty project folder; you then add images by importing or copying them in.
5. Click **Create project**.

![Dialog New project with the fields Name, Description, Existing folder on the server and the option Open to all signed-in users](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/new-project.png)

> [!NOTE]
> The folders admins may use can be limited in the server configuration (`project_folders`, see [Configuration](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html)). With S3 buckets configured, the dialog also offers **Store the files in: S3 bucket**, see [Projects in S3 Buckets](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects-in-s3-buckets.html).

## 3. Add the members

1. In the project list, click **Members & access** next to the project.
2. Click **Add member** for every person or group:
   - **User**: an account of the server, by its user name.
   - **Group**: a group of your company directory or single sign-on, for example `Annotation Team`. Everyone in the group gets the roles, also people who sign in for the first time later.
3. Tick the roles: **Annotator** draws and saves boxes, **Reviewer** compares and decides, **Project admin** manages the members and settings of this project.
4. Click **Save**.

![Dialog Members and access of the project Line 5 – brackets: name, description, the option open to all, and a table of members with user or group, name and the roles annotator, reviewer and project admin](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/members.png)

Alternatively, tick **Open to all signed-in users**: then everyone works in the project with their server-wide roles (see [Users and Roles](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/users-and-roles.html)).

## 4. Set the labels and options

1. Choose the new project in the top bar.
2. Click **Settings**.
3. Enter the labels, one per line, for example `bracket`, `nut`, `washer`. The order gives the keys 1 to 9.
4. Optional: a region of interest, two or more annotators per image (see [Check Annotations with Two Annotators](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/check-annotations-with-two-annotators.html)), box suggestions.
5. Click **Save settings**.

See [Project Settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html) for every option.

## 5. Tell the team

Send the members the server’s address. They sign in, choose the project in the top bar and start; see [Annotate Your First Images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/annotate-your-first-images.html).

# Check Annotations with Two Annotators – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/check-annotations-with-two-annotators.html

Two people who annotate the same image independently rarely draw exactly the same boxes. Where they differ, the image is hard or the instructions are unclear. LumiScan Annotation Web uses this to improve the training data: the server compares the annotators, writes the reference itself when they agree and shows a reviewer exactly where they differ.

## 1. Switch it on

A project admin opens **Settings** and sets, under **Several annotators per image**:

- **Annotators per image**: `2` (or more).
- **Agree: overlap ≥ %**: how much two boxes must overlap to count as the same box, default 85 %.
- **Agree: angle within °**: default 5°.
- **Write the reference automatically when all annotators agree**: on.

## 2. Annotate blind

Annotators work as usual in the mode **Annotate**. Each sees only their own boxes, never the others'. The image list shows how many have annotated an image (`1/2`).

![Annotate mode with two annotators per image: the image list shows 1/2 or 2/2 per image, the image shows only the annotator’s own boxes](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/annotate-blind.jpg)

When the last annotator saves:

- **all agree**: same objects, same labels, overlap and angle within the limits. The server writes the mean boxes as the reference `<image>.csv`. The status says **Saved. All 2 annotators agree: reference annotation written**.
- **they differ**: the image goes to review.

## 3. Review the differences

Reviewers switch to **Review** in the top bar. The list is sorted by the largest differences first.

![Review mode: the boxes of the two annotators in blue and orange on the image, numbered red markers where they differ, and the list of differences on the right](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/review.jpg)

Every annotator has a colour; red numbered markers show the differences:

- a box only one person drew,
- overlap too small,
- angle too different,
- bottom edge on the opposite side,
- different label.

For each difference, the panel on the right offers the boxes of each person, **Average** or **None**. Click **Show** to zoom to it. When every difference is decided, **Save** writes the reference annotation. A reviewed reference is never overwritten automatically.

![Differences panel: two annotators, two of seven objects differ; for each difference the buttons Show, the annotators' names, Average and None](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/review-differences.png)

## 4. Read the statistics

**Statistics** in the top bar shows the agreement for a folder or the whole project:

![Agreement between annotators: images with two annotators, share of images and objects that agree, mean overlap; tables per annotator, per pair, differences by kind and the images with the largest differences](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/statistics.png)

- **Per annotator**: overlap with the consensus and systematic habits, for example boxes drawn wider than the others (width +3 %) or rotated.
- **Pairs of annotators**: agreement (F1) and mean overlap.
- **Differences by kind** and **Largest differences**: click an image to review it.

Use the per-annotator figures to improve the instructions: a systematic deviation usually means the rule was not clear.

More: [Several Annotators per Image](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html).

# Annotate Faster with Box Suggestions – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/annotate-faster-with-box-suggestions.html

Correcting a suggested box is much faster than drawing it. With a box suggestion service, LumiScan Annotation Web asks your trained network for boxes on the open image; you only check and correct them.

## The loop

1. Annotate the first few hundred images by hand.
2. Train a network with LumiScan Training.
3. Copy the exported network into the box suggestion service (see [Box Suggestion Service](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestion-service.html)).
4. Annotate the next images with suggestions: accept, correct, add what is missing.
5. Train again with the larger data set. Every round makes the suggestions better.

For parts without a network yet, the service can run an open-vocabulary detector that finds objects by the names of the labels.

## 1. Choose the network for the project

A project admin opens **Settings** and, under **Box suggestions**, chooses the **Network** of the project. If the service has only one network, it is used without choosing. Also set:

- **Suggest from confidence %**: suggestions below are left out (default 30 %).
- **At most boxes per image**: default 50.

## 2. Get suggestions

Open an image and click **Suggest boxes** (`P`). After a moment, the suggestions appear as **dashed boxes** with their confidence:

![An image with dashed suggested boxes labelled bracket, nut and washer with their confidence in percent; on the right the note that the suggestions are not accepted yet, with the buttons Accept all and Discard](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/suggestions.jpg)

Boxes already on the image and suggestions outside the region of interest are not suggested again.

## 3. Accept, correct or discard

- **Correct** a suggestion (move, resize, rotate, change the label): it is accepted.
- Select a suggestion and press `Enter`: it is accepted as it is.
- Right-click: it is deleted.
- **Accept all** / **Discard** handle all remaining suggestions.

![Seven suggested boxes not accepted yet. Correcting one, or Enter on the selected one, accepts it. Buttons Accept all and Discard](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/suggestions-bar.png)

If you save with suggestions still open, you are asked whether to accept them or leave them out. Suggestions are never saved by themselves.

> [!TIP]
> Check every suggestion, also those with a high confidence. A network trained on corrected suggestions repeats its own mistakes if they are not corrected.

# Before Installation – LumiScan Annotation Web

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

Clarify these points before you install the server. Each links to the page with the details.

| Question | Options |
| --- | --- |
| Which computer runs the server? | A Windows 11 or Ubuntu 24.04 computer that is on whenever people annotate. It needs little computing power; its disks matter more. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/requirements.html). |
| Where are the images? | In folders on the server or on a network share mounted on it, or in an S3 bucket (AWS S3, MinIO, SeaweedFS). Folders that the desktop tool used are taken over as they are. See [Projects](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects.html) and [Projects in S3 Buckets](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects-in-s3-buckets.html). |
| How do people sign in? | Local accounts managed in the browser, the company directory (Active Directory / LDAP), single sign-on (OpenID Connect) or a combination. Keep at least one local administrator. See [Sign-in Methods](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/sign-in-methods.html). |
| HTTPS? | On by default, with a self-signed certificate that browsers warn about until it is trusted. Decide whether to use a certificate of your company’s CA instead, or a reverse proxy with TLS. See [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html#https). |
| Box suggestions? | Needs a computer with a GPU for the box suggestion service, and your trained networks. Can be added later. See [Box Suggestion Service](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestion-service.html). |
| Backups? | The server backs up its database and configuration automatically. The images and annotation files are backed up with the folders themselves. See [Backup and Restore](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/backup-and-restore.html). |

## What you need

- The release archive `LumiScanAnnotationWeb-<version>-win64.zip` (Windows), or the Linux build, from HD Vision Systems.
- Administrator rights on the server computer.
- For the directory: the address of a domain controller and a read-only service account. For single sign-on: a client registered at the identity provider.

# Installing the Server – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/installing-the-server.html

## Windows 11

1. Unpack `LumiScanAnnotationWeb-<version>-win64.zip`, for example to `C:\LumiScanAnnotationWeb`. It contains:
   ```none
   C:\LumiScanAnnotationWeb\
       lumiscan-annotation-server.exe    the server
       www\                              the web pages
       config\annotation-server.example.json
       README.md, Changelog.md
   ```
2. Copy `config\annotation-server.example.json` to `config\annotation-server.json` and adapt it, see [Configuration](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html). To start, set at least `port` and either `data_root` (an existing image folder) or `projects_root`.
3. Start the server in a command prompt:
   ```bat
   cd C:\LumiScanAnnotationWeb
   lumiscan-annotation-server.exe --config config\annotation-server.json
   ```
4. Allow the port (default 8080) in the Windows firewall for the network the users are in.

## Ubuntu 24.04

1. Copy the server and the `www` folder, for example to `/opt/lumiscan-annotation-web`, and the configuration to `/etc/lumiscan-annotation-web/annotation-server.json`.
2. Create a service account that may read and write the project folders:
   ```bash
   sudo useradd --system --home-dir /var/lib/lumiscan-annotation-web --create-home --shell /usr/sbin/nologin lsa
   sudo chown -R lsa: /etc/lumiscan-annotation-web
   ```
3. Start it once by hand to check the configuration:
   ```bash
   sudo -u lsa /opt/lumiscan-annotation-web/lumiscan-annotation-server --config /etc/lumiscan-annotation-web/annotation-server.json
   ```

## First sign-in

At the first start, with no accounts yet, the server creates the local user `admin` with a random password and writes it to `initial-admin-password.txt` next to the database (the log names the file).

1. Open `https://<server>:8080/` in the browser. The browser warns about the self-signed certificate: compare the fingerprint with the server log and continue, see [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html#https).
2. Sign in as `admin` with that password.
3. Choose a new password. The file is then deleted.
4. Create the other accounts, or set up the directory or single sign-on, see [Users and Roles](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/users-and-roles.html).

If nobody can sign in as administrator any more:

```none
lumiscan-annotation-server --config <configuration> --reset-password admin
```

This prints a new password (and creates the account if it is missing). It must be changed at the next sign-in.

## Starting the server automatically

The server is one program without a window. Start it at boot with the usual tools of the operating system, as the service account.

- **Linux (systemd), `/etc/systemd/system/lumiscan-annotation-web.service`:**
  ```ini
  [Unit]
  Description=LumiScan Annotation Web
  After=network-online.target
  Wants=network-online.target

  [Service]
  User=lsa
  ExecStart=/opt/lumiscan-annotation-web/lumiscan-annotation-server --config /etc/lumiscan-annotation-web/annotation-server.json
  Restart=on-failure

  [Install]
  WantedBy=multi-user.target
  ```

  Then `sudo systemctl enable --now lumiscan-annotation-web`.

- **Windows (Task Scheduler), in an administrator PowerShell:**
  ```powershell
  $exe = "C:\LumiScanAnnotationWeb\lumiscan-annotation-server.exe"
  $action = New-ScheduledTaskAction -Execute $exe -Argument "--config C:\LumiScanAnnotationWeb\config\annotation-server.json" -WorkingDirectory "C:\LumiScanAnnotationWeb"
  $trigger = New-ScheduledTaskTrigger -AtStartup
  $settings = New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit ([TimeSpan]::Zero)
  Register-ScheduledTask -TaskName "LumiScan Annotation Web" -Action $action -Trigger $trigger -Settings $settings -User "SYSTEM" -RunLevel Highest
  ```

  The account must be able to read and write the project folders; for network shares, use a domain service account instead of `SYSTEM`.

## Command-line options

Options on the command line override the configuration file.

|   |   |
| --- | --- |
| `--config <file>` | the configuration file (JSON) |
| `--data-root <dir>` | a folder with images, becomes the project `default` |
| `--bind <address>`, `--port <port>` | listen address (default `0.0.0.0`) and port (default `8080`) |
| `--https <mode>` | `auto`, `on` or `off`, see [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html#https) |
| `--web-root <dir>` | the web pages (default: `www` next to the program) |
| `--log-dir <dir>` | write rotating log files there |
| `--database <file>` | the database (default: `annotation-server.db` next to the configuration); local disk only |
| `--backup <file>` | write a backup and exit; works while the server runs |
| `--restore <file>` | restore a backup and exit; the server must be stopped (`--force` skips that check) |
| `--reset-password <user>` | give a local user a new random password, print it and exit |
| `--version`, `--help` | version, list of options |

## Updating

1. Stop the server. Optional, but recommended: make a backup first (`--backup`, see [Backup and Restore](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/backup-and-restore.html)).
2. Replace the program and the `www` folder. Keep the configuration and the database.
3. Start the server. It updates its database itself if needed.
4. Users reload the page in the browser.

# Single-PC Installation – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/single-pc-installation.html

For one person on one PC, for example a laptop at the production line, a PC without network or a trial, LumiScan Annotation Web runs on that PC only. It is the same program as on a server, in a window of its own and without sign-in.

![LumiScan Annotation in its own window on a single PC: no sign-in, the user menu says single-PC installation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/single-pc-window.jpg)

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/single-pc-installation.mp4)

## Installing

1. Run the LumiScan Annotation Web setup (`setup.exe`) and follow it. It installs into `C:\Program Files\LumiScan Annotation Web` and adds **LumiScan Annotation Web** to the start menu and the desktop. The Visual C++ runtime is installed with it if missing.
2. Start **LumiScan Annotation Web**. The window opens maximised; there is no sign-in.
3. Add your images under your name → **Projects** → **New project**, choosing an existing image folder or a new one, as described in [Projects](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects.html).

Requirements: Windows 10 or 11 (64 bit) with the Microsoft Edge WebView2 Runtime, which is part of Windows 11 and of current Windows 10 installations. Without it, LumiScan Annotation opens in the default web browser instead.

## Working

Everything works as on a server, with these differences:

- There is no sign-in. You are the local account, named after your Windows user, and hold every role: annotator, reviewer and admin.
- The user menu says **single-PC installation, no sign-in**; there is no **Log out**, **Change password** or **Users and sign-in**.
- Closing the window with unsaved changes asks first: **Save**, **Discard** or **Cancel**. Closing stops LumiScan Annotation.
- Starting it a second time brings the open window to the front.
- Only this PC can reach it (127.0.0.1). Other PCs cannot open it, even in the same network.

## Data folder

Everything the program writes is in your user profile:

```none
%LOCALAPPDATA%\HD Vision Systems\LumiScan Annotation Web\
    config.json      configuration (created at the first start)
    networks\        trained networks for box suggestions
    projects\        projects created here (images you add, annotation files)
    backups\         automatic backups
    logs\            log files
```

Image folders you add as projects stay where they are; their annotation files are written next to the images, as on a server.

## Box suggestions without a server {#box-suggestions-without-a-server}

The single-PC installation runs your trained networks itself, without a box suggestion service:

1. Copy the exported network folder from LumiScan Training (with `network.onnx` and `network_description.json`) into `networks\` in the data folder, for example `networks\line-5-parts\`.
2. Close and start LumiScan Annotation again.
3. In the [project settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html#box-suggestions), choose the network under **Box suggestions**.

**Suggest boxes** (`P`) and [Rate with network](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html#rate-with-network) then work as on a server. The networks run on the processor; how long one image takes depends on the network and the PC.

## Licence

Depending on your licence, LumiScan Annotation needs the **LumiScan Key** (a CodeMeter USB key) plugged into this PC. Without a valid licence the app says so and stops accepting changes until the key is back.

## Updates

Once a day LumiScan Annotation looks on docs.hdvisionsystems.com whether a newer version is out. If so, **Version … available** appears in the top bar; it links to the release notes. Nothing is downloaded or installed by itself: install the new setup over the old one, your data stays.

To switch the check off, set `"update_check": false` in `config.json`.

## Without the window

`Start LumiScan Annotation.cmd` in the installation folder starts LumiScan Annotation in the background and opens it in the default browser; `Stop LumiScan Annotation.cmd` stops it.

# Configuration – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html

The server reads one JSON file, given with `--config`. An example with every section is in `config\annotation-server.example.json`. Relative paths are relative to the folder of the configuration file. Secrets (passwords, keys) can be kept in separate files that only the service account may read: use the keys ending in `_file`.

## Example

```json
{
  "bind": "0.0.0.0",
  "port": 8080,
  "public_url": "https://annotation.example.com",
  "projects_root": "../projects",
  "project_folders": ["D:/LumiScan"],
  "data_root": "D:/LumiScan/annotation-data",
  "database": "annotation-server.db",
  "web_root": "../www",
  "log_dir": "../logs",
  "backup": { "dir": "../backups", "every_hours": 24, "keep": 14 },
  "pre_annotation": [
    { "url": "http://gpu-server:8090", "token_file": "preannotate.token" }
  ],
  "auth": {
    "local_login": true,
    "default_role": "annotator",
    "ldap": { "enabled": false },
    "oidc": { "enabled": false }
  }
}
```

## Keys

| Key | Meaning |
| --- | --- |
| `bind`, `port` | Listen address (default `0.0.0.0`, all network interfaces) and port (default `8080`). |
| `public_url` | The address users open, for example `https://annotation.example.com`. Needed behind a reverse proxy and for single sign-on (redirect address). |
| `https` | `auto` (default), `on` or `off`. See [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html#https). |
| `tls_cert`, `tls_key` | Certificate and private key (PEM) for HTTPS. Without them the server uses a self-signed certificate. See [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html#https). |
| `tls_names` | Optional list: further host names or IP addresses for the self-signed certificate. |
| `web_root` | The web pages. Default: `www` next to the program. |
| `data_root` | Optional: an image folder that becomes the project `default`, open to all users. This is how existing installations of version 2.0 keep working. |
| `projects_root` | Folder for new and imported projects. Default: `projects` next to the configuration. |
| `project_folders` | Optional list: admins may create projects on existing folders only below these. |
| `s3_targets` | Optional list of S3 buckets for projects, see [Projects in S3 Buckets](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects-in-s3-buckets.html). |
| `pre_annotation` | Optional: one box suggestion service or a list of them, each with `url`, `token_file` (or `token`), `timeout_s`, `enabled`. See [Box Suggestion Service](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestion-service.html). An entry `{"type": "onnx", "networks": "networks"}` runs the networks in that folder inside the server instead (builds with built-in networks, such as the [single-PC installation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/single-pc-installation.html)). |
| `update_check` | `true`: once a day the server asks docs.hdvisionsystems.com which version is current and shows project admins **Version … available**. Nothing is downloaded. Default: off; on in the single-PC installation. |
| `database` | The database: accounts, sessions, projects, history, notes. Default: `annotation-server.db` next to the configuration. **Local disk only**, never on a network share. |
| `index_refresh_seconds` | How often the project folders are scanned for changes made outside the web app. Default 60. |
| `upload_max_mb` | Largest image file project admins may [add through the browser](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/adding-images.html), in MB. Default 2048. |
| `translations_dir` | Folder with your own translation tables of the interface; they win over the tables installed with the app. Default: `translations` next to the configuration. See [Languages and Translations](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/languages-and-translations.html). |
| `lock_lease_seconds` | How long an edit lock lasts without renewal. Default 60; the browser renews it while the image is open. |
| `log_dir` | Folder for rotating log files. Without it, the log goes to the console only. |
| `backup.dir`, `backup.every_hours`, `backup.keep` | Automatic backups: folder (default `backups` next to the configuration), interval in hours (default 24), number kept (default 14). See [Backup and Restore](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/backup-and-restore.html). |
| `auth` | Sign-in methods and sessions, see [Sign-in Methods](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/sign-in-methods.html). |
| `license` | Prepared for the LumiScan Key; not used by this version. |

## HTTPS {#https}

The server speaks HTTPS by default, so passwords and session cookies never travel unencrypted. Users open `https://<server>:<port>/`, for example `https://annotation-pc:8080/`. The port speaks either HTTPS or HTTP: an address with `http://` gets no answer.

- **Self-signed certificate (default):** Without `tls_cert` and `tls_key`, the server creates a certificate at the first start and keeps it in the folder `tls` next to the configuration (`self-signed-cert.pem`, `self-signed-key.pem`). Nothing needs to be set up.
  - The certificate names the computer’s host name, `localhost`, the computer’s network addresses, the host of `public_url` and the entries of `tls_names`. Add to `tls_names` any further name or IP address users type, for example a DNS alias.
  - It is valid for 825 days. The server renews it 30 days before it expires, also while it runs, and when a name from `public_url` or `tls_names` is missing in it.
  - Browsers show a warning such as "Your connection is not private" until they trust the certificate. Compare the SHA-256 fingerprint in the warning’s certificate details with the one the server log shows at the start (`HTTPS: SHA-256 fingerprint …`), then continue. To avoid the warning, import `self-signed-cert.pem` on the clients as a trusted certificate (Windows: **Trusted Root Certification Authorities**, macOS: Keychain, **Always Trust**), or use a certificate of your company’s CA.
  - Back up the `tls` folder with the configuration (the automatic backups include it). A new certificate means a new warning on every client.

- **Your own certificate:** Set `tls_cert` and `tls_key` to the PEM files of a certificate from your company’s CA or a public CA (the certificate with its intermediate certificates) and its key. The server checks at the start that both belong together and warns 30 days before the certificate expires. Restart the server after replacing the files.
  ```json
    "tls_cert": "tls/annotation.pem",
    "tls_key": "tls/annotation.key",
  ```

- **Behind a reverse proxy (nginx, IIS, Apache):** The proxy terminates TLS and forwards to the server on the same computer, for example on `127.0.0.1:8080`. With `"bind": "127.0.0.1"` the server stays on plain HTTP by itself (`"https": "auto"`); otherwise set `"https": "off"`. Set `public_url` to the address users open. The proxy should send the header `X-Forwarded-Proto: https`, so the session cookie is marked secure.
  ```nginx
  server {
      listen 443 ssl;
      server_name annotation.example.com;
      ssl_certificate     /etc/ssl/annotation.pem;
      ssl_certificate_key /etc/ssl/annotation.key;
      client_max_body_size 64m;
      location / {
          proxy_pass http://127.0.0.1:8080;
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-Proto https;
          proxy_read_timeout 600s;
      }
  }
  ```

  `client_max_body_size` must allow the 8 MB pieces of a project import.

## Sessions and security

- Sign-in creates a session cookie (HttpOnly, SameSite=Lax, Secure over HTTPS). A session ends after `auth.session_hours` without activity (default 12) and after `auth.max_session_days` at the latest (default 7).
- After 5 failed sign-ins an account is blocked for 15 minutes (30 failed attempts per network address).
- Disabling a user or resetting a password ends their sessions at once.
- Every change request needs the header `X-Requested-With: lsa`, which protects against cross-site requests.

# Sign-in Methods – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/sign-in-methods.html

Everyone signs in; the name in the save history of every image is the signed-in user. Three methods can be combined. They and their secrets are configured only in the server’s configuration file (section `auth`), never in the browser.

![Sign-in card with the button Sign in with Company SSO, the fields user name and password for the company account, and the language list at the bottom](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/login-card.png)

## Local accounts

`"local_login": true` (default). Admins create local accounts in the browser (see [Users and Roles](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/users-and-roles.html)). Passwords have at least 10 characters and are stored as PBKDF2-SHA256 hashes with 600 000 rounds.

> [!TIP]
> Keep at least one local administrator, also with the directory or single sign-on. It is your way in when the directory is not reachable.

## Active Directory / LDAP

The server searches the user with a read-only service account, checks the password with a sign-in as that user and reads the groups. Users sign in with the same name and password as on their work computer.

```json
"ldap": {
  "enabled": true,
  "label": "company account",
  "url": "ldaps://dc01.ad.example.com:636",
  "ca_file": "company-root-ca.pem",
  "bind_dn": "CN=ldap-bind,OU=Service Accounts,DC=ad,DC=example,DC=com",
  "bind_password_file": "ldap-bind.secret",
  "base_dn": "DC=ad,DC=example,DC=com",
  "user_filter": "(&(objectClass=user)(sAMAccountName={username})(!(userAccountControl:1.2.840.113556.1.4.803:=2)))",
  "group_attribute": "memberOf",
  "group_filter": "(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={dn}))"
}
```

|   |   |
| --- | --- |
| `url` | `ldaps://host:636` (recommended) or `ldap://host:389` with `"start_tls": true`. The certificate is checked against `ca_file` or the system’s certificate store. |
| `bind_dn`, `bind_password_file` | The read-only service account. Empty: anonymous search. |
| `base_dn`, `user_filter` | Where and how users are searched; `{username}` is replaced by the name entered. The example skips disabled accounts. |
| `group_attribute` | Groups on the user entry (`memberOf` in Active Directory). |
| `group_filter`, `group_base_dn` | Optional group search; the example finds nested groups in Active Directory. `{dn}` and `{username}` are replaced. |
| `username_attribute`, `display_name_attribute`, `email_attribute` | Defaults `sAMAccountName`, `displayName`, `mail`. |
| `label` | Name shown on the sign-in page. |
| `timeout_s` | Default 10. |

No extra library is needed: the LDAP client is part of the server.

## Single sign-on (OpenID Connect)

Users click **Sign in with …** and sign in at the company’s identity provider (authorization code flow with PKCE). Signing out also ends the session at the provider.

1. Register a **confidential client** at the provider with the redirect address `<public_url>/api/auth/oidc/callback`.
2. Configure it:
   ```json
   "oidc": {
     "enabled": true,
     "label": "Company SSO",
     "issuer": "https://sso.example.com/realms/example",
     "client_id": "lumiscan-annotation",
     "client_secret_file": "oidc-client.secret",
     "scopes": "openid profile email",
     "username_claim": "preferred_username",
     "groups_claim": "groups"
   }
   ```
3. Set `public_url` (see [Configuration](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html)).
   - **Keycloak:** Client with **Client authentication** on, **Valid redirect URI** as above, **Valid post logout redirect URI** `<public_url>/`, and a mapper \*Group Membership with the claim name `groups`. Alternatively client roles: `"groups_claim": "resource_access.lumiscan-annotation.roles"`.
   - **Microsoft Entra ID:** Issuer `https://login.microsoftonline.com/<tenant>/v2.0`; `"groups_claim": "groups"` (group object IDs) or app roles with `"roles"`.

## Who gets which role

- New directory and single sign-on users get `default_role` (default `annotator`; empty: no role until an admin or a group mapping gives one).
- Names listed in `initial_admins` become admins at their first sign-in.
- **Groups → roles** in the browser gives roles to whole groups; they are refreshed at every sign-in. See [Groups and roles](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/users-and-roles.html#groups).
- Users without any role cannot sign in; they are told to ask an administrator and are listed for the admins.

Under your name → **Users and sign-in** → **Sign-in methods**, admins see what is configured, the redirect address to register at the provider, and can test a directory sign-in:

![Tab Sign-in methods: local accounts, directory settings with a form to test a directory sign-in, single sign-on settings with the redirect URI](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/sign-in-methods.png)

# Box Suggestion Service – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestion-service.html

The box suggestion service suggests boxes for the open image (see [Box Suggestions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestions.html)). It runs on a computer of yours, ideally with a GPU; no image leaves the company network. It is a separate program, so the annotation server itself needs no GPU.

## Backends

| Backend | What suggests | Needs |
| --- | --- | --- |
| `onnx` (default) | **Your trained LumiScan networks**: `network.onnx` + `network_description.json` as exported by LumiScan Training | ONNX Runtime (CPU, CUDA or DirectML) |
| `grounded-sam` | An open-vocabulary detector (Grounding DINO) finds the objects named by the labels; SAM 2 cuts each one out. For parts without a network yet. | PyTorch; GPU recommended; about 1 GB of models, downloaded at the first start |
| `threshold` | Classical image processing: bright parts on a dark background | nothing extra |

The service sends outlines; the annotation server fits the smallest oriented box around each outline.

## Installing

The service and its installers are in the folder `preannotate` of LumiScan Annotation Web; ask HD Vision Systems for it if it is not part of your delivery. Copy the folder to the computer that will run the service. The installers in `preannotate/install` set up Python, the packages for the backend, an access token and the start at boot, and print the line for the server configuration at the end.

| System | Command | Runs as |
| --- | --- | --- |
| Ubuntu 24.04 | `sudo preannotate/install/install-ubuntu.sh --gpu cuda11` | systemd service `lsa-preannotate` |
| Windows 11 | `preannotate\install\install-windows.ps1 -Gpu cuda11` in an administrator PowerShell; needs Python 3.12 (`winget install Python.Python.3.12`) | scheduled task "LumiScan PreAnnotate" at startup, as SYSTEM |
| macOS | `preannotate/install/install-macos.sh` | launch agent of the user |

Options (on Windows with a leading dash and capital letter, for example `-Backend`):

|   |   |
| --- | --- |
| `--backend onnx\|grounded-sam\|threshold` | the backend (default `onnx`) |
| `--gpu cpu\|cuda\|cuda11` | `cuda` for CUDA 12, `cuda11` for CUDA 11.8 with cuDNN 8 (as on LumiScan PCs), `cpu` without GPU; on Windows also `directml` for any DirectX 12 GPU |
| `--port`, `--host` | address of the service (default port 8090) |
| `--instance <name>` | a second service on the same computer, for example Grounding DINO next to the networks |
| `--dry-run` | print every step without doing it |
| `--uninstall` | remove the service; program and networks are kept |

Example: networks on an NVIDIA GPU, plus Grounding DINO as a second service:

```bash
sudo preannotate/install/install-ubuntu.sh --gpu cuda11
sudo preannotate/install/install-ubuntu.sh --backend grounded-sam --gpu cuda11 --instance dino --port 8091
```

## Adding your networks

Copy each network folder as exported by LumiScan Training into the networks folder of the service, one folder per network. The folder name is the network’s name.

```none
networks/
  line-5-parts/      network.onnx  network_description.json
  housing-seams/     network.onnx  network_description.json
```

Networks folder:

- Ubuntu: `/var/lib/lsa-preannotate/networks`
- Windows: `C:\ProgramData\LumiScan\PreAnnotate\networks`
- macOS: `~/Library/Application Support/LumiScan/PreAnnotate/networks`

Then restart the service (Ubuntu: `sudo systemctl restart lsa-preannotate`; Windows: `Restart-ScheduledTask "LumiScan PreAnnotate"`).

The service prepares the images exactly as LumiScan Training does (size, colour order, normalisation from `network_description.json`) and decodes the network’s output into oriented boxes. Class names come from `classList`; only classes that are labels of the project are suggested. For networks trained on BGR images, start the service with `--bgr`.

## Connecting the annotation server

Add the service, or several, to the server configuration and restart the server. Copy the token file the installer created next to the configuration.

```json
"pre_annotation": [
  { "url": "http://gpu-server:8090", "token_file": "preannotate.token" },
  { "url": "http://gpu-server:8091", "token_file": "preannotate-dino.token" }
]
```

- With several services, all are asked; of overlapping suggestions the most confident is kept.
- If one does not answer, the others still suggest and the browser shows a warning.
- The server log names each service at the start, with its backend and networks.

The button **Suggest boxes** appears in the browser as soon as a service is configured. The network of each project is chosen in its [settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html#box-suggestions).

## Checking the service {#checking-the-service}

```bash
curl -H "Authorization: Bearer $(sudo cat /etc/lsa-preannotate/default.token)" http://127.0.0.1:8090/v1/health
```

The answer lists the backend, the device and the networks with their classes. Logs: Ubuntu `journalctl -u lsa-preannotate -f`; Windows `C:\ProgramData\LumiScan\PreAnnotate\default.log`.

# Projects in S3 Buckets – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects-in-s3-buckets.html

Instead of a folder on the server, a project can keep its files in an S3 bucket: AWS S3, MinIO, SeaweedFS or any other store that speaks the S3 API. Below the project’s prefix the layout is exactly that of a project folder (date folders, `<image>.png`, `.csv`, `.json`), so a folder can be copied into a bucket and back with any S3 tool (`aws s3 sync`, `mc mirror`, …) and LumiScan Training reads the same files.

## 1. Configure the buckets

The server admin adds the buckets to the configuration. The access keys stay in the configuration; the browser only ever sees the name.

```json
"s3_targets": [
  { "name": "aws-frankfurt", "endpoint": "https://s3.eu-central-1.amazonaws.com",
    "region": "eu-central-1", "bucket": "annotation-data", "path_style": false,
    "access_key_id": "AKIA...", "secret_access_key_file": "aws-annotation.secret" },
  { "name": "seaweedfs-lab", "endpoint": "https://s3.lab.example.com:8333", "bucket": "annotation",
    "path_style": true, "access_key_id": "annotation-server",
    "secret_access_key_file": "seaweedfs-annotation.secret", "ca_file": "root-ca.pem" }
]
```

| Key | Meaning |
| --- | --- |
| `name` | Shown to admins when they create a project; projects refer to it. Do not rename it later. |
| `endpoint` | `https://s3.<region>.amazonaws.com` (AWS), `http(s)://host:9000` (MinIO), `http(s)://host:8333` (SeaweedFS) |
| `region` | The bucket’s region for AWS, for example `eu-central-1`; MinIO and SeaweedFS accept `us-east-1`. |
| `bucket` | The bucket; it must exist. |
| `path_style` | `true`: `endpoint/bucket/key` (MinIO, SeaweedFS; default). `false`: `bucket.endpoint/key` (AWS; required for buckets in newer regions). |
| `access_key_id`, `secret_access_key_file` | The keys. `secret_access_key` directly in the file is possible, a separate file readable only by the service account is better. Without keys, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` from the environment are used. |
| `ca_file`, `tls_verify` | Own CA for self-signed certificates; `"tls_verify": false` only for tests. |
| `proxy` | `http://proxy:3128` if the server reaches the store only through a proxy. |
| `cache_mb`, `cache_dir` | Local image cache, default 2048 MB in `s3-cache/<name>` next to the configuration; `0` switches it off. |
| `timeout_s` | Per request, default 30. |

## 2. Create a project in a bucket

Under your name → **Projects** → **New project** (or **Import project**), choose **Store the files in: S3 bucket …** and give a folder in the bucket (the prefix, for example `line-5`). One bucket holds any number of projects; the prefixes of two projects must not overlap. Images already below the prefix are used as they are; an import needs an empty prefix.

## How it behaves

- Annotation files are always read from and written to the bucket, never cached. If a file was changed in the bucket meanwhile (by an S3 tool or another server), saving is refused with a conflict, as with a folder, and the outside version is kept in the history.
- Images are cached on the server’s disk and checked against the bucket at every request, so changed images are fetched again and unchanged ones cost one small request.
- Database, locks, sessions and backups stay on the server. Deleting a bucket project never deletes anything in the bucket.
- Failed requests (network, `503 SlowDown`) are repeated; errors are shown with the reason S3 gives (wrong key, clock skew, missing bucket, wrong region).

## AWS permissions {#aws-permissions}

The IAM user or role needs:

- on the bucket: `s3:ListBucket`,
- on `arn:aws:s3:::<bucket>/*`: `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`.

Without `s3:ListBucket`, AWS answers missing files with 403 instead of 404. Keep the server’s clock synchronised: AWS refuses requests that are more than 15 minutes off.

## MinIO or SeaweedFS?

Both work the same for LumiScan Annotation Web. The vendor of MinIO stopped publishing the community edition as ready-made programs in October 2025; existing installations keep working. For a new self-hosted store, SeaweedFS (Apache 2.0, actively maintained) is the safer choice.

# User Interface – LumiScan Annotation Web

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

After signing in, the browser shows the open project with its image list on the left, the image in the middle and the panels on the right.

![The LumiScan Annotation window with numbered markers: project selection, image list, image area, toolbar, revision notes, labels, selected box, user menu, notes for you and logo](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/workspace-callouts.jpg)

**Table 1. Elements of the user interface**

| No. | Element | Description |
| --- | --- | --- |
| 1 | Project and folder | **Project**: the projects you take part in (hidden with only one). **Folder**: the sub-folders of the project, usually one per day. Next to it: the open image and its position in the folder. |
| 2 | Image list | All images of the folder. A filled dot: the image has boxes; a hollow dot: not yet. A name in red: that person is editing the image right now. ✎ with a number: open revision notes. ✓: [marked as done](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html#marking-images-as-done); VAL / TEST: the image is in the validation or test set of the export. Above the list: **+ Add images** (project admins, see [Adding Images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/adding-images.html)), search by file name, **Show**, **Label**, **Set** and **Sort**, and **Rate with network**, see [Finding and Sorting Images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html). |
| 3 | Image area | The open image with its boxes. The green edge is the bottom of each box, the label is written next to it. The selected box is yellow with four corner handles. Mouse wheel: zoom; drag an empty area: move the image. |
| 4 | Toolbar | **Previous** / **Next** image, undo ↶ and redo ↷, **New box** with the switch for the drawing mode ([center-line](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-line-rectangle) or [edge rectangle](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#edge-rectangle)), zoom − / + with the current zoom, **1:1** (one screen pixel per image pixel), **Fit**, and the mouse position in image pixels. **Copy ▾** ([copying boxes](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/copying-boxes-and-templates.html)), **Mark done** (`Shift+D`: mark and go on), **Save and copy to next** and **Save** below. |
| 5 | Revision notes | Instructions left on this image, see [Revision Notes](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/revision-notes.html). **Add note** leaves one. |
| 6 | Labels | The labels of the project; the number is the key that applies it. Clicking a label applies it to the selected box and to new boxes. **Add** adds a label to the shared list. ▭: the label has a [box template](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/copying-boxes-and-templates.html#box-templates); **Place … template** (`T`) places it. |
| 7 | Selected box | Centre, width, height (in pixels) and angle (in degrees) of the selected box, editable, and the **Bottom edge** buttons that turn the 0° side; **Save as template** (project admins). **Suggest boxes** below, if a box suggestion service is configured. Further down: **View** (brightness, contrast, show labels, show center lines, magnifier) and **History**. |
| 8 | User menu | Your name and roles; **Change password** (local accounts), **Projects** and **Users and sign-in** (admins), **Language** (see [Languages and Translations](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/languages-and-translations.html)), **Log out**. |
| 9 | Notes for you | Number of open revision notes addressed to you in this project. Click to open the next one. |
| 10 | Logo | Stays at the bottom of the image list; only the list scrolls. |

Depending on your role and the project, the top bar also shows:

- **Annotate** / **Review**: switch between your own annotation and the comparison of the annotators (with several annotators per image, if you have both roles).
- **Statistics**: agreement between the annotators (reviewers).
- **Export**: the annotated images as a LumiScan Training project or in the COCO format, see [Exporting the Annotations](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html) (reviewers, project admins).
- **Version … available**: a newer version is out (single-PC installation, project admins).
- **Settings**: labels, region of interest, several annotators, box suggestions (project admins).
- **Shortcuts**: the list of keyboard shortcuts.
- The status: **Ready**, **Saved …**, messages and errors.

![User menu of a reviewer with name, user name, account type and role, and the entries Change password, My projects, Language: English and Log out](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/user-menu.png)

## Small screens

Below a width of about 1000 pixels the panels are stacked: the image first, then the panels, then the image list.

# Annotating Images – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html

## Oriented boxes

An oriented box is a rectangle that can be rotated. It has a centre, a width, a height and an angle. The **green edge is the bottom** of the box: it gives the box its direction. An angle of 0° means the top of the box points up; positive angles turn clockwise.

The direction matters for the training: the network learns where the bottom of an object is. Agree on a rule for every kind of object, for example "bottom where the part lies flat", and draw all boxes of that kind the same way. [Box orientation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-orientation.html) shows why this matters, with examples.

## Drawing a box

There are two ways to draw a box, with three clicks each. The switch next to **New box** shows which one is used:

![The button New box with the switch for the drawing mode next to it: center-line rectangle on the left, edge rectangle on the right, selected](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/draw-modes.png)

- `N` starts a [center-line rectangle](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-line-rectangle), `E` an [edge rectangle](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#edge-rectangle). A click on one side of the switch does the same.
- **New box** and a double-click on the image start a box in the mode used last. The browser remembers it for your account.

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/drawing-a-box.mp4)

### Center-line rectangle {#center-line-rectangle}

First the center line of the box, from the middle of its bottom to the middle of its top, then the width, which spreads evenly to both sides of that line. These are the clicks of the desktop tool:

1. Press `N` and click where the **bottom** of the object is, or double-click there.
2. Click where the **top** of the object is: this draws the center line and sets the height and the angle.
3. Move sideways and click: this sets the width, the same on both sides of the center line.

|   |   |   |
| --- | --- | --- |
| ![After the first click, the center line follows the mouse as a dashed line from the bottom to the top of the bracket](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/draw-1.png) | ![After the second click, the box follows the mouse sideways; the green line is the bottom edge](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/draw-2.png) | ![After the third click: the box is finished and selected](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/draw-3.png) |

### Edge rectangle {#edge-rectangle}

First the bottom edge of the box, then the height, on one side only:

1. Press `E` and click one end of the **bottom edge** of the object, or double-click there when the edge rectangle was used last.
2. Click the other end of the bottom edge: this sets the width and the angle.
3. Move towards the **top** of the object and click: this sets the height. The side you move to becomes the top, so the order of the first two clicks does not matter.

|   |   |   |
| --- | --- | --- |
| ![After the first click, the green bottom edge follows the mouse along the lower side of the bracket](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/edge-1.png) | ![After the second click, the box grows from the bottom edge towards the mouse](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/edge-2.png) | ![After the third click: the box is finished and selected](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/edge-3.png) |

### Which one to use

- The **edge rectangle** is easier when one side of the object is a clear, straight edge, for example a part lying flat, the edge of a box or a plate, or when only one side is sharp in the image. You click on what you see.
- The **center-line rectangle** is easier for long, roughly symmetric objects whose axis is obvious, such as pins, screws or cables. An error in the width is shared by both sides.

Both give the same kind of box; you can switch at any time.

The new box gets the label selected in the **Labels** list. `Esc` or a right-click cancels drawing.

## Editing a box

Click a box to select it. The selected box is yellow, with a handle on each corner.

![A selected box around a nut: yellow outline, four round corner handles, green bottom edge and the label nut](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/box-selected.png)

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/editing-a-box.mp4)

|   |   |
| --- | --- |
| Move | Drag the box, or arrow keys (1 pixel; with `Shift` 10 pixels), or `Ctrl` / `Shift` + `I` `J` `K` `L` |
| Resize | Drag an edge; the opposite edge stays. Keys: `Ctrl` / `Shift` + `V` `B` (height), `N` `M` (width) by 1 / 10 pixels |
| Rotate | Drag a corner, or `Ctrl` / `Shift` + `U` `O` by 1° / 10° |
| Exact values | Type them in the **Selected box** panel: centre, width, height in pixels, angle in degrees |
| Bottom edge | `R` / `Shift+R` or the **Bottom edge** buttons: the next side becomes the bottom edge (0°), see [Center lines and the bottom edge](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-lines-and-bottom-edge) |
| Label | Number keys 1 to 9, or click the label in the list |
| Delete | Right-click, or `Delete` |

The browser keeps `Ctrl+N` for itself: use `Shift+N` / `Shift+M` for the width.

## Center lines and the bottom edge {#center-lines-and-bottom-edge}

Dashed **center lines** run along and across every box through its centre. Where they cross is the centre of the box, for example the position where a gripper holds the part. So you can see at a glance whether the centre sits right: on a bracket, the line along the box should run through both holes. The lines are also shown in the magnifier and while you draw a box, and they never get in the way of a click. **Show center lines** under **View**, or `C`, switches them off and on; the browser remembers the choice for your account.

The **green bottom edge** is the 0° side of the box and gives it its direction. If it is on the wrong side, you do not need to draw the box again: `R` makes the next side clockwise the bottom edge, `Shift+R` the next side counter-clockwise. The two **Bottom edge** buttons next to **Angle** do the same. The outline stays exactly where it is; the angle changes by 90°, and width and height swap. Each turn is one undo step.

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/center-lines-and-bottom-edge.mp4)

## Precise work: the magnifier

The mouse pointer is a crosshair. Next to it, a magnifier shows the area under the pointer enlarged, with the pixel grid, the boxes and the position to 0.1 pixel. This lets you place edges with sub-pixel accuracy. `M` or **Magnifier at the pointer** switches it off and on.

![Magnifier: a circle with crosshair and pixel grid over the corner of a bracket, with the position x 245.5, y 314.9 and the magnification 15 times](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/magnifier.png)

Boxes are saved to 0.1 pixel and angles to 0.001 radians, exactly as in the desktop tool.

## Zoom and view

- Mouse wheel or `+` / `−`: zoom at the pointer. `F`: fit the image into the window. `Z` or **1:1**: one screen pixel per image pixel.
- Drag an empty area, or `Alt` + drag: move the image.
- **Brightness** and **Contrast** change only the display, not the image.
- **Show labels** switches the label texts off for a clear view.
- **Show center lines** (`C`) switches the center lines off and on, see [Center lines and the bottom edge](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-lines-and-bottom-edge).

## Labels

The labels are shared by everyone in the project. **Add** adds the name typed in the field; project admins can also remove labels and change the order in the [settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html). The first nine have the keys 1 to 9.

## Saving

- **Save** (`S` or `Ctrl+S`) writes the boxes to `<image>.csv` and adds an entry to `<image>.json`.
- **Save and copy to next** (`Alt+S`): saves, opens the next image and copies the boxes onto it, unsaved. Useful for series where the parts barely move: correct, save, next.
- Moving to another image with unsaved changes asks: **Save**, **Discard changes** or **Cancel**.

## Region of interest

If the project has a region of interest, it is outlined in violet on the image. Annotate only inside it; box suggestions outside it are left out. Project admins set it in the [settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html).

## Deleting an image

Project admins can delete an image: right-click it in the image list and confirm. This deletes the image with its annotation files, all versions, its history and notes, and cannot be undone.

# Box Orientation – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-orientation.html

An oriented box says not only *where* a part is but also *which way it points*. The green bottom edge sets the direction, and the angle of the box follows from it (see [Center lines and the bottom edge](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-lines-and-bottom-edge)). For most parts that angle is the part’s real rotation: LumiScan Training learns it from your boxes, and an application such as LumiScan VGR uses it to turn the part the right way before placing it. The angle is only as right as the green edge, so the rule of this page is short:

> [!IMPORTANT]
> For each label, decide which side of the part is its bottom, and put the green bottom edge on exactly that side in every box, whatever way the part lies in the image.

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/box-orientation.mp4)

## Parts with a unique orientation

The bracket in the images on this page looks different in every rotation: the chamfered corner, the large hole, the slot and the foot with its small hole line up only one way. Such a part has exactly one correct angle between −180° and 180°.

![The same bracket four times, turned by 0°, 90°, 180° and −90°: the chamfered corner, the large hole and the foot with the small hole are in a different place each time](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/orientation/orientation-rotations.jpg)

Most industrial parts are like this, even if the difference is small: one hole off-centre, a notch, a printed mark. Annotate them all with an orientation. Only parts that truly look the same in every rotation are an exception, see [Parts without an orientation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-orientation.html#parts-without-orientation).

## One rule per label

Choose the bottom side by a feature that is easy to see in every image, also when the part is tilted, half in shadow or partly covered. For the bracket, the rule is: **the bottom edge lies along the foot**. Then every box of the label has its green edge along the foot, and the angle of each box is the bracket’s rotation, across the whole range from −180° to 180°:

![Five brackets at different rotations, each with a box whose green bottom edge lies along the foot; their angles are 18°, 147°, −64°, −128° and 96°](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/orientation/orientation-consistent.jpg)

- Write the rule down with an example image, where every annotator sees it, before the first image is annotated. Changing it later means checking every box already drawn.
- Use a feature of the part, never the image: "bottom edge at the bottom of the image" gives an angle near 0° for every part, whatever its real rotation.
- If two labels look alike (a part and its mirror-image counterpart, for example), give each its own rule, based on the feature that tells them apart.

## What goes wrong when the edge is on another side

The outline of a box can be perfect while its direction is wrong. Two typical mistakes, marked as the review marks them:

![The same five brackets; two boxes are marked: 1 has its green edge on the side opposite the foot (−33° instead of 147°), 2 has it on a neighbouring side (−38° instead of −128°)](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/orientation/orientation-inconsistent.jpg)

|   |   |
| --- | --- |
| 1: opposite side | The outline fits, but the angle is off by 180°. This is the most common mistake: the box looks correct at first glance. |
| 2: neighbouring side | The outline fits too, but the angle is off by 90°, and width and height are swapped. |

In both cases only the green edge shows the mistake.

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/box-orientation-why.mp4)

### In training

The network learns the angle from the examples it is given. If the same bracket, lying the same way, is labelled 147° in one image and −33° in the next, the examples contradict each other. The network cannot learn which way the bracket points, only roughly where its long side is: its angle predictions become uncertain and often come out turned by 180°, and with 90° mistakes width and height get mixed up as well. A few such boxes already do noticeable harm, because each one teaches the opposite of all the correct boxes.

Wrong boxes in the validation or test share also falsify the results of the training: a correct prediction is counted as an error, and the network looks worse or better than it is.

### On the robot

A robot typically grips the part at the centre of the box and turns it by the angle so that it arrives in the fixture the right way round. The centre of a box with the wrong bottom edge is still right, so the part is picked up without any problem. The mistake only shows when it is put down:

![Top: box at 18° with the green edge along the foot; turned by −18°, the bracket fits its fixture (green outline, tick). Bottom: the same bracket with a box at −162°; turned by 162°, it arrives upside down and does not fit (red outline, cross)](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/orientation/orientation-consequence.jpg)

An angle off by 180° places the part the wrong way round: it does not fit, sits on its fixture askew, or is assembled the wrong way, and that is often noticed only later in the line.

## Keeping the orientation right

- **Look at the green edge** before you save. If it is on the wrong side, do not draw the box again: `R` makes the next side clockwise the bottom edge, `Shift+R` the next side counter-clockwise; `R` twice moves it to the opposite side. The outline stays where it is (see [Center lines and the bottom edge](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-lines-and-bottom-edge)).
- **Draw from the bottom**: with the [center-line rectangle](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-line-rectangle), click the bottom of the part first; with the [edge rectangle](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#edge-rectangle), click the two ends of the bottom edge first and then move the mouse towards the top. The direction then comes out right without turning.
- **Templates** remember the orientation of the box they were made from. Make the template with the bottom edge on the correct side, and turn a placed template box to match the part (see [Box templates](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/copying-boxes-and-templates.html#box-templates)). The same applies to boxes copied from the previous image.
- **Box suggestions** can have the bottom edge on any side, especially those of the detector. Check the green edge of every suggestion before you accept it (see [Box suggestions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestions.html)).
- **Two annotators per image**: the [review](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html) marks boxes whose angles differ by more than 135° as *bottom edge on the other side*. Such a difference never comes from imprecise drawing, so it is worth agreeing on the rule again with both annotators.

The angle is stored in the annotation file as `angleRad`, measured from the green bottom edge (see [Annotation files](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotation-files.html)).

## Parts without an orientation {#parts-without-orientation}

Some parts look exactly the same in every rotation, for example a round washer or a ball. For them, the angle of the box means nothing, and any angle is as good as another. Mark such labels as **Labels without orientation** when you [export the annotations](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html) (`nonRotables` in LumiScan Training): the training then ignores their angle.

Use this only for parts that really have no front and back. A part that only looks *almost* symmetric, such as a bracket whose only difference is a small hole, still has an orientation, and the robot needs it: annotate it with a rule, as described above.

## Try it with the sample images {#sample-images}

Two downloads with the same 24 images of brackets and washers (synthetic camera images, 1280 × 960 pixels, grayscale), free to use for testing and training:

|   |   |
| --- | --- |
| [Sample project](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_attachments/lumiscan-annotation-web-sample-brackets.lumiscan-project.tar) (14 MB) | The images **with** their reference annotations, as a project file to load on your server: **Projects** → **Import project** (see [Exporting and importing](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects.html#exporting-and-importing)). The project *Sample – oriented brackets* has the labels `bracket` and `washer`; `washer` is already a label without orientation for the [export](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html). |
| [Sample images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_attachments/lumiscan-annotation-web-sample-brackets.zip) (14 MB) | The images **without** annotations, to annotate yourself (`images/`), the reference annotations as CSV files of the desktop tool (`reference/`) and a short guide (`README.txt`). |

Annotate the images of the ZIP with the rule of this page, the green bottom edge along the foot, and compare your boxes with the sample project: the angles should agree within a few degrees, never by 180°.

# Copying Boxes and Templates – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/copying-boxes-and-templates.html

Images of a series often show the same parts in nearly the same place. Copying the boxes and moving them a little is much faster than drawing them again.

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/copying-boxes.mp4)

The **Copy ▾** menu below the image collects the ways to copy:

![Menu Copy with the entries Boxes from the previous image, Copy these boxes to the next images, Copy all boxes and Paste boxes](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/copy-menu.png)

## Boxes from the previous image

`V` (or **Copy ▾ → Boxes from the previous image**) puts the boxes of the image before this one in the list onto the open image. If the open image has boxes already, you choose: **Add them** or **Replace these**.

Then adjust what moved and save. The copy is one step of [undo](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/history-and-undo.html): `Ctrl+Z` takes it back.

## Copy to the next images

For a series where the parts do not move, **Copy ▾ → Copy these boxes to the next images…** saves the boxes of the open image directly onto the next images of the list:

|   |   |
| --- | --- |
| Number of next images | How many images after this one, in the order of the list (images the list does not show are skipped). |
| Also replace boxes those images have already | Off (default): images with boxes keep theirs. On: their boxes are replaced. |

Images someone else has open right now are skipped; the status says how many. Open the images afterwards with `D` and correct what differs.

> [!TIP]
> **Save and copy to next** (`Alt+S`) does the same for one image at a time: it saves, opens the next image and puts the boxes on it, unsaved, so you see each image before it is saved.

## Copy and paste

- `Ctrl+C` copies the selected box, or all boxes if none is selected.
- `Ctrl+V` pastes them on the open image, at the same position. It works on any image, also in another browser tab of the same browser.

`Ctrl+V` pastes when no box is selected. With a box selected, `Ctrl+V` keeps its meaning from the desktop tool (height − 1 pixel); copying a box deselects it, so `Ctrl+C`, `Ctrl+V` pastes. On a Mac, `Cmd+C` and `Cmd+V` always copy and paste.

## Box templates {#box-templates}

Parts of a fixed size get boxes of nearly the same size and orientation on every image. A **template** remembers that size and orientation per label.

1. Draw one box of the label carefully, with the [bottom edge](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-lines-and-bottom-edge) on the correct side of the part (see [Box orientation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-orientation.html)).
2. With the box selected, click **Save as template** in the **Selected box** panel (project admins). The label list marks labels with a template with ▭.
3. From then on, `T` places a box of the current label at the mouse pointer: the label of the selected box, or the one clicked last. **Place … template** in the **Labels** panel does the same in the middle of the image.
4. Move the box into place (drag, or the arrow keys) and turn it if needed (`Ctrl` / `Shift` + `U` / `O`).

Templates are part of the [project settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html#box-templates), where they can also be changed or removed.

# Finding and Sorting Images – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html

Above the image list are the controls that decide which images the list shows and in which order.

![Image list with the search field, Show, Label, Set and Sort, pages of a TIFF file, images marked done with a tick and VAL / TEST tags for the validation and test set](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/image-filters.png)

## Search

Type part of a file name, for example `14-13` or `part_03`. The list shows only the matching images. `Enter` opens the first match, `Esc` clears the search.

## Show

|   |   |
| --- | --- |
| All images | Every image of the folder. |
| Without boxes | Images that still need annotating. With [several annotators per image](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html): **Not annotated by me** (annotating) or **Need a review** (reviewing). |
| With boxes | Images with an annotation. With several annotators: **Annotated by me** or **Finished**. |
| Marked done | Images [marked as done](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html#marking-images-as-done). |
| Not marked done | Images not marked yet. |
| With notes for me | Images with an open [revision note](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/revision-notes.html) addressed to you. |
| Network unsure | Images the project’s network is unsure about (50 % or more), after [rating](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html#rate-with-network). |

The image you have open always stays in the list. **Previous** and **Next** (`A` / `D`) skip the images the list does not show.

## Label

Only images with at least one box of that label, or **No boxes**. Useful to check all boxes of a rare class, or to find images where a class is missing. The labels come from the saved annotations, so unsaved changes do not count yet.

> [!NOTE]
> With several annotators per image, annotators work without seeing the reference annotation, so the label filter is only offered to reviewers there.

## Set

The set the [export](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html) puts the image in: **Training**, **Validation** or **Test**, with the number of images. The list tags validation images with VAL and test images with TEST. The set follows from the folder and file name and the project’s export settings (**Validation %**, **Test %**, **Keep each folder together**), so it is known before anything is exported, and it never changes when more images are annotated. The filter is shown once the export has a validation or test share.

Useful to check that the validation images cover every kind of part, or to annotate the test images with particular care.

## Marking images as done {#marking-images-as-done}

**Mark done** next to **Save** marks the open image as finished. That matters for images without boxes: an image with no objects on it looks the same as one nobody has looked at yet, until it is marked. `Shift+D` saves the boxes, marks the image and opens the next one, the quickest way through a series.

The list shows ✓ next to marked images, the line above it how many are done, and **Show → Marked done / Not marked done** filters them. Hovering over the button shows who marked the image and when; clicking it again removes the mark. Annotators and reviewers may mark images. The marks are kept on the server with the project (also in its export) and do not change the annotation files.

## Sort

|   |   |
| --- | --- |
| File name | The order of the folder. |
| Largest differences first | Reviewing with several annotators: images to check first, the most differences on top. |
| Network least sure first | After rating: the images the network is least sure about on top, with the percentage next to each name. |

## Rate with network (active learning) {#rate-with-network}

Not every image is equally useful for training. Images the network already handles well add little; the ones it is unsure about teach it the most. **Rate with network** lets the project’s trained network look at every image of the folder and say how sure it is.

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/finding-and-rating-images.mp4)

1. Choose the folder.
2. Click **Rate with network**. By default only images without boxes are rated; tick **Also images with boxes** to rate all, and **Rate again** after a new network was trained.
3. The rating runs on the server; you can keep working. The progress is shown next to the button.
4. The list switches to **Network least sure first**. Annotate from the top.

The button is shown when the server has [box suggestions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestions.html). The network is the one chosen in the [project settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html#box-suggestions).

How the percentage is computed: the network looks for objects down to a very low confidence. A detection exactly at the project’s minimum confidence (default 30 %) counts as 100 % unsure: the network cannot decide whether something is there. A detection near 0 % or 100 % counts as sure. The image gets the value of its most uncertain detection. An image without any detection gets 0 %.

> [!TIP]
> Rate, annotate the 50 to 100 least sure images, train, rate again with the new network. This finds the difficult cases much faster than annotating in file order.

# Adding Images – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/adding-images.html

Project admins add image files from their computer to a project, without access to the server’s folders. **+ Add images** is above the image list.

![Dialog Add images: the target folder (here a new folder named after today’s date), the drop area with Choose files and Choose a folder, and the list of chosen files with their sizes](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/add-images.png)

1. Click **+ Add images**.
2. Choose the folder: an existing folder of the project, or **New folder…** with a name (default: today’s date, for example `2026-11-08`). Choosing a folder on your computer suggests its name.
3. Choose the images: **Choose files…**, **Choose a folder…** (all images in it and its sub-folders), or drag files or a folder onto the dialog.
4. Click **Add images**. A bar shows the progress. The list then shows the folder with the new images.

Accepted are PNG, JPEG (`.jpg`, `.jpeg`), BMP and TIFF (`.tif`, `.tiff`, also multi-page), see [Image Formats](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/image-formats.html). Other files of a chosen folder are ignored.

## What is skipped

- An image with a name that is already in the folder.
- An image that would share its annotation file with another one: `part_01.png` and `part_01.jpg` both use `part_01.csv`.
- A file whose content does not match its extension (for example a JPEG named `.png`).

Skipped images are counted in the message at the end; files that could not be added stay in the dialog with the reason.

## Good to know

- The files are copied into the project’s folder on the server, or into its S3 bucket ([Projects in S3 Buckets](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects-in-s3-buckets.html)).
- A project whose images are directly in its folder (no sub-folders) takes new images there. A sub-folder would hide those images, as in the desktop tool.
- Large files are sent in pieces of 8 MB. The server accepts files up to 2 GB; `upload_max_mb` in the [configuration](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html) sets another limit.
- Images can also be put into the project folder directly (file explorer, network share, S3 tool): the server finds them within a minute.

# Box Suggestions – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestions.html

**Suggest boxes** (`P`) asks the box suggestion service for boxes on the open image. The button is only shown when the server has a service (see [Box Suggestion Service](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestion-service.html)), or runs the networks itself, as the [single-PC installation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/single-pc-installation.html#box-suggestions-without-a-server) does.

The suggestions come from:

- **your trained LumiScan network** for the project (chosen in the [project settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html#box-suggestions)), or
- for parts without a network yet, an **open-vocabulary detector** that looks for the objects named by the labels, for example "bracket" or "hexagon nut".

![Suggested boxes, dashed, with label and confidence, for example bracket 97 %, nut 93 %, washer 74 %](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/suggestions.jpg)

## Working with suggestions

Suggestions are drawn **dashed** with their label and confidence. They are not part of the annotation until you accept them.

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/box-suggestions.mp4)

|   |   |
| --- | --- |
| Accept one | Correct it (move, resize, rotate, change the label), or select it and press `Enter` |
| Delete one | Right-click it, or select it and press `Delete` |
| Accept all remaining | **Accept all** |
| Delete all remaining | **Discard** |
| Save with open suggestions | You are asked whether to accept them or leave them out |

Suggestions are never written to the annotation file by themselves.

What is not suggested:

- objects that already have a box on the image (overlap with an existing box),
- objects outside the region of interest,
- suggestions below the project’s minimum confidence, and beyond its maximum number of boxes.

## Good suggestions

- **With a network**: the more annotated images it was trained on, the better. Retrain after every few hundred corrected images.
- **With the detector**: label names say what to look for. Use visible properties ("hexagon nut", "weld seam", "black rubber seal"), not internal part numbers. Labels with a meaningless name get a description in the project settings, for example `part_a: hexagon nut`.
- Tiny or low-contrast objects: lower the minimum confidence.
- Always check every accepted box. A wrong box in the training data teaches the network the mistake.
- Let the network say where it is unsure: [Rate with network](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html#rate-with-network) sorts the images so the most useful ones are annotated first.

# Revision Notes – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/revision-notes.html

A revision note is an instruction on one image for someone else, typically from a reviewer to an annotator: what to change and why. For example: "This bracket’s box is too wide on the left: tighten it to the edge, please."

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/revision-notes.mp4)

## Leaving a note

1. Open the image. To pin the note to a box, select the box first.
2. Click **Add note** in the **Revision notes** panel.
3. Write the instruction.
4. Under **For**, choose the person, or **Whoever works on this image**.
5. Tick **Pin the note to the selected box** if you selected one. The note is then shown as a red **!** on the image.
6. Click **Add note**.

![Dialog Revision note on part_002.png with the instruction text, the addressee Whoever works on this image and the option to pin the note to the selected box](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/note-dialog.png)

## Receiving notes

- The top bar shows **✎ n notes for you**. Click it to open the next image with a note for you.
- The image list marks images with open notes (✎ and the number).
- **Only images with notes for me** filters the list.

![Button 2 notes for you in the top bar](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/notes-chip.png)

On the image, the note is shown in the **Revision notes** panel, with the author, the addressee and the time:

![A revision note from Clara Lenz to Anna Weber, marked for you, with the buttons Show, Done and Reply](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/note-panel.png)

|   |   |
| --- | --- |
| **Show** | zooms to the spot the note is pinned to |
| **Reply** | answers the note |
| **Done** | marks the note as done, optionally with a reply. Done notes stay visible, with who closed them and when. |

The author and project admins can delete a note.

# History and Undo – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/history-and-undo.html

## Undo and redo

While you edit an image, every box change is a step: `Ctrl+Z` undoes it, `Ctrl+Shift+Z` or `Ctrl+Y` redoes it, as do the buttons ↶ and ↷ in the toolbar. Holding an arrow key is one step.

## History

The **History** panel (on the right, at the bottom, click to open) lists every saved state of the open image, also from earlier days, with the time, the user and what happened: saved, decided in review, annotators agreed, restored, or changed outside the web app.

![History panel open: an older version of part_003.png is shown in pink over the image, with numbered markers where it differs from the boxes in the editor](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/history.jpg)

- Click a version to see it in **pink** over the image. Numbered markers show where it differs from the boxes in the editor.
- **Older** and **Newer** (or the keys `,` and `.`) step through the versions; **Close** hides it again.
- **Restore** puts the version into the editor as unsaved changes. Saving adds a new version; the history is never rewritten.

![History panel: the selected version from anna, compared with the editor 3 only in the version and 6 different, buttons Older, Newer, Close and Restore; below the list of versions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/history-panel.png)

Changes made with the desktop tool on the same folder are kept as versions too, with the user from `<image>.json`. The history keeps the exact text of each CSV file, so restoring writes an earlier state back byte for byte.

With several annotators per image, annotators see the history of their own version only. Reviewers choose under **Show** whether they see the reference or one annotator’s history.

# Working at the Same Time – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/working-at-the-same-time.html

Any number of people can work in the same project at the same time. Two rules keep their work apart.

## Edit locks

Opening an image takes an **edit lock** for you. While you have the image open, others can look at it but not change it: their view is read-only, with a banner naming you, and the image list shows your name in red next to the image.

![Read-only image: a banner says that anna is working on this image and it can be looked at but not changed; the Save buttons are disabled and the image list shows anna next to part_005.png](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/read-only.jpg)

- The lock lasts 60 seconds and is renewed by your browser as long as the image is open. If the browser is closed or the network is gone, the lock ends by itself after that time.
- Opening the same image in a second window of your own makes the other window read-only.
- A read-only image becomes editable by itself as soon as it is free, for example when the other person moves on to the next image. The status line then says **… is free again: you can edit it now**.
- With several annotators per image, every annotator has their own lock on their own version: they can annotate the same image at the same time.

## Conflicts

If the annotation file of an image was changed after you opened it, for example by the desktop tool on the same network folder or by another server on an S3 bucket, saving asks:

- **Load their version**: discard your changes and show the other version,
- **Overwrite with mine**: save your boxes anyway (the other version stays in the history),
- **Cancel**: keep editing.

The server scans the project folders regularly (default every 60 seconds) and takes over changes made outside the web app into the history.

# Several Annotators per Image – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html

With **Annotators per image** set to 2 or more in the [project settings](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html), every image is annotated by that many people independently. The server compares their boxes. A step-by-step guide is in [Check Annotations with Two Annotators](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/check-annotations-with-two-annotators.html).

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/two-annotators-and-review.mp4)

## Modes

Annotators see the mode **Annotate**, reviewers the mode **Review** and the **Statistics**. People with both roles switch at the top.

## Annotate (blind)

- Everyone draws their own version without seeing the others' boxes.
- The versions are stored apart from the reference, in `<folder>/.annotations/<image>/<user>.tsv` (same format as the CSV; training ignores them).
- Several people can annotate the same image at the same time.
- The image list shows **annotated / required** (`1/2`), and whether you have done it. Annotators see how many have annotated, not who.
- **Only images I have not annotated yet** filters the list.

## Automatic consensus

When the last required annotator saves, the server compares all versions. They **agree** when

- every object was drawn by everyone (nobody missed a box),
- matching boxes overlap at least the set value (**Agree: overlap ≥ %**, default 85 %, measured as rotated intersection over union),
- their angles differ less than the set limit (default 5°), with the bottom edge on the same side,
- they have the same label.

Then the server writes the **mean boxes** as the reference annotation `<image>.csv`, the file training reads, with `auto-consensus` as the user in the `.json` history. Otherwise the image goes to review.

Boxes of different annotators are matched with an optimal assignment (Hungarian method) on the rotated overlap.

## Review

![Review mode with the boxes of two annotators in their colours, red numbered markers at the differences and the differences panel on the right](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/review.jpg)

- The image list shows the state of each image: open, **to check**, **accepted** (agreed automatically), **done** (reviewed). It is sorted by the largest differences first; **Sort** changes that.
- Every annotator has a colour; the legend switches individual annotators on and off.
- Red numbered markers show the differences: box missing for someone, overlap too small, angle, bottom edge on the other side, different label.
- For each difference: **Show** zooms to it; the buttons take one person’s box, the **Average** or **None** into the reference.
- The boxes in the editor can also be changed freely before saving.
- **Save** writes the reference annotation. `.annotations/<image>/consensus.json` records who decided. A reviewed reference is never overwritten automatically, also if an annotator saves again.

## Statistics

**Statistics** shows the agreement for one folder or the whole project:

![Agreement between annotators: summary figures, per annotator, pairs of annotators, differences by kind, largest differences](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/statistics.png)

|   |   |
| --- | --- |
| Summary | Images with enough annotators, share of complete images that fully agree, mean overlap, share of objects that agree; images open, to check, agreed automatically, reviewed |
| Per annotator | Overlap with the consensus; systematic deviation of width, height and angle from the mean box; boxes only they drew, boxes they missed; other labels |
| Pairs of annotators | Agreement (F1) and mean overlap per pair |
| Differences by kind | How often each kind of difference occurs |
| Largest differences | The images with the most and largest differences; click to review |

# Exporting the Annotations – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html

**Export** in the top bar downloads the annotated images, in one of three formats (**Format**):

- **LumiScan Training project (ZIP)**: a complete LumiScan Training project. Unpack it into the Training’s projects folder, open it there and start training.
- **COCO: images and annotations (ZIP)** and **COCO: annotations only (JSON)**: for other tools, see [COCO](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html#coco).

Reviewers and project admins see the button. All three formats use the same images, classes and split.

![Dialog Export the annotations: format, project name, network type, validation and test share, keep folders together, only this folder, labels without orientation and the counts per set](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/training-export.png)

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/export-for-training.mp4)

## Settings

|   |   |
| --- | --- |
| Format | LumiScan Training project, COCO with images, or COCO annotations only (with the choice of all images or one set). |
| Project name in LumiScan Training | Name of the project folder and of its configuration file (for COCO: **Name of the export**). Default: the project name. |
| Network type | The network LumiScan Training trains, for example `ORTMXS` (oriented, extra small, the Training’s default) or `ORTMS`. Can be changed in LumiScan Training later. Not used for COCO. |
| Validation % | Share of the images the training does not learn from but measures its progress on. Default 20. |
| Test % | Share kept for the final test. Default 0: LumiScan Training then tests on the validation images. |
| Keep each folder together | All images of a folder go to the same set. Use it when the images of a folder are a series of nearly the same scene: otherwise almost identical images end up in training and validation, and the validation figures look better than the network is. |
| Only the folder … | Export only the open folder instead of all. |
| Labels without orientation | Labels whose objects have no front or back (for example round washers): `nonRotables` in LumiScan Training. |

Below the settings the dialog shows how many images and boxes go to each set, the classes, and how many images are left out because they have no annotation. Project admins' choices are kept as the project’s defaults for the next export.

## What is exported

```none
Line 5 – brackets.lumiscan-training.zip
  Line 5 – brackets/
    Line 5 – brackets.train.json        project configuration for LumiScan Training
    training/2026-10-28/part_001.png    image
    training/2026-10-28/part_001.csv    its annotation, unchanged
    ...
    validation/2026-10-29/...
    test/...                            only with a test share
    lumiscan-annotation-export.json     who exported when, the split, the counts
```

- Only images with an annotation are exported. With several annotators per image: the reference annotation (agreed or decided by a reviewer).
- The annotation files are the same files the server stores (see [Annotation Files](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotation-files.html)).
- JPEG and BMP images and the pages of TIFF files are written as PNG, because LumiScan Training reads `<name>.png` next to each `<name>.csv` (see [Image Formats](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/image-formats.html)).
- The classes are the project’s labels in their order. Boxes labelled `UNKNOWN`, and boxes with a label that is not a class, are not learned; the info file counts them.
- The configuration names the folders relative to the project (`training`, `validation`, `test`). LumiScan Training points them at the project folder when it opens the project.

## The split stays the same

Which set an image belongs to is decided by its folder and file name, not by chance. Exporting the same project again, after more images were annotated, keeps every image in its set: an image the network learned from never becomes a validation image later, so the validation figures stay honest. Raising the validation share only moves images from training to validation. The image list shows each image’s set under [Set](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html#_set).

## COCO {#coco}

**COCO: images and annotations (ZIP)** and **COCO: annotations only (JSON)** export the same images, classes and sets in the COCO object detection format (cocodataset.org), which CVAT, Label Studio, FiftyOne, Ultralytics, Detectron2 and many other tools read.

```none
Line 5 – brackets.coco.zip
  Line 5 – brackets/
    images/2026-10-28/part_001.png
    ...
    annotations/instances_all.json      all images
    annotations/instances_train.json    with more than one set: one file per set
    annotations/instances_val.json
    annotations/instances_test.json
```

The JSON download is one such file, for all images or for one set (**Images in the JSON file**); its `file_name` entries name the images as in the ZIP.

| Field | Content |
| --- | --- |
| `images[]` | `id`, `file_name` (`<folder>/<image>`), `width`, `height`, `split` (`train`, `val`, `test`) |
| `annotations[].bbox` | The axis-aligned rectangle around the oriented box `[x, y, width, height]`, as standard COCO tools expect |
| `annotations[].segmentation` | The four corners of the oriented box (top left, top right, bottom right, bottom left of the box), so tools draw it rotated |
| `annotations[].area` | Width × height of the oriented box |
| `annotations[].obb` | The box as in the CSV: `cx`, `cy`, `width`, `height`, `angle` (radians, clockwise, 0: top of the box up) |
| `annotations[].attributes.metadata` | The box’s metadata, if it has any |
| `categories[]` | The classes in label order, `rotatable: false` for labels without orientation |

PNG and JPEG files are exported as they are; BMP files and TIFF pages are written as PNG. Boxes labelled `UNKNOWN` are left out.

# Keyboard Shortcuts – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/keyboard-shortcuts.html

The same list is shown in the browser under **Shortcuts**.

[Video](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/videos/keyboard-workflow.mp4)

| Keys | Action |
| --- | --- |
| `A` / `D` | Previous / next image |
| `Shift+D` | [Mark the image as done](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html#marking-images-as-done) (its boxes are saved first) and open the next image |
| `S`, `Ctrl+S` | Save |
| `Alt+S` | Save, open the next image and copy these boxes onto it |
| `V` | [Take the boxes of the previous image](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/copying-boxes-and-templates.html) in the list (adjust, then save) |
| `Ctrl+C` / `Ctrl+V` | Copy the selected box (or all boxes) / paste them, also on another image; paste with no box selected (`Cmd+V` on a Mac) |
| `T` | Place a box of the current label’s [template](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/copying-boxes-and-templates.html#box-templates) at the mouse pointer |
| `Ctrl+Z`, `Ctrl+Shift+Z` / `Ctrl+Y` | Undo, redo (every box change is a step) |
| `,` / `.` | History open: show the next older / newer saved version |
| `N` | New box as a [center-line rectangle](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-line-rectangle): click bottom, click top, then click for the width |
| `E` | New box as an [edge rectangle](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#edge-rectangle): click both ends of the bottom edge, then click for the height |
| Double-click | New box in the mode used last |
| Right-click, `Delete` | Delete the selected box (or cancel drawing) |
| `R` / `Shift+R` | [Bottom edge](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-lines-and-bottom-edge) (0°) of the selected box one side on, clockwise / counter-clockwise; the outline stays |
| `P` | Suggest boxes (if the server has a box suggestion service) |
| `Enter` | Accept the selected suggested box |
| `1` – `9` | Apply label to the selected box |
| Arrow keys | Move the selected box by 1 pixel (`Shift`: 10 pixels) |
| `Ctrl` / `Shift` + `I` `J` `K` `L` | Move 1 / 10 pixels up, left, down, right |
| `Ctrl` / `Shift` + `U` `O` | Rotate 1° / 10° counter-clockwise, clockwise |
| `Ctrl` / `Shift` + `V` `B` | Height − / + 1 / 10 pixels |
| `Ctrl` / `Shift` + `N` `M` | Width − / + 1 / 10 pixels (the browser keeps `Ctrl+N` for itself: use `Shift+N`) |
| `F`, `+` / `−`, `Z` | Fit image, zoom in / out (the mouse wheel zooms too), 1:1 |
| `M` | Magnifier with crosshair at the mouse pointer on / off |
| `C` | [Center lines](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotating-images.html#center-lines-and-bottom-edge) (along and across each box through its centre) on / off |
| Drag empty area, `Alt` + drag | Move the image |
| `Esc` | Cancel drawing, deselect |

![Dialog Keyboard shortcuts with the list of keys and actions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/shortcuts.png)

# Projects – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects.html

A project is an independent annotation job: a data folder (or a prefix in an S3 bucket), its settings, its members with their roles, its history and its revision notes. Users only see the projects they take part in.

Server admins manage all projects under their name → **Projects**. Project admins manage the members and settings of their own project.

![Dialog Projects: buttons New project and Import project, a table of projects with name, description, folder, number of images, access, creation date and the buttons Members and access, Export and Delete](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/projects.png)

## Creating a project

**New project**, then:

|   |   |
| --- | --- |
| Name, description | Shown in the project list and the top bar |
| Existing folder on the server | A folder with images, for example `D:\Images\Line2` or a share mounted on the server. The annotation files are written next to the images. Empty: the server creates an empty folder under `projects_root`. |
| Store the files in | Only with S3 buckets configured: a folder on the server, or **S3 bucket …** with a prefix, see [Projects in S3 Buckets](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects-in-s3-buckets.html) |
| Open to all signed-in users | Everyone works in the project with their server-wide roles, without being a member |

The folders admins may use can be limited with `project_folders` in the [configuration](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html). Two projects must not share a folder.

### Layout of a project folder

The images are directly in the folder, or in one level of sub-folders, typically one per day:

```none
Line2\
    2026-10-28\
        part_001.png         the image
        part_001.csv         its boxes
        part_001.json        its save history
        .annotations\        versions of the annotators (several annotators per image)
    2026-10-29\ ...
    .lumiscan-annotation\
        settings.json        the project's shared settings (labels, ROI, ...)
```

This is the layout of the desktop tool; folders it used are taken over as they are. See [Annotation Files](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotation-files.html).

## Members and access {#members-and-access}

**Members & access** next to a project:

![Members and access: name, description, open to all, and the member table with user or group, name and the roles annotator, reviewer, project admin](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/members.png)

- **User**: a server account by its user name. **Group**: a group of the directory or single sign-on, matched by name, full DN or the last part of a Keycloak group path.
- Roles per member: **Annotator**, **Reviewer**, **Project admin**. A person in several entries gets all their roles.
- Directory and single sign-on users added by group get access at their first sign-in.
- You cannot remove your own project admin role, so a project always keeps an admin.

## Exporting and importing {#exporting-and-importing}

**Export** downloads the project as one file `<name>.lumiscan-project.tar`, a plain tar archive (readable with Windows' `tar.exe`, 7-Zip or any Linux system):

|   |   |
| --- | --- |
| `project.json` | name, description, members (no passwords), export time and user |
| `settings.json` | the project’s settings |
| `data/…` | images, CSV and JSON files byte for byte, and the annotators' versions |
| `notes.jsonl` | revision notes |
| `history.jsonl` | every saved version (optional) |

**Import project** uploads such a file in 8 MB pieces, with a progress bar, so projects of several gigabytes work. It creates an independent project in a new folder under `projects_root` (or in a bucket). Members are kept and apply when those users sign in on this server. Paths in the archive are checked: nothing can be written outside the new project folder.

![Dialog Import a project: project file, optional name, buttons Cancel and Import](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/import-project.png)

Typical use: a customer exports a project and sends it to HD Vision Systems for expert annotation; the annotated project comes back the same way.

## Deleting a project

**Delete** removes the project from the server: its settings, members, history and notes. The image and annotation files are deleted only for folders the server created itself (on request); existing folders and buckets are never deleted.

## The project `default`

The image folder given as `data_root` in the configuration becomes the project `default`, open to all users. This is how installations from before projects existed keep working unchanged.

# Users and Roles – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/users-and-roles.html

## Roles

| Role | May |
| --- | --- |
| Annotator | Draw and save boxes; add labels. With several annotators per image: only their own version, blind. |
| Reviewer | Compare the annotators, decide the reference annotation, see the statistics. |
| Project admin | Manage the members and the settings of the project; delete images. |
| Admin | Everything in every project, plus users, group mappings, projects (create, export, import, delete) and backups. |

The server enforces the roles; the browser only shows what a role may do.

**Server-wide roles** (Annotator, Reviewer, Admin) are set per user or per group, see below. They apply in projects that are **open to all signed-in users**. Other projects give roles to their members, see [Members and access](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects.html#members-and-access).

## Managing users

Admins: your name → **Users and sign-in**.

![Tab Users: search field, button Add local user, table of users with account type, the roles annotator, reviewer, admin, active, last sign-in, and the buttons Reset password and Delete](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/users.png)

- **Add local user**: user name, full name, e-mail, roles and a first password. Without a password, one is generated and shown once. The user must change it at the first sign-in.
- Tick the roles directly in the table. **Active** off: the user can no longer sign in, and their sessions end at once.
- **Reset password**: a new password for a local account (shown once); the user changes it at the next sign-in.
- Directory and single sign-on users appear in the list after their first sign-in. A **G** marks roles given through a group membership.

## Groups and roles {#groups}

**Groups → roles** gives a role to every member of a directory or single sign-on group:

![Tab Groups and roles: mappings of the groups Annotation Team to the role annotator and Quality Assurance to the role reviewer](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/groups.png)

A group matches by its name (`Annotation Reviewers`), its full DN, the last part of a Keycloak group path (`/hdvs/annotation-reviewers`) or a client role. Group roles are refreshed at every sign-in.

## Sign-in methods

The tab **Sign-in methods** shows what is configured, the redirect address to register at the single sign-on provider, and a form to **test a directory sign-in**: it shows the groups found and the roles they give, without signing in. The methods themselves are configured in the server’s configuration file, see [Sign-in Methods](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/sign-in-methods.html).

## Your own password

Local users change their password under their name → **Change password**. Passwords have at least 10 characters. Directory and single sign-on users change their password in the company directory.

![Dialog Change password: current password, new password twice](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/change-password.png)

# Project Settings – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/project-settings.html

Project admins open the settings of the current project with **Settings** in the top bar. They apply to everyone in the project and are stored in the project folder (`.lumiscan-annotation/settings.json`, the keys `labels` and `roiSettings` as in the desktop tool).

![Settings dialog: labels, region of interest, several annotators per image, box suggestions with network, descriptions, minimum confidence and maximum number of boxes](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/settings.png)

## Labels

One label per line. The order gives the keys 1 to 9 and the order in the list. Renaming a label here does not change boxes already saved with the old name.

## Region of interest

**Whole image**, or a rectangle in image pixels (**X**, **Y**, **Width**, **Height**). The rectangle is outlined on every image; box suggestions outside it are left out.

## Several annotators per image

|   |   |
| --- | --- |
| Annotators per image | `1`: each image is annotated once. `2` or more: every annotator draws their own boxes without seeing the others', see [Several Annotators per Image](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html). |
| Agree: overlap ≥ % | Minimum overlap of matching boxes (rotated intersection over union), default 85. |
| Agree: angle within ° | Maximum angle difference, default 5. |
| Write the reference automatically when all annotators agree | On (default): the server writes the mean boxes as the reference. Off: every image goes to review. |

## Box suggestions {#box-suggestions}

Shown when the server has a box suggestion service.

|   |   |
| --- | --- |
| Network | The trained network of the project, from the networks on the service (the list shows their classes). Empty with only one network: that one. |
| Descriptions | For the open-vocabulary detector: describe in English what a label looks like if its name says little, one per line, for example `part_a: hexagon nut`. |
| Suggest from confidence % | Suggestions below are left out, default 30. |
| At most boxes per image | Default 50. |

## Box templates {#box-templates}

One line per label: `label: width x height, angle°`, for example `nut: 42 x 18, 0°`. `T` places a box of that size and orientation, see [Box Templates](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/copying-boxes-and-templates.html#box-templates). Easier than typing: select a box of the right size and click **Save as template**. Delete a line to remove a template.

## Export for LumiScan Training

The network type, validation and test share and the labels without orientation chosen at the last [export](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html) are kept with the project as the defaults for the next one.

## Box line thickness

The thickness of the box lines on the image, for everyone in the project. Changes only the display.

# Backup and Restore – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/backup-and-restore.html

## What a backup contains

A backup is one tar file with everything the server keeps apart from the images:

- the database: accounts, group mappings, projects and members, the history of all annotations, revision notes,
- the files of the configuration folder: configuration, secret files, certificates,
- the folder `tls` next to the configuration: the HTTPS certificate, so the clients keep trusting it after a restore,
- the settings of every project.

The images and annotation files are backed up with the project folders themselves (your usual file backup), or per project with the [export](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects.html#exporting-and-importing).

> [!WARNING]
> Backups contain password hashes and secrets. Store them as carefully as the server itself.

## Automatic backups

Every `backup.every_hours` hours (default 24) into `backup.dir` (default `backups` next to the configuration). The newest `backup.keep` (default 14) are kept.

## In the browser

Admins: your name → **Users and sign-in** → **Backups**. The list shows the backups on the server; **Make a backup now** makes one, **Download** downloads it.

![Tab Backups: what a backup contains, the automatic schedule and folder, the list of backups with Download, and the button Make a backup now](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/backups.png)

## On the command line

Also while the server runs:

```none
lumiscan-annotation-server --config <configuration> --backup D:\Backups\annotation.tar
```

## Restoring

1. Stop the server.
2. Restore:
   ```none
   lumiscan-annotation-server --config <configuration> --restore <backup.tar>
   ```
3. Start the server.

The current database and every file the restore replaces are kept next to them as `…before-restore-<time>`. Sessions are not restored: everyone signs in again. The restore refuses to run while the server answers on its port (`--force` overrides this).

# Languages and Translations – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/languages-and-translations.html

LumiScan Annotation Web is available in these languages:

| Language | Code |
| --- | --- |
| English | `en` |
| Deutsch (German) | `de` |
| Español (Spanish) | `es` |
| Français (French) | `fr` |
| 中文（简体） (Chinese, simplified) | `zh-CN` |

The texts are written in English; the other languages are translations of them.

## Choosing the language

At the first visit the app uses the language of the browser. If there is none for it, the app uses English.

To choose another language:

- on the login page: the language list at the bottom of the login card,
- when signed in: **your name → Language**.

![The Language dialog: Same as the browser, English, Chinese (Simplified), Français, Deutsch and Español as buttons; the chosen language is framed in yellow](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/_images/screens/language-dialog.png)

The choice is saved with your account. It applies in every browser and on every PC you sign in with, also in the single-PC installation. **Same as the browser** removes the saved choice: the app follows the browser’s language again.

Dates and times are shown the way the chosen language writes them. Labels, folder and file names, and notes are shown as they were written.

## Changing texts and adding languages

Administrators can change any text of the interface and add languages, without a new version and without a restart. The texts are in **translation tables**, one JSON file per language:

```json
{
  "_meta": { "name": "Deutsch", "english": "German" },
  "messages": {
    "Save": "Speichern",
    "{n} images added": "{n} Bilder hinzugefügt"
  }
}
```

The key of each entry is the English text; the value is the text shown. `_meta.name` is the name in the language list, `_meta.english` the English name below it.

The server reads two places and merges them:

| Folder | Content |
| --- | --- |
| `www/i18n` in the installation folder | The tables that come with the app. Replaced by every update: do not change them. |
| `translations` next to the configuration | Your own tables. An update never touches them. Another folder can be set with `translations_dir` (see [Configuration](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html)). |

An entry in your own table wins over the one that came with the app. An empty entry is ignored.

### Changing a text

1. Copy the table of the language from `www/i18n`, for example `de.json`, into the `translations` folder (create the folder if needed).
2. Keep only the entries you want to change, or keep them all. Change the texts on the right side.
3. Save the file as UTF-8.
4. Reload the page in the browser. The new texts apply at once.

Example: your company calls a box a "frame" and an annotator a "labeler":

```json
{
  "messages": {
    "New box": "New frame",
    "Annotators per image": "Labelers per image"
  }
}
```

Saved as `translations/en.json`, this changes the English interface.

### Adding a language

Copy `en.json` from `www/i18n` to `translations/<code>.json`, for example `it.json` for Italian or `pt-BR.json` for Brazilian Portuguese, set `_meta`, and translate the texts. The language appears in the language list at the next reload. Untranslated entries show the English text.

### Rules for the texts

- Keep placeholders in curly braces exactly as they are: `{name}`, `{n}`, `{total}`. They are replaced by names and numbers. Their order in the sentence may change.
- Texts ending in a space, or starting with one, are put together with other texts: keep the space.
- A table that is not valid JSON is ignored, and the server log names it. Check the file with a JSON validator if a change does not show.
- After an update, new texts of the new version appear in English until your own table has them too. The tables in `www/i18n` of the new version show which texts exist.

> [!NOTE]
> The Spanish, French and Chinese tables were translated with care but not yet reviewed by native speakers. Corrections are welcome: send your table to HD Vision Systems so that the next version includes them.

# Annotation Files – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotation-files.html

The files are byte-identical to those of the desktop tool LumiScan Annotation, so LumiScan Training and every other tool that reads them work unchanged.

## Next to each image

For an image `<name>.png` (or `.jpg`, `.bmp`, `.tif`; a page of a multi-page TIFF uses `<name>_page002` and so on, see [Image Formats](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/image-formats.html)):

|   |   |
| --- | --- |
| `<name>.csv` | The boxes (reference annotation): one line per box. |
| `<name>.json` | The save history: who saved when. |

### CSV: the boxes

Tab-separated, with a header line, one line per box:

```none
 centerX	 centerY	   width	  height	angleRad	   label	metadata
 +1106.6	  +149.1	   +68.3	   +59.0	  +0.857	     nut	    null
  +681.4	  +613.1	  +210.6	   +64.8	  +2.512	 bracket	    null
```

|   |   |
| --- | --- |
| `centerX`, `centerY` | Centre of the box in image pixels; x to the right, y downwards from the top left corner of the image. |
| `width` | Along the box’s own x axis, in pixels. |
| `height` | Along the box’s own y axis, in pixels. |
| `angleRad` | Rotation in radians, clockwise in image coordinates. 0: the top of the box points up. The bottom edge (drawn green) is the edge at +height/2. |
| `label` | The class of the object. |
| `metadata` | Additional data as compact JSON, `null` if none. |

Numbers have a sign and one decimal (angle: three), right-aligned in 8 characters; label and metadata are right-aligned in 8 characters too. Line endings as the desktop tool writes them: CRLF on Windows, LF on Linux.

### JSON: the save history

An array with one entry per save:

```json
[
    {
        "user": "anna",
        "timestamp": 1794009447,
        "imageName": "part_003.png",
        "annotationName": "part_003.csv"
    },
    {
        "user": "david",
        "timestamp": 1794009449,
        "imageName": "part_003.png",
        "annotationName": "part_003.csv"
    }
]
```

`timestamp` is the time of the save in seconds since 1970-01-01 UTC (Unix time).

`auto-consensus` marks a reference written automatically because all annotators agreed.

## Several annotators per image

The annotators' own versions are kept apart, so training does not read them:

```none
<folder>/.annotations/<name>/<user>.tsv        an annotator's version (same format as the CSV)
<folder>/.annotations/<name>/consensus.json   who decided the reference, when
```

## Project settings

`<project folder>/.lumiscan-annotation/settings.json`: labels, region of interest, box line thickness, several annotators per image, box suggestions. The keys `labels` and `roiSettings` are those of the desktop tool’s `settings.json`.

## What is kept in the database

Everything else is in the server’s database: accounts, sessions, projects and members, the history of every saved version, revision notes and an index of the images. See [Backup and Restore](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/backup-and-restore.html).

# Image Formats – LumiScan Annotation Web

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

| Format | Notes |
| --- | --- |
| PNG (`.png`) | The format of the desktop tool and of LumiScan Training. Shown and exported as it is. |
| JPEG (`.jpg`, `.jpeg`) | Shown as it is; exported for LumiScan Training as PNG. |
| BMP (`.bmp`) | Shown as it is; exported as PNG. |
| TIFF (`.tif`, `.tiff`) | Also multi-page. The browser cannot show TIFF, so the server sends each page as PNG. Exported as PNG. |

## Annotation files and names

The boxes of an image are in `<name>.csv` next to it, the save history in `<name>.json` (see [Annotation Files](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotation-files.html)). Two images of a folder must therefore not have the same name without extension: if `part_01.png` and `part_01.jpg` are both there, only the PNG is listed (then JPEG, BMP, TIFF). [Adding images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/adding-images.html) in the browser skips such an image.

## Multi-page TIFF

Every page of a multi-page TIFF is an image of its own:

| In the list | Name in the REST API | Annotation file |
| --- | --- | --- |
| scan.tif · page 1 | `scan.tif#1` | `scan_page001.csv` |
| scan.tif · page 2 | `scan.tif#2` | `scan_page002.csv` |
| scan.tif · page 3 | `scan.tif#3` | `scan_page003.csv` |

A TIFF with a single page is listed as `scan.tif` with `scan.csv`. Thumbnails and reduced-resolution copies stored in the file are not pages.

A single page cannot be deleted in the app, because the file holds the other pages. Delete or replace the file in the project folder instead.

## Bit depth

8-bit grey and colour images keep their pixels. 16-bit TIFF pages are reduced to 8 bit for display, suggestions and export, by the bit depth they actually use: if the brightest value is at most 1023 they are treated as 10-bit, at most 4095 as 12-bit, at most 16383 as 14-bit, otherwise as 16-bit. A 12-bit camera image stored in 16 bit is therefore shown with its full brightness range instead of nearly black.

## In the exports

LumiScan Training reads `<name>.png` next to each `<name>.csv`. The [export](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html) therefore writes JPEG, BMP and TIFF pages as PNG (lossless): `part_07.jpg` becomes `part_07.png`, page 2 of `scan.tif` becomes `scan_page002.png`. The COCO export keeps PNG and JPEG files and writes BMP and TIFF pages as PNG.

# REST API – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/rest-api.html

Everything the browser does goes through the server’s REST API, so other programs can use it too, for example to import annotations or read the statistics.

## Basics

- All routes are under `/api`; requests and answers are JSON. `folder` and `name` are query parameters.
- Everything except `GET /api/status` and the sign-in routes needs a session: sign in with `POST /api/auth/login` and send the session cookie with every request.
- Changing requests (POST, PUT, DELETE) need the header `X-Requested-With: lsa`.
- The user is always the signed-in one. Routes about images, settings, history and notes take `project=<id>` (default: the only project the user takes part in, else `default`).
- Errors: `{"error": "<code>", "message": "<text>"}` with the HTTP status (400 bad request, 401 not signed in, 403 role missing, 404 not found, 409 conflict, 423 locked).

```bash
curl -c cookies.txt -H "X-Requested-With: lsa" -H "Content-Type: application/json" \
     -d '{"username":"anna","password":"..."}' https://annotation.example.com/api/auth/login
curl -b cookies.txt "https://annotation.example.com/api/images?project=line-5&folder=2026-10-28"
```

## Routes

Role in brackets: **Admin** is the server admin; the other roles are the user’s roles in the project.

### Sign-in and users

| Method and path | Purpose |
| --- | --- |
| `GET /status` | Version, licence state, accepted image formats and the upload limit (public) |
| `GET /auth/providers` | Which sign-in methods are offered (public) |
| `POST /auth/login` | `{username, password}`: local account, then directory → session cookie |
| `GET /auth/oidc/start`, `/auth/oidc/callback` | Single sign-on (browser redirects) |
| `POST /auth/logout` | End the session; returns the provider’s logout address for single sign-on sessions |
| `GET /auth/me` | The signed-in user, their roles and `settings` (personal settings such as `language`) |
| `PUT /auth/settings` | `{language: "de"}`: save personal settings with the account; `null` removes one (the browser’s language applies again) |
| `GET /i18n` | Languages of the interface: `{languages: [{code, name, english}]}` (public) |
| `GET /i18n/<code>` | The translation table of a language, merged from the installed table and the `translations` folder (public; ETag) |
| `POST /auth/password` | `{current, password}`: change the own password (local accounts) |
| `GET/POST /admin/users`, `PUT/DELETE /admin/users/<name>`, `POST /admin/users/<name>/password` | User management (Admin) |
| `GET/PUT /admin/mappings` | Group → role mappings (Admin) |
| `GET /admin/auth`, `POST /admin/auth/test-ldap` | Configured sign-in methods, test a directory sign-in (Admin) |
| `GET/POST /admin/backups`, `GET /admin/backups/<file>` | List, make and download backups (Admin) |

### Projects

| Method and path | Purpose |
| --- | --- |
| `GET /projects` | Projects the user takes part in, with their roles; for admins also the S3 targets |
| `POST /projects` | `{name, description, folder?, storage?, prefix?, openToAll}`: new project (Admin) |
| `GET/PUT /projects/<id>` | Details; name, description, open to all, members (Project admin) |
| `DELETE /projects/<id>` | `{deleteFiles}`: remove the project (Admin) |
| `GET /projects/<id>/export[?history=0]` | The project file (tar) (Admin) |
| `POST /projects/import`, `PUT /projects/import/<upload>?offset=`, `POST /projects/import/<upload>/finish` | Upload a project file in pieces and unpack it as a new project (Admin) |
| `GET /people` | People with a role in the project (to address notes) |

### Images and annotations

| Method and path | Purpose |
| --- | --- |
| `GET /folders` | Sub-folders of the project |
| `GET /images?folder=` | Images with annotated and locked state, open notes, box count and labels of the reference annotation, the network’s uncertainty once rated, the export set (`set`), the done mark (`done`, `doneBy`, `doneAt`), for TIFF pages `file` and `page`; with several annotators also the counts and review state |
| `GET /image?folder=&name=` | The image: PNG, JPEG and BMP as stored, TIFF pages as PNG (a page is named `scan.tif#2`, URL-encoded `scan.tif%232`) |
| `PUT /image/done?folder=&name=` | `{"done": true}` or `false`: mark the image as done or remove the mark (Annotator, Reviewer) |
| `PUT /images/upload?folder=&name=` | Add an image file, sent as the body (`application/octet-stream`); `newFolder=1` creates the folder; larger files in pieces with `offset` (bytes so far) and `total` (file size). 409 `exists` if the name or its annotation file is taken (Project admin) |
| `GET /annotations?folder=&name=[&layer=annotator]` | Boxes, image size, revision, lock. `layer=annotator`: your own version |
| `PUT /annotations?folder=&name=[&layer=annotator]` | Save `{session, baseRevision, boxes, force?}` → 409 on conflict, 423 if locked |
| `POST/DELETE /lock?folder=&name=[&layer=annotator]` | Take, renew or release the edit lock (`{session}`) |
| `DELETE /image?folder=&name=` | Delete an image with its files, versions, history and notes (Project admin) |
| `POST /geometry/fit-box` | Smallest oriented box around `{points: [[x, y], …]}` |

A box is `{"cx": 412.3, "cy": 267.8, "width": 188.0, "height": 71.4, "angle": -0.385, "label": "bracket", "metadata": null}` (angle in radians).

### History, notes, settings

| Method and path | Purpose |
| --- | --- |
| `GET /history?folder=&name=[&layer=annotator&owner=]`, `GET /history/version?id=` | Saved versions of an annotation; one version with its boxes |
| `GET /notes?folder=&name=`, `GET /notes/open[?mine=1]` | Revision notes of an image; open notes of the project |
| `POST /notes`, `PUT/DELETE /notes/<id>` | `{folder, name, text, assignee, x?, y?}`; `{status, reply, text}`; delete (author or Project admin) |
| `GET /settings`, `PUT /settings` | Project settings (changing: Project admin) |
| `POST /labels` | Add a label to the shared list (Annotator, Reviewer) |

### Review and suggestions

| Method and path | Purpose |
| --- | --- |
| `GET /compare?folder=&name=` | All annotators' boxes, matched objects and differences (Reviewer) |
| `GET /statistics[?folder=]` | Agreement statistics for a folder or the project (Reviewer) |
| `POST /preannotate?folder=&name=` | Box suggestions; body `{boxes?, labels?}`; 501 without a service, 502 if none answers |
| `GET /preannotate/services` | The box suggestion services, their backends and networks |
| `POST /uncertainty/scan` | `{folder, includeAnnotated?, rescore?}`: the network rates the folder’s images in the background (Annotator) |
| `GET /uncertainty/status`, `POST /uncertainty/cancel` | Progress of the rating; stop it |
| `GET /training-export/preview` | What an export for LumiScan Training would contain; parameters `name`, `network`, `validation`, `test`, `together=1`, `folder` (repeatable), `nonRotable` (repeatable) (Reviewer) |
| `GET /training-export` | The export as a ZIP file, same parameters (Reviewer) |
| `GET /coco-export` | The COCO export, same parameters plus `format=zip` (images and annotations) or `format=json` with `set=all`, `train`, `val` or `test` (Reviewer) |

# Release Notes – LumiScan Annotation Web

URL: https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/release-notes.html

This page lists the changes in each version of LumiScan Annotation Web, newest first. Every entry is grouped into **New features**, **Improvements**, **Bug fixes** and **Performance**; **Update notes** say what to check when you install the version over an older one.

To update, install the new version over the old one ([server](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/installing-the-server.html) or [single-PC setup](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/single-pc-installation.html)). Projects, annotations, accounts and settings are kept. To be on the safe side, download a backup first under **your name → Users and sign-in → Backups** (see [Backup and Restore](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/backup-and-restore.html)).

## Version 2.4.1.0 {#v2-4-1}

All texts of the interface now appear in the chosen language, and the German manual shows the German interface.

### Improvements

- Sizes and percentages are written the way the chosen language writes numbers, for example 2,0 GB and 96,6 % in German.
- German manual: all screenshots and videos show the German interface, and the names of buttons and menus are the ones the German interface shows.

### Bug fixes

- Some texts still appeared in English in every language: the reasons for differences in review mode (for example "overlap only 74 %"), the **Delete** buttons, the number of open revision notes, the hint in **Members & access**, the width and height of the region of interest, the text and status of **Rate with network**, and the error messages for uploads and images.

## Version 2.4.0.0 {#v2-4}

The interface now speaks five languages. Edit locks are friendlier when several people work at the same time, and the app starts faster.

### New features

- **Interface in five languages:** English, German, Spanish, French and Chinese (simplified). The app starts in the language of the browser, English if there is none for it.
- **Language saved with your account:** choose a language on the login page or under **your name → Language**. Your choice applies in every browser and on every PC you sign in with. **Same as the browser** goes back to the browser’s language.
- **Own texts and languages without a new version:** administrators can correct texts, use the terms of their company or add a language by putting a translation table into the server’s `translations` folder. The change applies at the next reload of the page, without a restart. See [Languages and Translations](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/languages-and-translations.html).

### Improvements

- Dates and times are shown the way the chosen language writes them.
- Most messages of the server (for example "The current password is wrong.") appear in the chosen language too.
- Before an update changes the database format, the server now keeps a copy of the old database next to it (for example `annotation-server.db.v3.bak`). Going back to the previous version then only means installing it and putting the copy in place of the database.
- New configuration setting `translations_dir` (see [Configuration](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html)).

### Bug fixes

- An image that was read-only because someone else, or another window of your own, had it open stayed read-only until it was opened again. It now becomes editable by itself as soon as it is free, and the app says so.
- A window that had lost its edit lock to someone else could take the lock back in the background while it still showed the image read-only. The image was then blocked for everyone. Fixed.
- Downloads with umlauts, accents or Chinese characters in their name (exports, project files, backups) could arrive with a garbled file name in some browsers. The exact name is now always kept.

### Performance

- Faster start: the app is loaded while the translations are fetched, and the language chosen before is fetched together with the list of languages.
- Unchanged translation tables are not sent again: the browser uses its copy.
- Adding images from the browser needs one listing of the folder less per file, which saves many requests in large S3 buckets.

### Update notes

- The database format changes (version 4). Older versions cannot open the updated database. The server keeps the old one as `annotation-server.db.v3.bak` next to it: to go back to 2.3, stop the server, install 2.3 and replace `annotation-server.db` with that copy (changes made with 2.4 in the meantime are then lost).

## Version 2.3.0.0 {#v2-3}

More image formats, adding images directly in the browser, a way to mark images as finished, and an export for other annotation and training tools.

### New features

- **JPEG, BMP and TIFF** besides PNG, including **multi-page TIFF**: every page is an image of its own with its own annotation file (see [Image Formats](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/image-formats.html)). 16-bit images are shown with the brightness range they actually use (10, 12, 14 or 16 bit).
- **Adding images in the browser** (project admins): **+ Add images** above the image list takes files, a whole folder or drag and drop, into an existing or a new folder. Large files are sent in pieces. Works for folders on the server and for S3 buckets (see [Adding Images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/adding-images.html)).
- **Mark as done:** **Mark done** next to **Save**, or `Shift+D` to save, mark and go on, marks an image as finished, also when it has no boxes. The image list shows a ✓ and the count, and **Show** filters by it.
- **COCO export:** **Export** offers the COCO format, used by CVAT, Label Studio, FiftyOne and many training frameworks: images with annotations as ZIP, or only the annotations as JSON for one set or all (see [Exporting the Annotations](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html)).
- **Set filter:** the image list shows in which set (training, validation, test) the export puts each image and can filter by it.

### Improvements

- **Keep each folder together** is remembered with the export settings of the project.
- The built-in networks for box suggestions read all image formats.
- Done marks are included in the project export and import.
- New configuration setting `upload_max_mb` for the largest file that can be added in the browser.

### Performance

- TIFF pages are converted for the browser once and then kept in a cache; the page list of a TIFF file is only read again when the file changes.
- Added images appear in the list at once, without waiting for the next scan of the folder.

### Update notes

- The database format changes (version 3). After the update, older versions can no longer open the database.

## Version 2.2.0.0 {#v2-2}

LumiScan Annotation on a single PC with its own window, faster annotation of series, finding the right images, and a direct path to LumiScan Training.

### New features

- **Single-PC installation:** a Windows installer with a start-menu and desktop shortcut. LumiScan Annotation runs in its own window, without a login, and only accepts connections from the same PC (see [Single-PC Installation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/single-pc-installation.html)).
- **Copying boxes:** take the boxes of the previous image (`V`), copy boxes to the next images of a series, and copy and paste single boxes or all boxes with `Ctrl+C` / `Ctrl+V`, also between images (see [Copying Boxes and Templates](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/copying-boxes-and-templates.html)).
- **Box templates:** save a box as the typical size and orientation of its label; `T` places one at the mouse pointer.
- **Finding images:** search by file name, filter by state, by label or by the uncertainty of the network, and sort the list (see [Finding and Sorting Images](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html)).
- **Active learning:** **Rate with network** lets the project’s network rate the images; **Network least sure first** shows the images where annotation helps most.
- **Export for LumiScan Training:** a ready LumiScan Training project as ZIP, with a stable split into training, validation and test set.
- **Built-in box suggestions:** trained LumiScan networks run inside the server, without a separate service and without Python.
- **Update check:** project admins see when a newer version is available (single-PC installation; optional on servers).

### Improvements

- Closing the window asks about unsaved changes on macOS and Linux too (before: Windows only).

### Bug fixes

- Windows: configuration and data folders below user or folder names with umlauts did not work.

### Performance

- The image list knows the box count and the labels of every image from the image index, so filtering by label does not read the annotation files again.
- Box suggestions from the built-in networks need no round trip to a separate service.

## Version 2.1.0.0 {#v2-1}

The step from a single-user tool to a team application: sign-in with roles, projects, several annotators per image, history and revision notes.

### New features

- **Sign-in and roles:** local accounts, Active Directory / LDAP and single sign-on with OpenID Connect (Keycloak, Microsoft Entra ID, Okta and others); roles annotator, reviewer and admin, checked by the server (see [Users and Roles](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/users-and-roles.html), [Sign-in Methods](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/sign-in-methods.html)).
- **Projects:** independent annotation jobs with their own folder, settings, members, history and notes; export and import of a whole project as one file (see [Projects](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects.html)).
- **Projects in S3 buckets:** AWS S3, MinIO, SeaweedFS and other S3-compatible stores (see [Projects in S3 Buckets](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects-in-s3-buckets.html)).
- **Several annotators per image**: blind annotation, automatic reference when all agree, a review mode with the differences numbered, and agreement statistics (see [Several Annotators per Image](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html)).
- **Version history and undo:** every saved version of an annotation can be viewed over the image and restored; undo and redo while editing (see [History and Undo](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/history-and-undo.html)).
- **Revision notes:** instructions on an image for a person, pinned to a box if needed, with replies (see [Revision Notes](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/revision-notes.html)).
- **Box suggestions:** a service with Grounding DINO and SAM 2, or with trained LumiScan networks, suggests boxes (`P`) (see [Box Suggestions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestions.html)).
- **Precise drawing:** magnifier with crosshair and pixel grid, center lines through every box, a second drawing mode (**edge rectangle**, `E`), and turning the bottom edge of a box (`R`).
- **Backup and restore** of the database and the configuration, automatic and on demand (see [Backup and Restore](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/backup-and-restore.html)).

### Improvements

- **HTTPS by default** with a self-signed certificate that the server creates and renews itself.
- Responses are compressed for browsers that accept it.
- New login page with the LumiScan apps.
- `A` / `D` skip images hidden by the filter of the image list.

### Bug fixes

- A second server on the same port shared the port silently on Linux; the server now refuses to start and says why.
- The read-only banner said "reviewing" in projects with one annotator per image, where the other person is annotating; it now says "editing".

### Performance

- Drawing, moving boxes, panning and the magnifier are smooth also with many boxes: about five to nine times less work per mouse movement.
- Image lists and statistics come from an index in the database instead of reading every file again.
- Images from S3 buckets are cached on the server and only downloaded again when they change.

### Update notes

- A server that listened on all addresses with plain HTTP now answers with HTTPS on the same port. Set `"https": "off"` in the configuration to keep HTTP.
- The access code (`auth_token`) of version 2.0 is replaced by sign-in; a configuration that still contains it is refused with a hint.

## Version 2.0.0.0 {#v2-0}

The first web version, successor of the desktop LumiScan Annotation 1.7.

### New features

- Annotation in the browser, served by a server for Windows and Linux.
- Annotation files byte for byte as written by the desktop tool, so LumiScan Training reads them unchanged.
- The same way of drawing oriented boxes as in the desktop tool, with its keyboard shortcuts, brightness and contrast, region of interest and labels on keys 1 to 9.
- Several people at once: edit locks per image, a read-only view for images others have open, and a warning when a file was changed by someone else.

# FAQ – LumiScan Annotation Web

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

Short answers to common questions about LumiScan Annotation Web. Each entry links to the page with the details.

> [!TIP]
> Each entry has a fixed anchor (for example `#faq-browsers`). Problems and error messages are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html).

## Requirements and setup

### Which browsers work, and do annotators need to install anything? {#faq-browsers}

- **Answer:** Current versions of Google Chrome, Microsoft Edge and Mozilla Firefox. Annotators install nothing: they open the server’s address, for example `https://annotation-pc:8080/`, and sign in. Only the server is installed, on one computer in your network.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/requirements.html), [Installing the Server](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/installing-the-server.html)

### Do images leave the company network? {#faq-network}

- **Answer:** No. The server, the project folders or S3 buckets and the box suggestion service all run on your computers. Only the browsers of your users access them.
- **More:** [Description](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/description.html), [Before Installation](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/before-installation.html)

### Why does the browser warn that the connection is not private? {#faq-certificate-warning}

- **Answer:** The server speaks HTTPS by default. Without a certificate of its own, it creates a self-signed one at the first start, which browsers do not know yet.
  - Compare the SHA-256 fingerprint in the warning’s certificate details with the one the server log shows at the start (`HTTPS: SHA-256 fingerprint …`), then continue.
  - To get rid of the warning, import `tls/self-signed-cert.pem` from the server on the clients as a trusted certificate, or give the server a certificate of your company’s CA (`tls_cert`, `tls_key`).
  - Behind a reverse proxy that does TLS, the server stays on plain HTTP.
- **More:** [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html#https)

## Desktop tool and files

### Can we keep using the desktop tool LumiScan Annotation? {#faq-desktop-tool}

- **Answer:** Yes. Both write the same files, so the desktop tool and the web app can work on the same project folder. The server takes changes made with the desktop tool into the history (it scans the folders every 60 seconds). If both change the same image at the same time, saving in the browser reports a conflict and offers **Load their version** or **Overwrite with mine**; the other version stays in the history.
- **More:** [Working at the Same Time](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/working-at-the-same-time.html), [Annotation Files](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotation-files.html)

### Does LumiScan Training read the files unchanged? {#faq-training-files}

- **Answer:** Yes. `<image>.csv` and `<image>.json` next to each image are byte-identical to those of the desktop tool. With several annotators per image, the reference annotation is written to exactly these files, so training reads only agreed or reviewed boxes.
- **More:** [Annotation Files](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/annotation-files.html), [Several Annotators per Image](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html)

### Our cameras save JPEG or multi-page TIFF. Do we have to convert the images?

- **Answer:** No. PNG, JPEG, BMP and TIFF are read, every page of a multi-page TIFF is an image of its own. The export writes them as PNG for LumiScan Training.
- **More:** [Image Formats](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/image-formats.html)

## Annotating together

### Can several people annotate the same image? {#faq-same-image}

- **Answer:** Not at the same time in normal mode: whoever opens the image first holds the edit lock, the others see it read-only, with a banner that names who is editing. The lock ends 60 seconds after that person closes the image. With several annotators per image, every annotator has their own version, and they can work on the same image at the same time.
- **More:** [Working at the Same Time](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/working-at-the-same-time.html)

### Why can’t an annotator see the other annotators' boxes? {#faq-blind}

- **Answer:** With several annotators per image, annotation is blind on purpose: only independent annotations show where images are ambiguous. Reviewers see all versions side by side and decide.
- **More:** [Several Annotators per Image](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html), [How To: Check Annotations with Two Annotators](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/check-annotations-with-two-annotators.html)

### What happens when two annotators agree? {#faq-agreement}

- **Answer:** The server writes the mean of their boxes as the reference annotation. Training uses it, and nobody needs to review the image. Otherwise the image goes to review, sorted by the largest differences first.
- **More:** [Several Annotators per Image](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/several-annotators-per-image.html)

### Where do I find the notes left for me? {#faq-notes}

- **Answer:** **✎ n notes for you** in the top bar opens the next image with a note for you. Use **Reply** to answer and **Done** once you have fixed the image; done notes stay visible.
- **More:** [Revision Notes](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/revision-notes.html)

### How do I undo a save? {#faq-undo}

- **Answer:** Open **History**, click the earlier version, choose **Restore**, then **Save**. Saving adds a new version; the history is never rewritten.
- **More:** [History and Undo](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/history-and-undo.html)

## Box suggestions

### Why is **Suggest boxes** missing? {#faq-suggest-missing}

- **Answer:** The server has no box suggestion service configured (`pre_annotation` in the configuration), or you have no annotator role in the project.
- **More:** [Box Suggestion Service](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestion-service.html), [Box Suggestions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestions.html)

### Do the suggestions get better over time? {#faq-suggestions-improve}

- **Answer:** Yes, if you retrain the network regularly with the corrected annotations and put the new network into the service. Every corrected suggestion is training data for the next network.
- **More:** [How To: Annotate Faster with Box Suggestions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/how-tos/annotate-faster-with-box-suggestions.html)

### Which images should we annotate first? {#faq-which-images-first}

- **Answer:** The ones the network is least sure about. **Rate with network** above the image list rates the folder; **Network least sure first** sorts by it.
- **More:** [Rate with network](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/finding-and-sorting-images.html#rate-with-network)

### How do the images get into LumiScan Training? {#faq-training-split}

- **Answer:** **Export** in the top bar downloads a ready LumiScan Training project with training and validation images. Unpack it into the Training’s projects folder and open it there.
- **More:** [Exporting the Annotations](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html)

### Can we use the annotations in other tools?

- **Answer:** Yes. **Export** also offers the COCO format, with or without the images. Standard tools draw each oriented box from its corners (`segmentation`); the exact box is in `obb`.
- **More:** [COCO](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/export-for-lumiscan-training.html#coco)

## Projects, access and backups

### How do I give a whole department access? {#faq-department-access}

- **Answer:** Add their directory group as a member of the project, or map the group to a role under **Groups → roles**. Members of the group sign in with their directory or single sign-on account and get the role of their group.
- **More:** [Groups](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/users-and-roles.html#groups), [Sign-in Methods](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/sign-in-methods.html)

### How do I send a project to HD Vision Systems? {#faq-send-project}

- **Answer:** **Projects** → **Export** gives one file with images, annotations, settings and notes. HD Vision Systems imports it, annotates and sends it back the same way.
- **More:** [Export and import](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects.html#exporting-and-importing)

### What is backed up, and how often? {#faq-backup}

- **Answer:** The server backs up the database (accounts, projects, history, notes), the configuration and the HTTPS certificate automatically, every 24 hours by default, and keeps the last 14 backups. The images and annotation files are backed up with your folders, or per project with the export.
- **More:** [Backup and Restore](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/backup-and-restore.html)

## Troubleshooting {#troubleshooting}

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

- [The page does not open](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-page-does-not-open)
- [A certificate warning in the browser](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-certificate-warning)
- [Sign-in fails](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-sign-in-fails)
- [Signed in but no access ("No role")](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-no-role)
- [Nobody can sign in as administrator](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-no-admin)
- [The project is not in the list](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-project-missing)
- [The image is read-only](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-read-only)
- ["Changed by someone else" when saving](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-changed-by-someone-else)
- [New images do not appear](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-new-images-missing)
- ["No suggestions" or an error after **Suggest boxes**](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-no-suggestions)
- [S3 project: access or signature errors](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-s3-errors)
- [The server does not start](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#ts-server-does-not-start)

## Licence and support

### Which licence do I need? {#faq-licence}

- **Answer:** This version of LumiScan Annotation Web runs without a LumiScan Key. For licensing questions, contact HD Vision Systems.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/requirements.html#licence)

### 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 at [info@hdvisionsystems.com](mailto:info@hdvisionsystems.com) or +49 6221 67219-00, and send the server log and the version (`lumiscan-annotation-server --version`).
- **More:** [Logs](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/troubleshooting.html#logs)

# Troubleshooting – LumiScan Annotation Web

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

| Problem | Solution |
| --- | --- |
| The page does not open | Check the address and port (default `8080`) and that it starts with `https://`. Is the server running? Is the port open in the server’s firewall? The server log shows `Listening on https://…` after a successful start. |
| "Your connection is not private" or a similar certificate warning | The server uses its self-signed certificate. Compare the fingerprint with the server log and continue, or make the clients trust the certificate, see [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/configuration.html#https). |
| The server does not start: "HTTPS: cannot create the self-signed certificate" | The server’s account may not write the folder `tls` next to the configuration. Give it write access, or set `tls_cert` and `tls_key`. |
| "Server not reachable" in the status | The connection to the server was interrupted. Unsaved changes stay in the browser; save again once the server is back. |
| Sign-in fails | Check user name and password (the message never says which one is wrong). After 5 failed attempts the account is blocked for 15 minutes. Directory users: test the sign-in under **Users and sign-in** → **Sign-in methods**. |
| "No role": signed in but no access | New directory or single sign-on users without a group mapping have no role. An admin gives a role under **Users and sign-in**, or maps the group. |
| Nobody can sign in as administrator | On the server: `lumiscan-annotation-server --config <configuration> --reset-password admin` prints a new password. |
| The project is not in the list | You are not a member. Ask the project admin or a server admin to add you or your group. |
| The image is read-only | Someone else is editing it (the banner and the image list name them), or you have it open in another window. The lock ends 60 seconds after the other window was closed. |
| "Changed by someone else" when saving | The annotation file was changed after you opened the image, for example with the desktop tool. Choose **Load their version** or **Overwrite with mine**; the other version stays in the history. |
| New images do not appear | The server scans the folders every 60 seconds (`index_refresh_seconds`). Wait or switch the folder. The images must be PNG, JPEG, BMP or TIFF files in the project folder or one level of sub-folders (see [Image Formats](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/image-formats.html)); an image with the same name as a PNG next to it is not listed. |
| **Suggest boxes** is missing | No box suggestion service in the configuration (`pre_annotation`), or you have no annotator role. |
| "No suggestions" or an error after **Suggest boxes** | Check the service: `curl …/v1/health` (see [Checking the service](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/box-suggestion-service.html#checking-the-service)). The network of the project must exist on the service; its classes must match the labels of the project. With several services, one that does not answer only gives a warning. |
| S3 project: "access denied" / "SignatureDoesNotMatch" / "RequestTimeTooSkewed" | Wrong keys, missing permissions (see [AWS permissions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/projects-in-s3-buckets.html#aws-permissions)) or a server clock that is off by more than 15 minutes. |
| The server does not start: "database is locked" or file errors | The database must be on a local disk, not on a network share. Is another server instance running with the same configuration? |
| The restore refuses to run | The server is still running. Stop it first. |

## Logs {#logs}

- The server writes its log to the console and, with `log_dir`, to rotating files. It names the configuration, the projects, the sign-in methods and the box suggestion services at the start, and every error with its reason.
- Box suggestion service: Ubuntu `journalctl -u lsa-preannotate -f`, Windows `C:\ProgramData\LumiScan\PreAnnotate\default.log`.

Still stuck? Contact HD Vision Systems: [info@hdvisionsystems.com](mailto:info@hdvisionsystems.com), +49 6221 67219-00. Please send the server log and the version (`lumiscan-annotation-server --version`).
