---
title: "Your First Industrial Vision Application"
description: "Build a complete vision application step by step: camera, Cam Driver, Template Finder and Cockpit on ctrlX OS or a PC, a part found in a camera image, and the result read by your PLC."
product: "LumiScan Documentation"
component: "ROOT"
language: "en"
url: "https://docs.hdvisionsystems.com/en/getting-started/first-application.html"
---

# Your First Industrial Vision Application – LumiScan Documentation

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**

- [1. Choose platform and components](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-1)
- [2. Install the apps and licences](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-2)
- [3. Connect and configure the camera](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-3)
- [4. Take the first image](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-4)
- [5. Look at it in Cockpit](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-5)
- [6. Teach the part](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-6)
- [7. Find the part and keep the settings](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-7)
- [8. Trigger it from your PLC](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-8)

## Step 1 of 8 - Choose platform and components {#step-1}

|   | 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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html) - 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](https://docs.hdvisionsystems.com/en/getting-started/platform-overview.html#platforms).

**Done when:** you know your device, your camera and how your PLC will connect.\
**Next:** [Step 2 - Install the apps and licences](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-2)

## Step 2 of 8 - Install the apps and licences {#step-2}

**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](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/which-licensing-path.html). Details on Keryx: [Installing on Windows](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html#installing).

**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](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-3)

## Step 3 of 8 - Connect and configure the camera {#step-3}

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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/setup-camera-ip-address.html).
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
   ```json
     "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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/setup-camera-configuration.html) for all settings.

> [!TIP]
> 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](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-4)

## Step 4 of 8 - Take the first image {#step-4}

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](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/tools.html).

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

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

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

   c. set `request` back to `false`,

   d. 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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#connection-steps).

**Done when:** `capture` succeeded and `output/image` holds an image.\
**Next:** [Step 5 - Look at it in Cockpit](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-5)

## Step 5 of 8 - Look at it in Cockpit {#step-5}

- **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](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html).

**Done when:** you see the camera image in Cockpit.\
**Next:** [Step 6 - Teach the part](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-6)

## Step 6 of 8 - Teach the part {#step-6}

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](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-7)

## Step 7 of 8 - Find the part and keep the settings {#step-7}

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](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/how-tos/match-a-part-from-a-camera-image.html).
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](https://docs.hdvisionsystems.com/en/getting-started/first-application.html#step-8)

## Step 8 of 8 - Trigger it from your PLC {#step-8}

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](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html#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](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/opc-ua.html).

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

## What next

- Every image searched automatically, without a call per image: [Processing an Image Stream](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).
- Results in robot coordinates: [LumiScan Calibration](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/index.html).
- All call patterns and status codes: [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/index.html).