Troubleshooting

Another operation of the same module was still running. A second call is not queued; it returns at once and does nothing.

The module’s image stream is searching a frame. The stream and find-template never run at the same time on one module.

If another operation was still running: wait for the running execute to return, then call the method again. The lock is per module, so other modules are not held up.

If the stream of the module runs:

If system/remove-module answers busy: stop the stream of the module first. Removing a module stops its stream.

A required input is empty: input/input-image-address or input/template-name.

The match mode is misspelled. input/match-mode accepts TM_SQDIFF, TM_SQDIFF_NORMED, TM_CCORR, TM_CCORR_NORMED, TM_CCOEFF and TM_CCOEFF_NORMED.

A search parameter is out of range, for example input/scale/min-scale or input/rotation/step-rot not greater than 0, or a rotation outside 0 to 360.

The image address points at this application itself.

A folder or file name is an absolute path, such as /tmp/templates, or a path that leads outside the configuration directory, such as ../../etc.

If a required input is empty: set it. input/template-name takes an entry of system/templates.

If the match mode is misspelled: write one of the accepted names to input/match-mode.

If a search parameter is out of range: correct it, see Tuning the Search.

If the image address points at this application: set input/input-image-address to the image node of the camera application, for example hdvisionsystems/lumiscan-cam-driver/camera1/output/image.

If a path is absolute or leaves the configuration directory: give it relative to the configuration directory. A path that stays inside is fine even if it contains ...

The camera application is not running, or it runs on another device.

The camera application has not captured an image yet.

The address in input/input-image-address is wrong.

The image node at the address is missing, empty or inconsistent.

The image uses an unsupported pixel format. Supported are Mono8, Mono12, RGB8, RGB12, BGR8, BGR12, BayerGR8, BayerGR12, BayerRG8 and BayerRG12.

If the camera application is not running: start it on the same device and capture an image.

If no image has been captured yet: capture an image in the camera application.

If the address is wrong: correct input/input-image-address.

If the pixel format is not supported: use one of the supported pixel formats, see Requirements.

The message names a directory: the template folder does not exist. The default templates is created at startup, so either it was deleted or the folder name is wrong.

The message names a file: the folder exists but holds no such file.

The file is there but is not found: it is in a different folder from the one in use. All modules share one template folder.

If the folder does not exist: switch to an existing folder with system/set-template-dir, or correct its name. The folder must already exist; it is not created for you.

If the folder holds no such file: correct the spelling of input/template-name, or create the template with system/create-template.

If the file is in another folder: move the file into the folder system/template-dir names, or switch with system/set-template-dir.

The region reaches past an edge of the image. A region reaching past an edge is refused, not trimmed.

For find-template, the region is smaller than the template. This is refused with status -5.

For system/create-template, input/crop/width or input/crop/height is 0. Both must be greater than 0.

If the region reaches past an edge: correct input/crop/startX, startY, width or height, so that the region fits the image. A zero width or height reaches the right or bottom edge.

If the region is smaller than the template: widen the region.

If width or height is 0 (create-template): set both to the size of the region, greater than 0.

A file could not be written - usually a permission problem or a full disk.

The configuration directory is not writable. The same problem is reported in the log at startup.

If the configuration directory is not writable: make it writable for the application.

If the disk is full: free disk space on the device.

The template was cut from the wrong region or the wrong image, see Problem: The template is not found even in the image it was cut from.

The part is rotated or at another distance than in the template, see Problem: The part is not found when it is rotated or at a different distance.

input/crop excludes the part.

The template touches the edge of the image. Such a template cannot be found near the opposite edge, because the template must fit entirely inside the searched image.

Background that changes from part to part is inside the template; it lowers every score.

If the template is not found in its own image: follow Problem: The template is not found even in the image it was cut from.

If the part is rotated or at another distance: follow Problem: The part is not found when it is rotated or at a different distance.

If the crop excludes the part: widen the region, or set all four input/crop/ values to 0.

If the template touches the image border or holds changing background: create the template again from a region that stays away from the image border, includes what identifies the part and excludes what varies. See Creating a Template.

If the part was not in the image: the result is correct; nothing needs to be changed.

The region given when the template was created is wrong.

The image address is wrong: the template was cut from another image than the one searched. system/create-template/input/input-image-address and <module>/find-template/input/input-image-address are separate nodes.

