---
title: "FAQ"
description: "Frequently asked questions about LumiScan Area Detector - image source and pixel formats, commissioning the threshold level, reading the result, the label image, the image stream, status codes, settings files and licensing."
product: "LumiScan Area Detector"
component: "lumiscan-area-detector"
version: "1.2.0"
display_version: "1.2.0.6"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/faq.html"
---

# FAQ – LumiScan Area Detector

Short answers to common questions about LumiScan Area Detector. Each entry links to the page with the details.

> [!TIP]
> Each entry has a fixed anchor (for example `#faq-pixel-formats`). Problems, error messages and status codes are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html).

## Requirements and setup

### Which image source does the Area Detector need? {#faq-image-source}

- **Answer:** The application does not talk to a camera itself. It reads the image node of another application that runs on the **same device** - the same ctrlX CORE or ctrlX IPC, or the same PC (remote Data Layer access is not supported), normally LumiScan Cam Driver, for example `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. Any application works if its image node provides `data` (raw, uncompressed uint8 pixel data), `width`, `height` and `pixel-type` (GenICam pixel format name). No reference picture is needed.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/requirements.html), [Description](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/description.html)

### Which pixel formats are supported? {#faq-pixel-formats}

- **Answer:** `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` and `BayerRG12`. Bayer images are converted to colour and 12-bit images are scaled down to 8 bit before detection, so a threshold tuned on one format still applies to another. Any other pixel format is rejected with status code `-3`.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/requirements.html)

## Detecting and measuring

### How do I run a detection and read the result? {#faq-first-run}

- **Answer:** Set `<module>/detect-area/input/input-image-address`, write to `<module>/detect-area/execute` (a blocking call) and check that `output/status-code` is `1`. Then read `output/result`: `blobs` is sorted by area, so `blobs[0]` is the largest; each blob has its centre `x`, `y`, its `area` in pixels (counted, never derived from a fitted shape), its `label` and a bounding box. `blob_count` gives the number of regions and `total_area` the sum, which is usually the number to act on for coverage, contamination and fill checks.
- **More:** [Detecting Areas](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/detecting-areas.html), [How To: Measure Part Area from a Camera Image](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/how-tos/measure-part-area-from-a-camera-image.html)

### How do I find the right threshold level? {#faq-commission-level}

- **Answer:** Measure the picture instead of guessing. `FIXED` is the only `input/method` in this version; anything else is refused.
  - Set `system/analyse-scene/input/input-image-address` and write to `system/analyse-scene/execute`.
  - Read `output/recommended-settings`: `node=value` lines relative to a module’s `detect-area/input/`, holding the level, which end is the part and whether to fill holes. Nothing is written for you.
  - Check the advice with `output/histogram`: the level should sit in the valley between the part’s hump and the background’s. One hump means no level will work and the lighting needs fixing.
  - Set `<module>/detect-area/input/method-specific/fixed/level` (0-255, default `128`).
- **More:** [Analysing a Scene](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/analysing-a-scene.html), [Tuning the Detection](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/tuning-the-detection.html)

### Which preprocessing filters are there, and what do they need? {#faq-preprocessing}

- **Answer:** `input/preprocess/method` applies one filter before detection: `NONE` (default), `LOG` (Laplacian of Gaussian), `DOG` (Difference of Gaussians; `sigma-first` must differ from `sigma-second`) or `DOH` (Determinant of Hessian; `kernel-size` must be 1, 3, 5 or 7). Only the chosen method’s parameters are read and validated. All three normalise their output, so the threshold level may need revisiting after enabling one.
- **More:** [Detecting Areas](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/detecting-areas.html), [Tuning the Detection](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/tuning-the-detection.html)

### How do I find the pixels belonging to a reported region? {#faq-label-image}

- **Answer:** Every run publishes `output/blob-labels`, an ordinary image node (`data`, `width`, `height`, `pixel-type`) in `Mono16`, with one region number per pixel and `0` for background. The numbers are the `blobs[].label` values in `output/result`, so all pixels holding a blob’s label are that region; a binary mask is `labels > 0`. The image is whole frame, at the size of the input image, and labels are not renumbered. It is emptied when the next run starts.
- **More:** [The Label Image](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/the-label-image.html)

### How do I restrict the search or make it faster? {#faq-crop-speed}

- **Answer:** Set `input/crop/` (`startX`, `startY`, `width`, `height`); a zero width or height reaches the right or bottom edge, so all zero searches the whole image. A region reaching past an edge is refused rather than trimmed, naming the input and the limit it broke. For speed, restrict the area first, then raise the level so noise and dust stop crossing the threshold.
- **More:** [Detecting Areas](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/detecting-areas.html), [Tuning the Detection](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/tuning-the-detection.html)

### How do I detect areas on every frame of a camera stream? {#faq-stream}

- **Answer:** Subscribe a module to the Cam Driver’s stream (experimental): write the camera’s stream folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, to `<module>/control/subscribe/input/address`, set `control/subscribe/input/enable` to `true` and write to `control/subscribe/execute`. Each frame is searched with the inputs of `detect-area`, and one result per frame is published on `control/subscribe/output/stream/result`. The label image is not streamed. To read the latest result as a plain `detect-area/output/result`, set `control/subscribe/input/keep-latest-output` to `true`.
- **More:** [Detecting Areas on an Image Stream](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/processing-an-image-stream.html), [Streams](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html)

## Status codes and errors

### How do I know whether a detection worked, and where is the reason for a failure? {#faq-status-codes}

- **Answer:** Check the sign of `output/status-code`: greater than 0 is success, `0` means the operation has not run since the application started, less than 0 means it failed and produced nothing; do not use the result then. The reason is on `output/status-text`. A failed write to `execute` answers only with a status code (over REST, a bare `400`), so read `output/status-text` afterwards; the text is also in the application log: on ctrlX OS in the ctrlX Logbook or `journalctl`, on a PC in the application’s console output.
- **More:** [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/execute-a-method.html), [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/execution-status.html)

## Troubleshooting {#troubleshooting}

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

- [Status code `-1` (busy)](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-status-minus-1)
- [Status code `-2` (invalid input)](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#ts-status-minus-2)
- [Status code `-3` (image read failed)](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-status-minus-3)
- [The crop region does not fit the image](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#ts-crop-does-not-fit)
- [Status code `-6` (write failed)](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#ts-status-minus-6)
- [Nothing is found, or the result is empty](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-nothing-found)
- [The measured area is larger or smaller than the part](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-area-wrong)
- [Many tiny regions are reported](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-tiny-regions)
- [One part is reported as several regions](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-part-split)
- [The reading drifts with the lighting, or no level works](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-reading-drifts)
- [`output/result` is empty although the detection worked a moment ago](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-result-empty-next-run)
- [The image stream delivers no results](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#ts-stream-no-results)
- [My settings or modules are gone after a restart](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-settings-lost)
- [The application stops shortly after starting](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#ts-app-stops-after-start)
- [Status code `-11` (licence unavailable)](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#ts-licence-unavailable)

## Modules, licensing and support

### Where are the settings files? {#faq-settings-files}

- **Answer:** In the application’s configuration directory, `lumiscan-area-detector/`: the application settings file `lumiscan-area-detector.json` and one `<module-id>.json` per saved module.
  - On ctrlX OS: in the active solution, `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-area-detector`.
  - On a PC (Windows): `%APP_RESOURCE_DIR%\etc\lumiscan-area-detector`; without `APP_RESOURCE_DIR`, `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-areadetect\etc\lumiscan-area-detector`.
  - On a PC, `lumiscan-areadetect --generate-settings <folder>` writes an example of both files, with their JSON schemas, into a folder of your choice.
- **More:** [Data Layer Reference](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/datalayer-reference.html#configuration-file), [Where the files are](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html#files)

### Which licence do I need, and how many modules does it cover? {#faq-licence}

- **Answer:** One licence covers ten modules; the eleventh module acquires a second licence of the same key, and a module is refused with status `-11` when no licence on the device covers it. Purchase routes:
  - Bought from HD Vision Systems: the licence is on a LumiScan Key (Windows 11 or Ubuntu 24.04). One LumiScan Key is needed per device running the software at the same time; keys can be exchanged between devices.
  - Bought in the ctrlX Store for Windows 11: ctrlX WORKS plus a LumiScan Key.
  - Bought in the ctrlX Store for ctrlX OS (ctrlX CORE or IPC): a ctrlX licence, no key.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/requirements.html#licence), [Module Management](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/module-management.html), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)

### 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 customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905; for licences, [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).
- **More:** [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)