Template Storage

Templates are ordinary PNG files kept in the application’s configuration directory. You can inspect, copy and back them up with normal tools, and a template prepared elsewhere can simply be uploaded (ctrlX OS) or copied in (PC).

Where they are

The configuration directory, and a templates folder inside it, are created when the application first starts, so there is somewhere to upload or copy to on a brand-new installation. Where it is depends on the platform.

On ctrlX OS

On a ctrlX device the configuration directory is part of the active solution:

/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-template-finder

Because it belongs to the solution, templates are included when the solution is exported and are restored with it on another device.

On a PC

On Windows the configuration directory is %APP_RESOURCE_DIR%\etc\lumiscan-template-finder; without APP_RESOURCE_DIR, C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-templ-find\etc\lumiscan-template-finder.

Layout

<configuration directory>/
├── lumiscan-template-finder.json   module list, chosen template folder, log level
├── module-1.json                   saved settings of one module
└── templates/                      default template folder
    ├── screw.png
    └── bracket.png

One folder serves the whole application, not one per module: every module searches it, and create-template writes into it, so a template created by one module is immediately usable by all of them.

module-1.json is written by system/save-module-inputs - see Module Management.

Log level

lumiscan-template-finder.json also carries how much the application logs, in the same system block the other LumiScan applications use:

{
    "system": {
        "logLevel": "TRACE"
    }
}

TRACE, DEBUG, INFO, WARN, ERROR, FATAL and OFF are accepted, from most detail to none. TRACE is what to set before reproducing a problem for a support report.

The level is read once, at startup, so restart the application after changing it. Add the block by hand: the application only ever writes template-dir and modules to this file, and leaves everything else in it alone.

The key is optional. Without it the application logs at its built-in DEBUG level, and a value that is not one of the names above is reported in the log and changes nothing - a typo here can never silence the application.

Choosing the folder

system/template-dir                          read-only, the folder in use
system/templates                             read-only, what is in it
system/set-template-dir/execute              change it
system/set-template-dir/input/template-dir   the folder to change to

template-dir and templates are read-only outputs of set-template-dir, so the listing can never disagree with the folder it came from. To change folder, write set-template-dir/input/template-dir, then execute the method, then check set-template-dir/output/status-code is 1.

The folder must already exist. It is not created for you: the default templates is created at startup, so a missing folder means the name is wrong, and quietly creating an empty one would hide the mistake. The choice is saved and restored on the next start.

If the call is rejected nothing changes - the application keeps using the folder it had.

system/templates

Every template in the folder, without the .png extension, sorted:

["bracket", "screw"]

An entry can be pasted straight into find-template/input/template-name. The list is refreshed at startup, when set-template-dir succeeds, and when create-template saves a new template.

It is not refreshed when a file arrives by other means, such as an upload through the ctrlX web interface (ctrlX OS) or a file copied into the folder (PC). Execute set-template-dir again, naming the same folder, to pick such a file up.

Only files ending in a lower case .png are listed. SCREW.PNG is ignored.

Getting templates onto the device

From a live image: Creating a Template writes the file directly. No file transfer needed.
Through the ctrlX web interface (ctrlX OS): The application’s data folder is browsable, so a prepared PNG can be uploaded into templates.
With the solution (ctrlX OS): Templates stored in the active solution’s configuration travel with it to another device.
By copying (PC): A prepared PNG can be copied into templates in the configuration directory.

A template added while the application is running is picked up on the next search - the file is read each time, not cached at startup, so there is no need to restart.

File format

PNG, 8-bit RGB. Created templates are always written this way, whatever the camera’s pixel format.
A grayscale PNG works too.
.png is added when the name has no extension, so screw and screw.png mean the same file.

Path rules

Folder and file names are always interpreted relative to the configuration directory. Two things are rejected with status code -2:

an absolute path, such as /tmp/templates
a path that leads outside the configuration directory, such as ../../etc

This means the application can only ever read and write inside its own configuration directory. A path that stays inside is fine even if it contains ...

Troubleshooting

Problems with the template folder and the template files are described step by step in Troubleshooting:

Status code -4 (source not found) - naming a directory or a file, or a file that is there but is not found
Status code -2 (invalid input) - an absolute path, or one pointing outside the configuration directory
Status code -6 (write failed)
The template file is on the device but missing from system/templates

Starting from an Example (PC)

On a PC, the Template Finder writes an example of its settings into a folder of your choice, and ends without starting. For example, on Windows:

lumiscan-templ-find --generate-settings C:\work\template-finder-settings

Without a folder (-g alone) it writes into the current folder. The example is the application settings file lumiscan-template-finder.json, which names the module module-1, and the module file module-1.json beside it: every input of find-template with the value it has by default, except the image address, which is the Cam Driver’s camera1. Beside them, in schemas/, are the schemas the two files name in "$schema": lumiscan-template-finder.schema.json, lumiscan-template-finder-module.schema.json, and stream.schema.json for the stream section of a module file. They describe every key the Template Finder reads - each input of find-template with its type, its default and the range a run accepts - so an editor that understands JSON Schema can check the files and show what each value means. Copy the schemas folder along with the files: system/save-module-inputs keeps the "$schema" of a module file it saves. Existing files are never overwritten: when one of them is in the folder already, nothing is written and the Template Finder says which.

The Template Finder then names the folder it reads its settings from - on Windows by default C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-templ-find\etc\lumiscan-template-finder. Edit the example, copy it there, and start the Template Finder. See also Where the files are (Windows).