Correct input/input-image-address and the crop region, then create the template again. Searched in the same image, it must be found exactly at the centre of the region you specified - (195, 250) for a region starting at (100, 200) that is 190 x 100 pixels - with a confidence close to 1.

The defaults search the template at its original size and orientation only.

If the part rotates: set input/rotation/max-rot (for example 360) with a coarse input/rotation/step-rot (for example 5).

If the part changes distance: set input/scale/min-scale, input/scale/max-scale and input/scale/step-scale (for example 0.9, 1.1, 0.05).

The confidence is not an absolute measure. The score map is rescaled for every scale/rotation step, so the best location of every step reaches a confidence near 1, and input/match-thresh acts per step. Only repeats at the same location are removed, so a weak match somewhere else can still appear.

Raise input/match-thresh, for example to 0.95, or narrow the scale and rotation range.

The next run has started. Every run clears its own outputs as soon as it begins, before anything that can fail. Triggering execute again and then reading gives the new run - possibly failed or still empty - not the previous one.

A call refused with -1 (busy) clears nothing, so this is not the cause when the second call was refused.

If the next run started too early: wait for execute to return, read the outputs, and only then trigger the next run.

If the latest run failed: follow the entry for its status code.

The file arrived by other means - an upload through the ctrlX web interface on ctrlX OS, or a file copied into the folder on a PC - and the list was not refreshed. The list is refreshed at startup, when system/set-template-dir succeeds and when system/create-template saves a template.

The extension is not a lower case .png. SCREW.PNG is ignored.

The file is in a different folder from the one in use.

If the extension is not a lower case .png: rename the file to a lower case .png.

If the list was not refreshed: execute system/set-template-dir again, naming the same folder. Expected: its status code is 1, and system/templates lists the template.

Only the inputs were written. Writing control/subscribe/input/enable alone starts nothing; control/subscribe/execute applies the inputs.

control/subscribe/execute was refused (Rejected, ctrlX: DL_INVALID_VALUE): stream mode without an address, or a queue size outside 1 to 64.

The settings file <module-id>.json could not be written, for example because it is not valid JSON (CreationFailed, ctrlX: DL_CREATION_FAILED). Nothing changed.

The stream of the Cam Driver does not run, so no frames arrive.

The source cannot be subscribed to. The module tries it again every 5 seconds while the stream runs, and logs the first failure.

Frames cannot be searched, for the reasons find-template gives in its status-text.

If only the inputs were written: set control/subscribe/input/enable to true and write to control/subscribe/execute. Wait until control/subscribe/output/stream/active is true.

If the call was refused (Rejected, DL_INVALID_VALUE): write the camera’s stream folder to control/subscribe/input/address, set control/subscribe/input/queue-size to a value from 1 to 64, and write to control/subscribe/execute again.

If the settings file could not be written (CreationFailed, DL_CREATION_FAILED): make <module-id>.json in the configuration directory valid JSON again, without comments, then write to control/subscribe/execute again.

If the stream of the Cam Driver does not run: start it. It is not kept after a restart: call its control/publish/execute with enable = true after every start, and connect the camera first. See A stream delivers nothing.

If the source cannot be subscribed to: check that control/subscribe/input/address is the camera’s stream folder and that the Cam Driver runs on the same device.

If frames fail: correct the input that last-failure names, as for a single find-template call.

The module list was not saved. Settings and new modules are live at once but not permanent until saved; the module list and each module’s settings are saved separately.

The module’s settings were not saved.

A save failed: system/save-module-inputs or system/save-current-modules did not report status 1.

<module-id>.json contains comments. The stream reads such a file, but the module’s inputs are then not restored at start; the log reports the file as unreadable.

A setting whose node no longer exists after a software update is skipped, with a log entry.

If the settings or the module list were not saved:

If the module file contains comments: remove them from <module-id>.json. Changes made to the file by hand take effect at the next start.

If a setting was skipped after an update: set the input again and save the module’s settings.

The licence is missing. The reason is written to the system log.

The application needs more licences than are installed. One licence covers ten modules, see Problem: Status code -11 (licence unavailable).

If the licence is missing: install a valid licence on the device and start the application again. Expected: it keeps running, and its nodes are on the Data Layer.

No licence on the device covers the module. One licence covers ten modules; the eleventh module acquires a second licence of the same key.

If more modules exist than the licences cover: remove the modules you do not need with system/remove-module and save the module list with system/save-current-modules, or obtain another licence.