How To: Test with Example Images Instead of a Camera

A simulated camera is a camera module of LumiScan Cam Driver that does not talk to a camera. Each capture loads the next image from a folder instead. To the other LumiScan applications it looks exactly like a real camera: the image appears on the same Data Layer nodes.

Use it to set up and test an evaluation - a code reader, LumiScan Template Finder, LumiScan AI Object Matching - with known example images, before the camera is installed or without stopping the line.

When you have finished, a module named simulation delivers your example images, one per capture, on hdvisionsystems/lumiscan-cam-driver/simulation/output/image.

Before you start

LumiScan Cam Driver installed on the ctrlX CORE, with a licence, see Requirements
Example images as PNG files, ideally taken with the camera and lighting that will be used later
A browser with access to the ctrlX web interface

How it fits together

Whether a camera module is simulated depends on its serial: a serial that contains simulation makes the module play images from the storage folder rather than search for a camera. The id is free.

The images are taken from the storage folder configured in lumiscan-cam-driver.json, in a sub-folder named after the module’s id: images/simulation for the settings in this guide. When the camera is connected, the module scans this folder; each capture then loads the next image.

Since v2.0.0, the images are taken from the sub-folder <id>, not from the storage folder itself. If unifiedStorage is set to true in the system settings (from v2.2.0), the storage folder itself is used.

Step 1 - Create the module file

In the ctrlX web interface, go to Home > Manage app data and click Open file view.

Figure 1. Manage app data with the Open file view button
Open the folder lumiscan-cam-driver.
Create the file simulation.json, for example as a copy of the example module file, with these values:
```
{
  "id": "simulation",
  "serial": "simulation"
}
```
Keep the $schema and meta entries of the example file.

Figure 2. Module file of a simulated camera: the serial contains simulation
Open lumiscan-cam-driver.json and add simulation.json to the modules list:
```
"modules": [
  "simulation.json"
]
```
Check that system holds a storage, for example the internal storage:
```
"storage": {
  "type": "Internal",
  "parameters": {
    "rootPath": "images"
  }
}
```
See Storage settings.

Step 2 - Upload the example images

In the file view of lumiscan-cam-driver, open the storage folder, images for the settings above.
Create a sub-folder named exactly like the module’s id: simulation.
Upload the example images into this folder.

The first capture loads the first image of the folder. For larger amounts of images, upload them with WebDAV, see Uploading Data.

Step 3 - Restart LumiScan Cam Driver

Under Settings > Apps, select LumiScan Cam Driver and click Restart. The application reads its settings files only at start.

Expected: under hdvisionsystems/lumiscan-cam-driver, a folder simulation exists.

Step 4 - Connect and capture

Values on the Data Layer can be set in the ctrlX web interface under Settings > Data Layer, or by another application, for example a PLC program.

Connect the simulated camera with the handshake on hdvisionsystems/lumiscan-cam-driver/simulation/control/connect-camera: wait until ready is true, set request to true, wait until ready is false, set request to false.
Check that simulation/device-info/is-connected is true.
Write to hdvisionsystems/lumiscan-cam-driver/simulation/control/capture/execute.

Expected: simulation/control/status/code is 0, and the first example image is on hdvisionsystems/lumiscan-cam-driver/simulation/output/image. Each further capture loads the next image.

To see which image is loaded, open LumiScan Cockpit. It shows the image of the module simulation like that of a real camera.

Step 5 - Use the images in another application

Point the image address of the evaluating application at the simulated camera:

hdvisionsystems/lumiscan-cam-driver/simulation/output/image

For LumiScan DMC Reader, for example, this is input/image-address; for LumiScan AI Object Matching, externalImagePath in the module file. To change to the real camera later, change only this address, or replace the module’s serial with that of the camera.

Result

LumiScan Cam Driver has a simulated camera, simulation.
Each capture loads the next example image onto hdvisionsystems/lumiscan-cam-driver/simulation/output/image.
Other LumiScan applications can be set up and tested with these images, without camera hardware.

More on simulation mode: FAQ: How does simulation mode work? and Loading Images.