Your First Industrial Vision Application

You end with a working cell: a camera takes an image, LumiScan Template Finder finds your part in it, Cockpit shows image and result, and your PLC triggers the search and reads the position. Eight steps; each one ends with Done when and points to the next.

The same steps work on ctrlX OS (ctrlX CORE or ctrlX IPC) and on a PC with Windows 11 or Ubuntu 24.04 - where they differ, both are given. Template Finder stands for any processing app: a code reader, the Text Reader or the Area Detector are set up the same way with their own nodes.

Your progress - tick off each step as you finish it

Step 1 of 8 - Choose platform and components

1 Plan · 2 Install · 3 Camera · 4 Image · 5 Cockpit · 6 Teach · 7 Find · 8 PLC

ctrlX OS PC

Device

ctrlX CORE or ctrlX IPC

Windows 11 or Ubuntu 24.04

Apps

LumiScan Cam Driver, LumiScan Template Finder, LumiScan Cockpit

LumiScan Keryx, the same three apps, the OPC UA Connector for the PLC

Camera

an Ethernet-enabled, GenICam-compliant camera - see the Cam Driver requirements - and its power supply (PoE or external)

Controller

ctrlX PLC on the same device

a PLC with an OPC UA client

The platform overview explains the differences: Two platforms for the vision apps.

Done when: you know your device, your camera and how your PLC will connect.
Next: Step 2 - Install the apps and licences

Step 2 of 8 - Install the apps and licences

1 Plan ✓ · 2 Install · 3 Camera · 4 Image · 5 Cockpit · 6 Teach · 7 Find · 8 PLC

On ctrlX OS: install Cam Driver, Template Finder and Cockpit as ctrlX apps, and their ctrlX licences in the License Manager of ctrlX OS. Without a licence an app shuts down shortly after starting and writes the reason to the system log.

On a PC:

  1. Install LumiScan Keryx first, then the three apps, each installer as administrator.

  2. Install CodeMeter Runtime and plug in the LumiScan Key - or, for apps bought in the ctrlX Store, the licence in ctrlX WORKS plus the LumiScan Key.

  3. Open a new terminal before starting an app from the command line.

Which licence applies where: Which Licensing Path Applies. Details on Keryx: Installing on Windows.

Done when: the apps are installed and licensed (on ctrlX OS they appear among the running apps).
Next: Step 3 - Connect and configure the camera

Step 3 of 8 - Connect and configure the camera

1 Plan ✓ · 2 Install ✓ · 3 Camera · 4 Image · 5 Cockpit · 6 Teach · 7 Find · 8 PLC

  1. Connect the camera to the Ethernet port of the device and power it. It must be in the same local network as the ctrlX CORE or the PC. To set its IP address from the Cam Driver, see Setup Camera IP Address.

  2. Make a camera settings file: copy the example camera_example.json that comes with the Cam Driver, for example as camera1.json, and set

      "id": "camera1",
  "serial": "<serial number of your camera>",

  3. List the file under modules in lumiscan-cam-driver.json.

  4. Where the files are edited:

    • ctrlX OS: ctrlX OS website → Home → Manage app data → File View → the Cam Driver folder.

    • PC: the Cam Driver’s settings folder in a text editor; restart the Cam Driver after saving.

See Setup Camera Configuration for all settings.

No camera at hand yet? A serial number that contains simulation gives you a simulated camera, so you can go through all the remaining steps first.

Done when: after the Cam Driver has read its settings, the module camera1 appears on the Data Layer under hdvisionsystems/lumiscan-cam-driver/camera1/.
Next: Step 4 - Take the first image

Step 4 of 8 - Take the first image

1 Plan ✓ · 2 Install ✓ · 3 Camera ✓ · 4 Image · 5 Cockpit · 6 Teach · 7 Find · 8 PLC

You work directly on the Data Layer nodes. Open the node browser: on ctrlX OS the Data Layer view of the ctrlX OS web interface, on a PC the Keryx page http://127.0.0.1:7555/ (a writable node has an editor, a method an Invoke button). See Tools.

  1. Connect the camera - a handshake, because it can take several seconds:

    1. wait until hdvisionsystems/lumiscan-cam-driver/camera1/control/connect-camera/ready is true,

    2. set …​/connect-camera/request to true, wait until ready turns false,

    3. set request back to false,

    4. check hdvisionsystems/lumiscan-cam-driver/camera1/device-info/is-connected = true.

  2. Capture - one call: invoke hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute, then check that hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code is 0.

