FAQ

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.

Data Layer Reference, ctrlX Data Layer and LumiScan Keryx

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

Requirements

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.

Requirements

Use system/create-object, which is application-wide, so an object taught once is findable by every module:

Creating an Object, How To: Find a Part from a Camera Image

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.

Creating an Object

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.

Object Storage

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.

Finding an Object

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.

Tuning the Search

Tuning the Search: Speed

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:

Finding Objects on an Image Stream (Experimental), Streams (Experimental)

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.

Execute a Method, Execution Status

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:

Requirements, Module Management, Licensing FAQ

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.

Licensing FAQ