---
title: "How To: Mark Positions on Camera Images with Overlays"
description: "Show a camera image from LumiScan Cam Driver in LumiScan Cockpit and draw fixed markers on it - a centre cross, a region of interest, alignment circles."
product: "LumiScan Cockpit"
component: "lumiscan-cockpit"
version: "1.2.0"
display_version: "1.2.0.8"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/how-tos/mark-image-positions-with-overlays.html"
---

# How To: Mark Positions on Camera Images with Overlays – LumiScan Cockpit

This guide shows a camera image from LumiScan Cam Driver in LumiScan Cockpit and draws fixed markers on it: a cross at the image centre, and optionally circles and rectangles. Such overlays help to align a camera, to check a part against a region of interest, or to show an operator where a part has to be.

When you have finished, every image of the camera is shown in Cockpit with your markers on top.

## Before you start {#prerequisites}

- LumiScan Cockpit and LumiScan Cam Driver are installed and running on the same ctrlX CORE.
- The camera is connected and has captured at least one image. If not, see the LumiScan Cam Driver manual.
- You can open the ctrlX web interface in a browser on your PC.
- Basic knowledge of JSON.

## How it fits together {#overview}

Cockpit shows the images that other LumiScan applications put on the ctrlX Data Layer. It produces no images of its own. For LumiScan Cam Driver, it lists every camera module found under `hdvisionsystems/lumiscan-cam-driver`.

Overlays are not part of the image. They are defined in Cockpit’s settings file, `lumiscan-cockpit.json`, under `overlay`, keyed by `<application>/<image name>`, and Cockpit draws them on every image with that key. The file is read when Cockpit starts, so a changed overlay appears after a restart. All properties are described in [Overlays](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/overlays.html).

## Step 1 - Check that the camera delivers images {#step-1-check-camera}

1. Open the ctrlX web interface.
2. Under **Settings > Apps**, check that LumiScan Cam Driver is running.
3. Capture an image with the camera, as described in the LumiScan Cam Driver manual.

## Step 2 - Open the image in Cockpit {#step-2-open-cockpit}

1. Click **LumiScan Cockpit** in the sidebar of the ctrlX web interface.

   The application overview lists the available images, grouped by the application that publishes them. For LumiScan Cam Driver, each camera module is one entry, named after the module.

   ![LumiScan Cockpit overview with the entries lumiscan-cam-driver camera 1 and lumiscan-ai-object-matching example](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/howto-overlays-overview.png)

   *Figure 1. Application overview of LumiScan Cockpit*

2. Click the name of the image. It opens in a new browser tab.

Note the two names: the application (`lumiscan-cam-driver`) and the image (in the example `camera 1`). Together they form the key of the overlay.

## Step 3 - Open Cockpit’s settings file {#step-3-open-settings}

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

2. Open the folder `lumiscan-cockpit`.

3. Click `lumiscan-cockpit.json`. The file opens in the editor on the right.

   The editor checks the file against its schema and marks errors.

   ![File view of the folder lumiscan-cockpit with lumiscan-cockpit.json opened in the editor](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/howto-overlays-settings-file.png)

   *Figure 2. Cockpit’s settings file in the file view of the ctrlX web interface*

## Step 4 - Add an overlay {#step-4-add-overlay}

Add an entry under `overlay` for your image, with one element per shape. This example draws a green cross, 30 pixels wide, at the centre of the image:

```json
{
  "$schema": "schemas/lumiscan-cockpit.schema.json",
  "overlay": {
    "lumiscan-cam-driver/camera 1": [
      {
        "color": "green",
        "shape": "cross",
        "centerX": 0.5,
        "centerY": 0.5,
        "width": 30,
        "height": 30
      }
    ]
  }
}
```

Each element has these properties:

- **`color`:** A named colour (`red`, `green`, `blue`, `black`, `white`, `yellow`, `cyan`, `magenta`) or six hex digits, `#RRGGBB`. A colour that cannot be read is drawn white.
- **`shape`:** `rectangle`, `circle` or `cross`.
- **`centerX`, `centerY`:** The centre of the shape.
- **`width`, `height`:** The size of the shape. For a circle, `width` is the diameter.

Position and size follow one rule: values **below** `1.0` are relative to the image (`0.5` is the middle), values of `1.0` and above are pixels. So the cross above sits in the middle of every image, whatever the resolution, and is 30 pixels wide.

To draw on several images at once, use `*` in the key:

- `lumiscan-cam-driver/*` - every image of LumiScan Cam Driver
- `*/resultImage` - the image named `resultImage` of every application
- `/` - every image

An image that matches several keys shows all of their overlays.

## Step 5 - Save and restart Cockpit {#step-5-save-restart}

1. Check that the editor marks no errors, then click **Save**.
2. Under **Settings > Apps**, select **LumiScan Cockpit** and click **Restart**.
3. Open the image in Cockpit again, as in step 2.

Expected: the image shows a green cross at its centre.

![Camera image of a ring-shaped part in LumiScan Cockpit with a small green cross at the image centre](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/howto-overlays-cross.jpg)

*Figure 3. Camera image in Cockpit with a green cross at the centre*

## Example: several overlays on all camera images {#example-several-overlays}

This configuration draws, on every image of LumiScan Cam Driver, a centre cross, three concentric circles as a target for alignment, and two rectangles marking regions of interest. The circles use `height` `0`, since only the width (the diameter) is used. The rectangles use pixel coordinates.

```json
{
  "$schema": "schemas/lumiscan-cockpit.schema.json",
  "overlay": {
    "lumiscan-cam-driver/*": [
      { "color": "green", "shape": "cross", "centerX": 0.5, "centerY": 0.5, "width": 30, "height": 30 },
      { "color": "red", "shape": "circle", "centerX": 0.5, "centerY": 0.5, "width": 100, "height": 0 },
      { "color": "yellow", "shape": "circle", "centerX": 0.5, "centerY": 0.5, "width": 150, "height": 0 },
      { "color": "green", "shape": "circle", "centerX": 0.5, "centerY": 0.5, "width": 200, "height": 0 },
      { "color": "#c8b100", "shape": "rectangle", "centerX": 400, "centerY": 400, "width": 250, "height": 200 },
      { "color": "#c8b100", "shape": "rectangle", "centerX": 400, "centerY": 800, "width": 250, "height": 200 }
    ]
  }
}
```

![Camera image in LumiScan Cockpit with a centre cross](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/howto-overlays-multiple.jpg)

*Figure 4. Camera image with several overlays*

## Result {#result}

- LumiScan Cockpit shows the images of LumiScan Cam Driver with your overlays.
- The markers stay at the configured position on every new image.
- To change them, edit `lumiscan-cockpit.json` and restart Cockpit.

> [!WARNING]
> `1.0` is not the far edge of the image but one pixel. To place a shape relatively near the right or bottom edge, use a value just below `1.0`, for example `0.99`.

If an overlay does not appear, check the key against the names in the application overview, and see [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html).