The image is now on hdvisionsystems/lumiscan-cam-driver/camera1/output/image. The whole sequence and its status codes: Connection Steps.

Done when: capture succeeded and output/image holds an image.
Next: Step 5 - Look at it in Cockpit

Step 5 of 8 - Look at it in Cockpit

1 Plan ✓ · 2 Install ✓ · 3 Camera ✓ · 4 Image ✓ · 5 Cockpit · 6 Teach · 7 Find · 8 PLC

  • ctrlX OS: in the ctrlX web interface click LumiScan Cockpit in the sidebar.

  • PC: start lumiscan-cockpit; its window opens.

The application overview lists the running apps and their views. Open the Cam Driver’s view: it shows the image you captured. Use it now to position the part and to read off pixel coordinates for the next step. See Opening the Cockpit.

Done when: you see the camera image in Cockpit.
Next: Step 6 - Teach the part

Step 6 of 8 - Teach the part

1 Plan ✓ · 2 Install ✓ · 3 Camera ✓ · 4 Image ✓ · 5 Cockpit ✓ · 6 Teach · 7 Find · 8 PLC

Point Template Finder at the camera image and cut a template - a small picture of the part - from it:

hdvisionsystems/lumiscan-template-finder/system/create-template/input/input-image-address  = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
hdvisionsystems/lumiscan-template-finder/module-1/find-template/input/input-image-address  = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
hdvisionsystems/lumiscan-template-finder/system/create-template/input/crop/startX          = 100
hdvisionsystems/lumiscan-template-finder/system/create-template/input/crop/startY          = 200
hdvisionsystems/lumiscan-template-finder/system/create-template/input/crop/width           = 190
hdvisionsystems/lumiscan-template-finder/system/create-template/input/crop/height          = 100
hdvisionsystems/lumiscan-template-finder/system/create-template/input/template-name        = screw

Use the region around your part instead of the example values, then invoke hdvisionsystems/lumiscan-template-finder/system/create-template/execute.

Done when: hdvisionsystems/lumiscan-template-finder/system/create-template/output/status-code is 1.
Next: Step 7 - Find the part and keep the settings

Step 7 of 8 - Find the part and keep the settings

1 Plan ✓ · 2 Install ✓ · 3 Camera ✓ · 4 Image ✓ · 5 Cockpit ✓ · 6 Teach ✓ · 7 Find · 8 PLC

  1. Set hdvisionsystems/lumiscan-template-finder/module-1/find-template/input/template-name = screw and invoke hdvisionsystems/lumiscan-template-finder/module-1/find-template/execute.

  2. Read hdvisionsystems/lumiscan-template-finder/module-1/find-template/output/result: on the image you cut the template from you get one match, centred in your region, with a confidence close to 1.

  3. Capture a new image with the part moved (step 4) and search again: the match follows the part. If it does not, widen rotation or scale as in How To: Match a Part from a Camera Image.

  4. Make the settings permanent: set hdvisionsystems/lumiscan-template-finder/system/save-module-inputs/input/module-id = module-1 and invoke hdvisionsystems/lumiscan-template-finder/system/save-module-inputs/execute.

Done when: the part is found reliably in new images, and the settings survive a restart.
Next: Step 8 - Trigger it from your PLC

Step 8 of 8 - Trigger it from your PLC

1 Plan ✓ · 2 Install ✓ · 3 Camera ✓ · 4 Image ✓ · 5 Cockpit ✓ · 6 Teach ✓ · 7 Find ✓ · 8 PLC

In production one cycle is three calls, made by the PLC instead of by you:

  1. call hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute and check hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code = 0,

  2. call hdvisionsystems/lumiscan-template-finder/module-1/find-template/execute,

  3. read hdvisionsystems/lumiscan-template-finder/module-1/find-template/output/status-code (negative = the search failed) and the result.

How the PLC reaches the nodes:

  • ctrlX PLC: it reads, writes and calls the nodes directly on the same device. Use the plain nodes (numbers, booleans, strings) for the PLC logic. See Connecting a PLC.

  • PLC with OPC UA (PC): start the OPC UA Connector after the apps. Each node is an OPC UA node at opc.tcp://<pc>:4840, its NodeId is the Data Layer address; an execute node is an OPC UA method, called with the Call service. See OPC UA Connector.

Done when: the PLC triggers a capture and a search and reads the result - your first LumiScan vision application runs.

What next