---
title: "FAQ"
description: "Frequently asked questions about LumiScan Object Finder - platforms and Data Layer, image source and pixel formats, teaching objects, tuning the search, the image stream, status codes, saving modules and licensing."
product: "LumiScan Object Finder"
component: "lumiscan-object-finder"
version: "1.1.0"
display_version: "1.1.0.7"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/faq.html"
---

# FAQ – LumiScan Object Finder

Short answers to common questions about LumiScan Object Finder. 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-object-finder/1.1.0/troubleshooting.html).

## Requirements and setup

### On which platforms does the Object Finder run, and which Data Layer does it use? {#faq-platforms}

- **Answer:** On ctrlX OS (ctrlX CORE or ctrlX IPC) it uses the ctrlX Data Layer; on a PC with Windows 11 or Ubuntu 24.04 it uses LumiScan Keryx, the Data Layer of HD Vision Systems for PCs. The node addresses, types and the way the methods are called are the same on both, so a program written against one works against the other. Only the names of the results of a method call differ, for example `DL_TOO_MANY_OPERATIONS` on the ctrlX Data Layer and `TooManyOperations` on LumiScan Keryx.
- **More:** [Data Layer Reference](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/datalayer-reference.html), [ctrlX Data Layer and LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/platforms.html)

### Which image source does the Object Finder 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).
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/requirements.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 matching. Any other pixel format is rejected with status code `-3`.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/requirements.html)

## Teaching objects

### How do I teach an object from the live camera? {#faq-create-object}

- **Answer:** Use `system/create-object`, which is application-wide, so an object taught once is findable by every module:
  - Put the part in front of the camera, in the lighting the installation will use.
  - Set `system/create-object/input/input-image-address`, `input/object-id` (for example `screw-m6`) and `input/crop/startX`, `startY`, `width`, `height` (width and height greater than 0).
  - Write to `system/create-object/execute` and check that `output/status-code` is `1`.
  - The picture is saved as `<object-id>.png`, `output/object-path` names the file, and `system/objects` lists the new object. An existing object with the same id is overwritten.
- **More:** [Creating an Object](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/creating-an-object.html), [How To: Find a Part from a Camera Image](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/how-tos/find-a-part-from-a-camera-image.html)

### How tightly should I crop when teaching an object? {#faq-crop-margin}

- **Answer:** Leave about 5 pixels of background around the part; more buys nothing. A crop that stops at the silhouette hides the outline from the detector: the object is either refused as a failed run naming it, or accepted but keyed only on the part’s interior detail. A loose crop that takes in a workbench edge or a neighbouring part makes matching less reliable, because background inside the picture is background the detector then expects to see.
- **More:** [Creating an Object](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/creating-an-object.html)

### How do I switch to another object directory? {#faq-object-dir}

- **Answer:** Write `system/set-object-dir/input/object-dir` and write to `system/set-object-dir/execute`. Do not write `system/object-dir` directly: that changes the value shown but not the directory the application reads. The directory must already exist inside the configuration directory; absolute paths and paths climbing out with `..` are refused with status `-2`. A rejected call changes nothing, and the choice is saved.
- **More:** [Object Storage](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/object-storage.html)

## Finding and tuning

### How do I run a search and read the result? {#faq-find-object}

- **Answer:** Set `<module>/find-object/input/input-image-address` and `input/object-id`, write to `<module>/find-object/execute` (a blocking call) and read `output/status-code`. `input/object-id` is required: an empty value is refused with `-2`. Each run searches for one object; to sort mixed parts, run once per object and compare the scores. On `1`, read `output/result`: `matches` is sorted by score, so `matches[0]` is the best. Each match gives the top left corner `x`, `y`, the `width` and `height` of the template that matched, the `score` (0 to 1) and the `object_id`. The rectangle is axis aligned; there is no rotation in the result.
- **More:** [Finding an Object](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/finding-an-object.html)

### How do I choose the confidence threshold? {#faq-confidence-threshold}

- **Answer:** Measure rather than guess. Set `input/confidence-threshold` low (`0.4`), run against real parts, note the scores in `output/result`, and set the threshold a little below the worst score a genuine part produces. The default is `0.6`; a threshold at or above `0.9` will usually reject everything. If genuine scores hover near the threshold or images are noisy, set `input/preprocess/blur-sigma-x` to `1.0` (blur is off by default) and measure again.
- **More:** [Tuning the Search](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/tuning-the-search.html)

### How can I make the search faster? {#faq-search-speed}

- **Answer:**
  - Restrict the area with `input/crop`; this costs no precision.
  - Raise `input/preprocess/bin-size`. On a 1920x1080 image with a 128x128 object, `2` measured about 6x and `4` about 14x faster. Positions quantise to `bin-size` pixels, and an object binned too far is refused.
  - Search for fewer objects; each `execute` reprocesses the whole image.
  - Keep the settings stable between runs: the detector is compiled on the first run and rebuilt whenever an input changes, which costs far more than a detection.
  - Raising `input/pyramid` does not make the search faster; measured, it is slightly slower.
- **More:** [Tuning the Search: Speed](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/tuning-the-search.html#speed)

### Can the Object Finder search every frame a camera streams? {#faq-image-stream}

- **Answer:** Yes, as an experimental feature. A module subscribes to one camera’s stream and searches each frame with the inputs of `find-object` (all but `input/input-image-address`), publishing one result per frame on `<module-id>/control/subscribe/output/stream/result`:
  - Make sure the Cam Driver’s stream runs.
  - Write the camera’s stream folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, to `<module-id>/control/subscribe/input/address`.
  - Set `control/subscribe/input/enable` to `true` and write to `control/subscribe/execute`. Writing `enable` alone starts nothing.
  - Wait until `control/subscribe/output/stream/active` is `true`.
  - What `control/subscribe/execute` applies is saved in `<module-id>.json`, so a module that streamed streams again after a restart. For a PLC, switch on `control/subscribe/input/keep-latest-output` and read `find-object/output/result`.
- **More:** [Finding Objects on an Image Stream (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/processing-an-image-stream.html), [Streams (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html)

## Status codes and errors

### How do I know whether an operation 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. The reason is on `output/status-text`, which starts with `ok:` or `error:`; invalid inputs are reported together, each naming the input and its value. 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 with `journalctl`, on a PC in the application’s console output. `-1` (busy) means another operation of the same module was still running; nothing was done.
- **More:** [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/execute-a-method.html), [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/execution-status.html)

## Troubleshooting {#troubleshooting}

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

- [Status code `-1` (busy)](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-busy-while-streaming)
- [Status code `-2` (invalid input)](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#ts-status-minus-2)
- [Status code `-3` (image read failed)](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-status-minus-3)
- [Status code `-4` (source not found)](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-status-minus-4)
- [The crop region does not fit the image](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-crop-does-not-fit)
- [The run fails and names the object](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-object-refused-bin-size)
- [Status code `-6` (write failed)](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#ts-status-minus-6)
- [The result is empty although the status code is `1`](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-empty-result)
- [One part is reported several times](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-duplicate-matches)
- [`output/result` is empty although the search worked a moment ago](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-result-empty-next-run)
- [An uploaded `.png` does not appear on `system/objects`](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-object-not-listed)
- [The image stream delivers no results](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#ts-stream-no-results)
- [My settings or modules are gone after a restart](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-settings-lost)
- [The application stops shortly after starting](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#ts-app-stops-after-start)
- [Status code `-11` (licence unavailable)](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#ts-licence-unavailable)

## Modules, licensing and support

### 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-object-finder/1.1.0/lumiscan-object-finder/requirements.html#licence), [Module Management](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/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)