---
title: "Box Suggestion Service"
description: "Install the box suggestion service for LumiScan Annotation Web on Ubuntu, Windows or macOS and connect your trained LumiScan networks (ONNX)."
product: "LumiScan Annotation Web"
component: "lumiscan-annotation-web"
version: "2.1.0"
display_version: "2.1.0.0"
latest_version: false
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/box-suggestion-service.html"
---

# Box Suggestion Service – LumiScan Annotation Web

The box suggestion service suggests boxes for the open image (see [Box Suggestions](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/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/2.1.0/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`.