---
title: "How To: Match a Part from a Camera Image"
product: "LumiScan Template Finder"
component: "lumiscan-template-finder"
version: "1.1.0"
display_version: "1.1.0.7"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/how-tos/match-a-part-from-a-camera-image.html"
---

# How To: Match a Part from a Camera Image – LumiScan Template Finder

End-to-end walkthrough, from a running camera to a match result, using the module the application creates for you on installation.

## Before you start

- LumiScan Cam Driver, or another image source, is running on the same device - the same ctrlX CORE or ctrlX IPC, or the same PC - and has captured an image.
- You know the address of its image node. For camera 1 of the cam driver:
  ```
  hdvisionsystems/lumiscan-cam-driver/camera1/output/image
  ```

Throughout, paths are relative to the application:

```
hdvisionsystems/lumiscan-template-finder/
```

Creating a template is an operation of the whole application, under `system/`; the search belongs to the module `module-1`.

## Step 1 - Point both operations at the camera

Set the image address on both operations:

```
system/create-template/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
module-1/find-template/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
```

They are separate nodes on purpose - a template can be cut from one camera and searched for in another.

## Step 2 - Capture an image with the part in view

Trigger a capture in the camera application, with the part positioned as it will be in production. The template is cut from this image, so its lighting and working distance become the reference.

## Step 3 - Cut the template

Find the pixel coordinates of a region containing the part. The camera application’s image preview is the easiest way to read them off.

Then:

```
system/create-template/input/crop/startX    = 100
system/create-template/input/crop/startY    = 200
system/create-template/input/crop/width     = 190
system/create-template/input/crop/height    = 100
system/create-template/input/template-name = screw
```

Write to `system/create-template/execute`, then read `system/create-template/output/status-code`.

`1` means it worked, and `system/create-template/output/template-path` now reads `templates/screw.png`.

If you get `-5`, the region does not fit the image; `output/status-text` names the actual image size.

## Step 4 - Verify against the same image

Before changing anything, search the image you just cut from:

```
module-1/find-template/input/template-name = screw
```

Write to `module-1/find-template/execute` and read `module-1/find-template/output/result`.

You should get exactly one match, its `oriented_bounding_box` centred at the middle of the region you specified - (195, 250) for the values above - with a confidence close to 1.

> [!TIP]
> This check is worth the half minute it takes. If the template is not found in the very image it came from, the problem is the region or the image address, and no amount of parameter tuning will fix it.

## Step 5 - Search a real image

Capture a new image with the part in a different position and search again. The match should follow the part.

If nothing is found, the part has probably changed size or orientation relative to the template. Go to step 6.

## Step 6 - Widen the search, if needed

Only if step 5 failed:

**The part rotates.** Set a rotation range with a coarse step:

```
module-1/find-template/input/rotation/max-rot  = 360
module-1/find-template/input/rotation/step-rot = 5
```

**The part changes distance.** Set a scale range:

```
module-1/find-template/input/scale/min-scale  = 0.9
module-1/find-template/input/scale/max-scale  = 1.1
module-1/find-template/input/scale/step-scale = 0.05
```

Each combination is a separate pass over the image, so both settings together are 72 x 5 = 360 passes. Widen one at a time and stop as soon as the part is found reliably.

If widening the range starts producing matches in the wrong places, raise the threshold:

```
module-1/find-template/input/match-thresh = 0.95
```

The reason is explained in [Tuning the Search](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/tuning-the-search.html).

## Step 7 - Keep the settings

The settings are live but not yet permanent. To have them restored after a restart:

```
system/save-module-inputs/input/module-id = module-1
```

Write to `system/save-module-inputs/execute`.

The template file itself is already permanent - it is a file in the application’s configuration directory, which on ctrlX OS is part of the active solution.

## In production

A cycle is now a single write to `module-1/find-template/execute`, followed by:

1. read `module-1/find-template/output/status-code` - negative means the search failed
2. read `module-1/find-template/output/result` - `best_score` and `matches[0]` give the best match

Nothing else needs to be set between cycles. To have every frame of the camera searched without a call per image, see [Finding Templates on an Image Stream (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).