Box Suggestion Service

The box suggestion service suggests boxes for the open image (see Box Suggestions). 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:

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.

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.

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

Checking the service

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.