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

# FAQ – LumiScan Template Finder

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

## Requirements and setup

### On which platforms does the Template 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-template-finder/1.1.0/lumiscan-template-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 Template 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). An address inside the Template Finder itself is rejected with status code `-2`.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/requirements.html), [Data Layer Reference](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/datalayer-reference.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, so templates cut from one format still match images of another. Any other pixel format is rejected with status code `-3`.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/requirements.html)

## Templates

### How do I create a template from a live camera image? {#faq-create-template}

- **Answer:** Use `system/create-template`, which is application-wide: it cuts a region out of the current image and saves it as a PNG that every module can use:
  - Make sure the camera application has captured an image.
  - Set `system/create-template/input/input-image-address`, the four `input/crop/` values (`width` and `height` must be greater than 0) and `input/template-name`. Use a lower case name; `.png` is added if you give no extension.
  - Write to `system/create-template/execute` and read `output/status-code`. On `1`, `output/template-path` names the file, for example `templates/screw.png`.
  - On `-5`, the region does not fit the image; `output/status-text` names the actual image size.
  - The file is written as 8-bit RGB PNG, whatever the camera’s pixel format. An existing file with the same name is overwritten without warning.
- **More:** [Creating a Template](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/creating-a-template.html), [How To: Match a Part from a Camera Image](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/how-tos/match-a-part-from-a-camera-image.html)

### Where are templates stored, and can I upload one prepared on a PC? {#faq-template-storage}

- **Answer:** Templates are PNG files in the `templates` folder of the application’s configuration directory, created at first start. A template added by hand is read on the next search, without a restart.
  - On ctrlX OS the directory is part of the active solution (`/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-template-finder`), so templates are exported and restored with the solution. A prepared PNG (8-bit RGB or grayscale) can be uploaded into it through the ctrlX web interface.
  - On a PC a prepared PNG is copied into the folder. On Windows the directory is `%APP_RESOURCE_DIR%\etc\lumiscan-template-finder`, or without `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-templ-find\etc\lumiscan-template-finder`.
  - To use another folder, write `system/set-template-dir/input/template-dir`, execute `system/set-template-dir` and check that its status code is `1`. The folder must already exist; an absolute path or one leading outside the configuration directory is rejected with `-2`.
- **More:** [Template Storage](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/template-storage.html)

## Searching and tuning

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

- **Answer:** Set `find-template/input/input-image-address` and `find-template/input/template-name` (as listed on `system/templates`), write to `find-template/execute` and read `find-template/output/status-code`. The write is blocking and returns when the search has finished. On `1`, read `output/result`: `matches` is sorted by confidence, so `matches[0]` and `best_score` give the best match. Each match has an `oriented_bounding_box` (`center_x`, `center_y`, `width`, `height` in pixels, `angle` in degrees), `confidence`, `scale` and `rotation`. An empty `matches` list with status `1` is a normal result: the part was not found.
- **More:** [Finding a Template](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/finding-a-template.html)

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

- **Answer:**
  - Search only as wide a scale and rotation range as the parts actually vary, with a coarse step.
  - Raise `input/preprocess/bin-size` to `2` (roughly four times faster) and check the confidence is still acceptable. Small or thin templates should stay at `1`.
  - Keep `input/use-grayscale` at `true` (roughly three times faster than matching each colour channel); turn it off only when colour distinguishes the part.
  - Limit the search to a region with `input/crop/`.
- **More:** [Tuning the Search](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/tuning-the-search.html), [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/requirements.html)

### How do I search only part of the image, and which frame are the positions in? {#faq-search-region}

- **Answer:** Set `find-template/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, not trimmed, with a message such as `crop/startX + crop/width (100 + 541 = 641) exceeds the image width 640`. `input/result-coordinate` decides the frame of the positions: `IMAGE` (default, the full image, usable directly for a robot pick) or `CROP` (the searched region, top left corner (0,0)).
- **More:** [Finding a Template](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/finding-a-template.html)

### Can the Template 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-template` (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-template/output/result`.
- **More:** [Finding Templates on an Image Stream (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-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:`. A failed write to `execute` itself answers only with a status code (over REST, a bare `400`), so read `output/status-text` afterwards. The same text is written to 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, so try again when it has finished.
- **More:** [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/execute-a-method.html), [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/execution-status.html)

## Troubleshooting {#troubleshooting}

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

- [Status code `-1` (busy)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-busy-while-streaming)
- [Status code `-2` (invalid input)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-status-minus-2)
- [Status code `-3` (image read failed)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-status-minus-3)
- [Status code `-4` (source not found)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-status-minus-4)
- [The crop region does not fit the image](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#ts-crop-does-not-fit)
- [Status code `-6` (write failed)](https://docs.hdvisionsystems.com/en/lumiscan-template-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-template-finder/1.1.0/troubleshooting.html#ts-empty-result)
- [The template is not found even in the image it was cut from](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-not-found-in-own-image)
- [The part is not found when it is rotated or at a different distance](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-rotation-scale)
- [A wide search reports weak matches in the wrong places](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-spurious-matches)
- [`output/result` is empty although the search worked a moment ago](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-result-empty)
- [The template file is on the device but missing from `system/templates`](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-template-not-listed)
- [The image stream delivers no results](https://docs.hdvisionsystems.com/en/lumiscan-template-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-template-finder/1.1.0/troubleshooting.html#faq-settings-lost)
- [The application stops shortly after starting](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-app-stops-after-start)
- [Status code `-11` (licence unavailable)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#ts-licence-unavailable)

## 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-template-finder/1.1.0/lumiscan-template-finder/requirements.html#licence), [Module Management](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-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). Before reproducing a problem for a support report, set `logLevel` to `TRACE` in the `system` block of `lumiscan-template-finder.json` and restart the application.
- **More:** [Template Storage](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/template-storage.html), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)