FAQ

Short answers to common questions about LumiScan Template Finder. Each entry links to the page with the details.

Each entry has a fixed anchor (for example #faq-pixel-formats). Problems, error messages and status codes are described step by step in Troubleshooting.

Requirements and setup

On which platforms does the Template Finder run, and which Data Layer does it use?

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, ctrlX Data Layer and LumiScan Keryx

Which image source does the Template Finder need?

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, Data Layer Reference

Which pixel formats are supported?

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

Templates

How do I create a template from a live camera image?

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, How To: Match a Part from a Camera Image

Where are templates stored, and can I upload one prepared on a PC?

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

Searching and tuning

How do I run a search and read the 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

How can I make the search faster?

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, Requirements

How do I search only part of the image, and which frame are the positions in?

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

Can the Template Finder search every frame a camera streams?

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), Streams (Experimental)

Status codes and errors

How do I know whether an operation worked, and where is the reason for a failure?

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, Execution Status

Troubleshooting

Problems and error messages are described step by step in Troubleshooting:

Licensing and support

Which licence do I need, and how many modules does it cover?

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, Module Management, Licensing FAQ

Where can I find more answers or get support?

Answer: See the site-wide LumiScan FAQ. Contact HD Vision Systems customer success at customer.success@hdvisionsystems.com or +49 6221 6721905; for licences, 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, Licensing FAQ