# LumiScan Cockpit 1.2.0.8 – complete documentation

> All pages of the LumiScan Cockpit 1.2.0.8 manual (language: en) by HD Vision Systems GmbH, in navigation order. Each page starts with a level-1 heading followed by its URL; cite that URL. Manual: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/

# Description – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/description.html

LumiScan Cockpit shows what the vision applications on a ctrlX CORE or ctrlX IPC, or on a PC, are looking at and what they found in it: on ctrlX OS in an ordinary web browser, on a PC in a window of its own. It is a viewer: it draws the pictures and the results other applications publish, and configures nothing about them.

A view follows the application it is showing. When the picture behind it changes, the browser is told and fetches the new frame, so what is on screen is what the station just did rather than a snapshot from up to two seconds ago. While a camera streams, its view is live: it shows the frames as they arrive. See [Live Updates](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html).

## Data Layer {#data-layer}

LumiScan Cockpit has no nodes of its own: it reads the nodes of the other apps.

On ctrlX OS (ctrlX CORE or ctrlX IPC), LumiScan Cockpit uses the [ctrlX Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html).

On a PC with Windows 11 or Ubuntu 24.04, LumiScan Cockpit uses [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html).

The node addresses, types and call patterns are the same on both.

How addresses are built, how to call functions, the status codes and the tools are described in [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/index.html).

Cockpit reads everything it displays from the Data Layer - the ctrlX Data Layer on ctrlX OS, LumiScan Keryx on a PC: the image nodes of the publishing applications, and the result nodes of the ones whose findings it draws.

What is the same for every LumiScan app - how addresses are built, the handshake, execute and stream call patterns, status codes, settings and tools - is described in the [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/index.html) manual. This manual covers only what is specific to LumiScan Cockpit; the pages of this manual describe its own nodes.

> [!NOTE]
> Cockpit provides **no Data Layer output of its own**. Nothing else on the system can consume what it draws — the drawing exists only in the browser or in Cockpit’s window. To act on a result programmatically, read that application’s own result nodes.

## What it shows

Two applications publish images of their own, and Cockpit shows those images as they are:

- LumiScan Cam Driver (`lumiscan-cam-driver`)
- LumiScan AI Object Matching (`lumiscan-ai-object-matching`)

Eight further applications publish no image of their own — each reads one from another application — and Cockpit draws their findings, in green, on the image they were found in. Those eight are listed in [Viewing Results](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html). AI Object Matching’s boxes are drawn on a camera’s live frames too, while it infers on the camera’s stream.

LumiScan Calibration produces coordinates rather than an image, and is not shown.

The home page is an overview of every compatible application currently running on the system, so it also answers which of them are up before you open any single view.

# Requirements – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/requirements.html

## Licence {#licence}

How LumiScan Cockpit is licensed depends on where you bought it and where it runs:

| Bought from | Runs on | Licensing |
| --- | --- | --- |
| HD Vision Systems | Windows 11 or Ubuntu 24.04 | The licence is held on your LumiScan Key. It is a one-time purchase and needs no renewal.<br><br>[Licensing path: bought from HD Vision Systems](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/path-hdvs.html) |
| ctrlX Store | Windows 11 | The licence is held in ctrlX WORKS. The LumiScan Key is required in addition; it protects the software against reverse engineering.<br><br>[Licensing path: ctrlX Store, Windows](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/path-ctrlx-windows.html) |
| ctrlX Store | ctrlX OS (ctrlX CORE or IPC) | ctrlX licence `SWL-W-XCx-COCKPITxxxHDVSx-V1NN`, one licence per app instance.<br><br>[Licensing path: ctrlX Store, ctrlX OS](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/path-ctrlx-os.html) |

Each device on which LumiScan Cockpit runs at the same time needs its own LumiScan Key. Keys can be exchanged between devices.

How to install CodeMeter Runtime and how to request, renew and move licences is described in [LumiScan Licensing](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/index.html).

On ctrlX OS, the application shuts down shortly after starting if the licence is missing; the reason is written to the system log.

## Where Cockpit runs

| Cockpit runs on | Data Layer |
| --- | --- |
| ctrlX OS (ctrlX CORE or ctrlX IPC) | the ctrlX Data Layer |
| a PC | LumiScan Keryx (see [Opening the Cockpit](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html#windows) and [LumiScan Keryx on a PC](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html)) |

On a PC, building Cockpit’s pages from source needs Node.js with npm.

## The applications it shows

Cockpit displays other applications' data, so on its own it shows an empty overview. The applications whose images and results it draws must run on the **same device** — the same ctrlX CORE or ctrlX IPC, or the same PC — because Cockpit reads them from the Data Layer there.

In practice the starting point is LumiScan Cam Driver with a configured camera: it publishes the image the other applications read and the results are drawn on.

## A browser, or Cockpit’s window

**On ctrlX OS:** Cockpit is reached from the ctrlX web interface, so any browser that can open the ctrlX interface can open Cockpit. Views are ordinary browser tabs.

**On a PC:** Cockpit shows its pages in a window of its own. Started with `--no-gui`, Cockpit opens no window and its pages are opened in a browser. Cockpit answers on `127.0.0.1` only, so the browser has to run on the same PC.

(Windows) Cockpit’s window needs the Microsoft Edge WebView2 Runtime; without it, Cockpit opens its pages in the default browser instead.

On both, a view that is not visible stops asking for updates, so views left open in background browser tabs cost nothing. A live view is an MJPEG stream, which every current browser shows in an ordinary image.

> [!NOTE]
> (ctrlX OS) Whether the ctrlX web interface passes a live view through without holding it back has not yet been verified on a device. If it does not, a live view shows still images instead - see [Live Updates](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html).

## Storage

Cockpit stores one thing: its settings file, a few kilobytes of JSON in the application’s data directory, holding the optional overlays and the live view settings. It keeps no images — every frame is fetched from the publishing application when it is shown. See [Overlays](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/overlays.html) and [Live view settings](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html#settings).

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

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/how-tos/mark-image-positions-with-overlays.html

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).

# Opening the Cockpit – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html

How Cockpit is opened depends on where it runs: on ctrlX OS it is opened from the ctrlX web interface, on a PC it opens a window of its own.

## On ctrlX OS

Cockpit has no window of its own on the device. It is opened from the ctrlX web interface, through the link the application adds to the sidebar when it is installed and running.

1. Open the ctrlX CORE web interface in a browser.
2. Click **LumiScan Cockpit** in the sidebar.

The link opens the address `/ctrlx-hdvisionsystems-cockpit/` of the ctrlX web interface; ctrlX hands it on to Cockpit.

## On a PC (LumiScan Keryx)

Cockpit runs on a PC with LumiScan Keryx, together with the applications it shows. It opens its pages in a window of its own, and serves them itself, on `127.0.0.1` only.

1. Start the applications and Cockpit. There is no broker to start first: the first of them to find none starts the LumiScan Keryx broker, at the default address `tcp://127.0.0.1:5555`, and the broker keeps running when they end (see [LumiScan Keryx on a PC](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html#broker)).
   ```
   lumiscan-cam-driver
   lumiscan-cockpit
   ```
2. The **LumiScan Cockpit** window opens. Starting Cockpit again while it runs brings that window to the front rather than opening a second one.

Closing the window ends Cockpit; the broker and the applications keep running.

For the broker, the port, the window and the log, see [Broker, Window and Pages (PC)](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html#windows).

## The application overview

The page that opens is the **application overview**: every compatible HD Vision Systems application currently running on the system, and the views each one offers. It is how you see what is available and active before opening anything.

**On ctrlX OS:** clicking a view opens it in a new browser tab, which then keeps itself current for as long as it is the visible tab.

**On a PC:** clicking a view opens it in the same window, which then keeps it current. The bar at the top of the window goes back (**←**) and forward (**→**) through the pages opened in it, and to the overview (**⌂**).

## When a view has nothing to show

A view reports the reason rather than showing an empty frame. The reasons and what to do are described in [Troubleshooting: A view shows a message instead of an image](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-view-nothing-to-show) and [Troubleshooting: Findings are not drawn](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-findings-not-drawn).

## Broker, Window and Pages (PC) {#windows}

This section applies to Cockpit on a PC with LumiScan Keryx.

The broker the applications start is the one of **LumiScan Keryx** when it is installed, which also brings up the Keryx page, `http://127.0.0.1:7555/`, to look at the tree; otherwise the `krxsystem` beside the applications. If the broker stops answering, the applications keep running and start it again.

Cockpit and the applications must use the same address. Without options they all do; an address passed with `--keryx-url` has to be passed to every one of them. Two cases start no broker, so start `krxsystem --backend hdv --url <address>` yourself first:

- an `ipc://` address relative to the folder it is started in (`ipc://x`); start the broker and every application from that same folder;
- `--no-keryx-autostart`, or the environment variable `LUMISCAN_KERYX_AUTOSTART=0`.

See also [Options and environment variables](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html#options).

Cockpit serves its pages on port 8000. When that port is taken, by another program or by a Cockpit started with `--no-gui`, Cockpit says so in a message and ends; `--port` chooses another port.

(Windows) Cockpit’s window shows its pages with the Microsoft Edge WebView2 Runtime. Without the runtime, Cockpit opens them in the default browser instead and shows a message; clicking **OK** there ends Cockpit.

`--no-gui` opens no window: Cockpit serves its pages for a browser on the same PC, at `http://127.0.0.1:8000/lumiscan-cockpit/` (`http://127.0.0.1:8000/` leads there too). A view then opens in a new browser tab.

(Windows) Started from a console as `lumiscan-cockpit`, without `.exe`, Cockpit keeps that console until it ends, writes its log there, and ends with Ctrl+C, with its window or with `--no-gui`. The name runs `lumiscan-cockpit.com`, which starts `lumiscan-cockpit.exe` and waits for it; `lumiscan-cockpit.exe` started directly gives the console back at once.

(Windows) Cockpit always writes its log to `%LOCALAPPDATA%\LumiScan Cockpit\logs\lumiscan-cockpit.log`.

Cockpit looks for its pages in a `www` folder beside its program, or in the folder `--frontend` names. Without them it serves only its API, and says so in its log.

## Starting from an Example (PC) {#generate-settings}

On a PC, Cockpit writes an example of its settings into a folder of your choice, and ends without starting. For example (Windows):

```shell
lumiscan-cockpit --generate-settings C:\work\cockpit-settings
```

Without a folder (`-g` alone) it writes into the current folder. The example is the settings file `lumiscan-cockpit.json` - the overlay drawn on the views and the limits of the live view - and its schema, `schemas\lumiscan-cockpit.schema.json`. Existing files are never overwritten: when one of them is in the folder already, nothing is written and the Cockpit says which.

The Cockpit then names the folder it reads its settings from. On Windows this is `%APP_RESOURCE_DIR%\etc\lumiscan-cockpit` when the environment variable `APP_RESOURCE_DIR` is set, otherwise `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cockpit\etc\lumiscan-cockpit`. Edit the example, copy it there, and start the Cockpit.

# Viewing Results – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html

Eight applications have their findings drawn on the image they were found in, in green, and AI Object Matching has its boxes drawn on a camera’s live frames (see [AI Object Matching on a camera stream](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html#ai-on-a-stream)):

| Application | Drawn | Labelled with |
| --- | --- | --- |
| `lumiscan-template-finder` | a rectangle at the angle the match was found | the template’s name and the score |
| `lumiscan-object-finder` | a rectangle around the object | the object’s id and the score |
| `lumiscan-text-reader` | a rectangle around each word | the word itself and the score |
| `lumiscan-area-detector` | each region tinted, one colour per region | the region’s number and its area, as `<label>:<area>` |
| `lumiscan-dmc-reader` | a rectangle around each code | the decoded text and the score |
| `lumiscan-qr-code-reader` | a rectangle around each code | the decoded text and the score |
| `lumiscan-aztec-code-reader` | a rectangle around each code | the decoded text and the score |
| `lumiscan-barcode-reader` | a rectangle around each code | the decoded text and the score |

A code that was located but not decoded has no text, and is labelled with its score alone.

## How a view is named

An application with modules is listed by module, and each module is one view.

A code reader has no modules — there is one reader per application — so it has a single view, named after the code it reads: `datamatrix-code`, `qr-code`, `aztec-code` or `bar-code`.

## What each one looks like

### Template Finder

![Template Finder](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/template-finder.png)

### Object Finder

![Object Finder](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/object-finder.png)

### Text Reader

![Text Reader](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/text-reader.png)

### Area Detector

![Area Detector](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/areadetect.png)

### DMC Reader

![DMC Reader](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/datamatrix-code.png)

### QR Code Reader

![QR Code Reader](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/qrcode.png)

### Aztec Code Reader

![Aztec Code Reader](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/aztec-code.png)

### Barcode Reader

![Barcode Reader](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/barcode.png)

## The Area Detector is drawn differently

A rectangle cannot show that two touching parts were separated rather than merged: overlapping boxes look the same either way. The Area Detector’s regions are tinted instead, one colour per region, over the image underneath so the part is still visible through the tint.

The number before the area is the region’s number in `output/blob-labels`, which is also what picks its colour — so an area on screen can be traced to the pixels it was measured from.

## AI Object Matching on a camera stream {#ai-on-a-stream}

While an AI Object Matching module infers on a camera’s image stream (its `control/subscribe/output/stream/active` is `true`), the module’s view is live: it shows the camera’s frames with the boxes of the module’s latest result drawn on them, in green, each labelled with its class name and score. A class the module’s class names do not cover is labelled with its number. See [Live view](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html#live-view).

The view shows the module’s one source, the stream named by its `setting/stream/address`. A result the source’s camera did not produce (its lineage names another camera) is not drawn on that camera’s frame. When the module subscribes to another stream, the view follows it within about a second.

> [!NOTE]
> The boxes are drawn on the **very frame** the result was found in: the result’s lineage names it, and Cockpit keeps the camera’s recent frames (64 MB) to find it. The view therefore shows a new picture with each result, not with each frame. When the frame is no longer kept - the module took longer than that to infer - the boxes are drawn on the newest frame instead, and the note **approximate** says so: while the scene moves, a box may then be a little off.

While the module is not streaming, its view shows its last result image, as before.

## What is not shown

LumiScan Calibration produces coordinates, not an image, so Cockpit does not show it.

# The View Region – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/the-view-region.html

None of the eight applications that draw findings publishes an image of its own — each reads one from another application — so Cockpit follows the module’s `input-image-address` to find the picture the findings belong on. If that has not been set, the view reports so rather than showing an empty frame; point the module at a camera’s image node first.

## The view is the region that was searched

Where a module searches only part of the image, you see that part, at its own size, with the findings on it — which is exactly what the detector was given. A module with no crop configured searches the whole image, so its view is the whole frame.

This applies to the four applications with modules. A code reader reports nothing but the codes it found, so its view is always the whole picture it read.

The region comes from **the result itself**, not from the module’s crop settings, so editing the crop after a run does not move the picture out from under the findings still on display. The view keeps showing what that result came from until the next run replaces it.

## When the image size no longer matches

If the last result was found in a camera image of a **different size** than the one now displayed, the findings are not drawn and a note says which size the result belongs to. What to do is described in [Troubleshooting: Findings are not drawn](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-findings-not-drawn).

# Live Updates – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html

A view keeps itself current, in one of two ways:

- **Still images** — while the application behind the view takes one picture at a time, Cockpit tells the browser when the picture has changed, and the browser fetches the new one.
- **Live view** — while a camera streams its images, the view shows the stream itself: frame after frame as they arrive, marked **LIVE** beside the view’s name.

The view switches between the two by itself. You do not choose.

## Still images

While a view is open, Cockpit watches the application behind it and tells the browser when the picture has changed; the browser then fetches the new frame.

Cockpit looks about **five times a second** and speaks **at most twice a second**, which bounds what a fast-cycling station costs. Nothing is missed by that, because the browser always fetches the newest frame rather than a queue of old ones.

A view that is not visible stops asking, so background tabs cost nothing.

## Live view {#live-view}

A view turns live when the camera behind it streams: when LumiScan Cam Driver’s `control/publish/execute` has started the stream for that camera (see the Cam Driver’s manual, "Streaming Images"). The view of an AI Object Matching module turns live when the module infers on camera streams; it then shows the frames of the camera its latest result came from, with the module’s boxes drawn on them (see [Viewing Results](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html#ai-on-a-stream)).

- The frames are sent as JPEG, at most at the **frame rate** set in the live view settings, with the overlays drawn on them.
- When frames arrive faster, the newest one is shown and the others are skipped: a view never lags behind the camera.
- When the stream stops, the view goes back to still images within about a second, showing the last picture the camera published.

Cockpit receives a camera’s stream only while a live view of it is open, and encodes each frame once, however many tabs or windows show the same view. When the last of them closes or leaves the view, this stops about ten seconds later; a reload in between does not restart it.

## Live view settings {#settings}

The gear (⚙) at the top of every page opens the live view settings:

| Setting | Range | Default | What it does |
| --- | --- | --- | --- |
| Frames per second, at most | 1 to 30 | 10 | How often each live view is encoded and sent. Lower values save processor time on the device (controller or PC) and network bandwidth. |
| JPEG quality | 50 to 95 | 85 | How sharp each frame is. Lower values make smaller frames. |

**Save** applies the settings at once to the next frame of every live view, wherever it is open. They are kept in Cockpit’s settings file (the `liveView` section) and survive a restart.

## When live or streaming is not available

**Eight views may stream at once** — still images or live. Beyond that, a view falls back to re-fetching its image every two seconds. The same fallback applies if the connection through a proxy does not allow streaming.

**Four live views may be open at once**, counting every tab and window. Beyond that, a live view shows still images instead and tries again every five seconds.

The picture stays correct either way — it just arrives later.

# Overlays – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/overlays.html

An **overlay** is a fixed shape Cockpit draws on top of an image — a region of interest, an alignment mark, a boundary the operator should judge a part against. It is drawn on still images and on the frames of a live view alike. Unlike the findings in [Viewing Results](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html), an overlay comes from you rather than from an application, and it does not change between frames.

Overlays are configured in a JSON file, Cockpit’s settings file:

**On ctrlX OS:** the file is reached through the file view on the ctrlX home screen.

**On a PC:** the file is `lumiscan-cockpit.json` in the folder Cockpit reads its settings from. On Windows this is `%APP_RESOURCE_DIR%\etc\lumiscan-cockpit` when the environment variable `APP_RESOURCE_DIR` is set, otherwise `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cockpit\etc\lumiscan-cockpit`. Open it in any text editor, preferably one that checks JSON against the schema in the `schemas` folder. Cockpit writes an example of the file on request, see [Starting from an Example](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html#generate-settings).

> [!IMPORTANT]
> The file is read **once, at start-up**. Editing it does not change a running Cockpit — restart the application to pick up a changed overlay. The same file holds the live view settings (`liveView`), which the settings panel changes at once - see [Live view settings](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html#settings).

## Choosing what an overlay applies to

Each overlay is keyed by the application and the image it belongs to, in the form `appName/imageName`.

Either half may be the wildcard `*`, which matches every value:

| Key | Applies to |
| --- | --- |
| `lumiscan-cam-driver/resultImage` | that one image from that one application |
| `*/resultImage` | the result image of **any** application |
| `lumiscan-cam-driver/*` | **every** image published by that application |

## Defining a shape

Each overlay element is a shape with these properties:

- **Color:** The colour of the shape. Either a named colour — `red`, `green`, `blue`, `black`, `white`, `yellow`, `cyan`, `magenta` — or six hex digits, `RRGGBB`, where the may be left off. A colour that cannot be read is drawn **white** rather than refused, so a typo shows up as a white shape.
- **Shape:** The type of shape to draw: `rectangle`, `circle` or `cross`.
- **Center position (`centerX`, `centerY`):** The location of the shape’s centre on the image.
- **Width and height:** The size of the shape. For circles, the width is used as the diameter.

### Relative and absolute coordinates

Position and size share one rule, which lets an overlay be written either way:

- Values **below** `1.0` are **relative** to the image dimensions — `0.0` is the left or top edge, `0.5` the middle, `0.99` almost the far edge.
- Values of `1.0` **and above** are **absolute pixel** coordinates.

A relative overlay keeps its place when the camera resolution changes; an absolute one stays on the same pixels.

> [!WARNING]
> `1.0` is **not** the far edge — it is one pixel. The rule is decided before anything is drawn, and it turns on whether the number is below `1.0`, so `1.0` falls on the absolute side. To place something at the far edge relatively, use a value just under `1.0`.
>
> The same trap applies to size: a `width` of `1.0` is a one-pixel-wide shape, not a full-width one.

## Example

This configuration adds a green rectangle to the centre of an image, and a red circle highlighting a specific region:

```json
{
  "overlay": {
    "lumiscan-cam-driver/resultImage": [
      {
        "color": "green",
        "shape": "rectangle",
        "centerX": 0.5,
        "centerY": 0.5,
        "width": 0.4,
        "height": 0.3
      },
      {
        "color": "red",
        "shape": "circle",
        "centerX": 75,
        "centerY": 25,
        "width": 100,
        "height": 100
      }
    ]
  }
}
```

The green rectangle is centred in the image using relative coordinates — 50 % from the left, 50 % from the top, four tenths of the width and three tenths of the height. The red circle uses absolute pixel coordinates: its centre sits 75 pixels from the left edge and 25 pixels from the top, and it is 100 pixels across.

## Complete reference {#complete-reference}

Every setting of this file as its JSON Schema `lumiscan-cockpit.schema.json` defines it, generated for version 1.2.0:

| Setting | Type | Default | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `overlay` | object |   |   | **Required.** Overlay settings for image annotations |
| `overlay/<name>` | object[] |   |   | Array of overlay elements to be drawn on the image. The name of this should follow the format appName/imageName it is possible to use a \* as a wildcard for either part |
| `overlay/<name>[]/color` | string |   | pattern `^(red\|green\|blue\|black\|white\|yellow\|cyan\|magenta\|#?[0-9A-Fa-f]{6})$` | **Required.** Color of the overlay element. Can be a named color (red, green, blue, black, white, yellow, cyan, magenta) or hex format (#RRGGBB or RRGGBB) |
| `overlay/<name>[]/shape` | string |   | `rectangle`, `circle`, `cross` | **Required.** Shape type of the overlay element |
| `overlay/<name>[]/centerX` | number |   |   | **Required.** X-coordinate of the shape center. Values < 1.0 are relative to image width (0.0-1.0), values >= 1.0 are absolute pixel coordinates |
| `overlay/<name>[]/centerY` | number |   |   | **Required.** Y-coordinate of the shape center. Values < 1.0 are relative to image height (0.0-1.0), values >= 1.0 are absolute pixel coordinates |
| `overlay/<name>[]/width` | number |   |   | **Required.** Width of the shape. Values < 1.0 are relative to image width (0.0-1.0), values >= 1.0 are absolute pixel values. For circles, this is the diameter |
| `overlay/<name>[]/height` | number |   |   | **Required.** Height of the shape. Values < 1.0 are relative to image height (0.0-1.0), values >= 1.0 are absolute pixel values |

## JSON Schemas {#json-schemas}

The application keeps the JSON Schemas of its settings files in its `schemas` folder; those copies always match the installed version. The schemas of LumiScan Cockpit 1.2.0 can also be downloaded: [JSON Schemas of LumiScan Cockpit 1.2.0](https://docs.hdvisionsystems.com/schemas/lumiscan-cockpit/1.2.0/index.html).

To have an editor such as Visual Studio Code check a copy of a settings file that you edit on your PC, point its `$schema` entry at the published schema:

```json
{
  "$schema": "https://docs.hdvisionsystems.com/schemas/lumiscan-cockpit/1.2.0/lumiscan-cockpit.schema.json",
  ...
}
```

Leave the `$schema` entry of the files on the device as the application wrote it.

# FAQ – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/faq.html

Short answers to common questions about LumiScan Cockpit. Each entry links to the page with the details. Problems and error messages are described in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html).

> [!TIP]
> Each entry has a fixed anchor (for example `#faq-open-cockpit`). To find an error message, search the [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html) page for it.

## Getting started

### What does LumiScan Cockpit do? {#faq-what-is-cockpit}

- **Answer:** Cockpit shows what the vision applications on a ctrlX CORE or ctrlX IPC, or on a PC, are looking at and what they found: on ctrlX OS in a web browser, on a PC in a window of its own. It is a viewer only: it shows the images published by LumiScan Cam Driver and LumiScan AI Object Matching, and draws the findings of eight further applications on the image they were found in. It configures nothing in those applications.
- **More:** [Description](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/description.html)

### What do I need to use Cockpit? {#faq-requirements}

- **Answer:** The applications whose images and results Cockpit shows must run on the same device - the same ctrlX CORE or ctrlX IPC, or the same PC - because Cockpit reads them from the Data Layer there (the ctrlX Data Layer on ctrlX OS, LumiScan Keryx on a PC); on its own it shows an empty overview. In practice, start with LumiScan Cam Driver and a configured camera. On ctrlX OS, any browser that can open the ctrlX web interface can open Cockpit; on a PC, Cockpit opens a window of its own (on Windows with the Microsoft Edge WebView2 Runtime). Cockpit stores only its settings file (the optional overlays and the live view settings) and keeps no images.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/requirements.html)

### How do I open Cockpit? {#faq-open-cockpit}

- **Answer:** On ctrlX OS, open the ctrlX CORE web interface in a browser and click **LumiScan Cockpit** in the sidebar; the application adds this link when it is installed and running. Clicking a view opens it in a new browser tab. On a PC, start the applications and `lumiscan-cockpit`: the **LumiScan Cockpit** window opens, and a view opens in the same window. The page that opens is the application overview: every compatible HD Vision Systems application currently running and the views each offers.
- **More:** [Opening the Cockpit](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html)

### Can a PLC or another application use what Cockpit draws? {#faq-programmatic-results}

- **Answer:** No. Cockpit provides no Data Layer output of its own; the drawing exists only in the browser or in Cockpit’s window. To act on a result programmatically, read that application’s own result nodes.
- **More:** [Description](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/description.html)

## Viewing results

### Which applications' results are drawn, and how? {#faq-supported-apps}

- **Answer:** Findings are drawn in green on the image they were found in:
  - `lumiscan-template-finder`: a rectangle at the angle of the match, labelled with the template name and score.
  - `lumiscan-object-finder`: a rectangle around the object, labelled with the object id and score.
  - `lumiscan-text-reader`: a rectangle around each word, labelled with the word and score.
  - `lumiscan-area-detector`: each region tinted in its own colour, labelled `<label>:<area>`.
  - `lumiscan-dmc-reader`, `lumiscan-qr-code-reader`, `lumiscan-aztec-code-reader`, `lumiscan-barcode-reader`: a rectangle around each code, labelled with the decoded text and score. A code that was located but not decoded is labelled with its score only.
  - `lumiscan-ai-object-matching`, while a module infers on a camera stream: the module’s boxes on the camera’s live frames, labelled with the class name and score.
- **More:** [Viewing Results](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html)

### How are the views named? {#faq-view-names}

- **Answer:** An application with modules is listed by module, and each module is one view. A code reader has no modules, so it has a single view named after the code it reads: `datamatrix-code`, `qr-code`, `aztec-code` or `bar-code`.
- **More:** [Viewing Results](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html)

### What does the label on an Area Detector region mean? {#faq-area-detector-labels}

- **Answer:** The label has the form `<label>:<area>`. The number before the colon is the region’s number in `output/blob-labels`, which also selects the region’s colour, so an area on screen can be traced to the pixels it was measured from. Regions are tinted instead of boxed because overlapping rectangles cannot show whether touching parts were separated or merged.
- **More:** [Viewing Results](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html)

### Why does a view show only part of the camera image? {#faq-view-shows-region}

- **Answer:** For the four applications with modules, a view shows the region that was searched, at its own size; a module without a crop searches and shows the whole frame. A code reader’s view is always the whole picture it read. The region comes from the result itself, not from the current crop settings, so editing the crop does not change the view until the next run.
- **More:** [The View Region](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/the-view-region.html)

## Live updates

### How quickly does a view update? {#faq-update-rate}

- **Answer:** While a view shows still images, Cockpit checks the application about five times a second and notifies the browser at most twice a second; the browser then fetches the newest frame, so no frame queue builds up. While a camera streams, the view is live and shows the frames as they arrive, at most at the frame rate set in the live view settings (default 10 per second). A view that is not visible stops asking, so background tabs cost nothing.
- **More:** [Live Updates](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html)

### How do I change the frame rate or the quality of a live view? {#faq-live-view-settings}

- **Answer:** Click the gear (⚙) at the top of any page. **Frames per second, at most** (1 to 30, default 10) and **JPEG quality** (50 to 95, default 85) apply at once to every live view, and are kept in the `liveView` section of Cockpit’s settings file.
- **More:** [Live view settings](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html#settings)

## Overlays

### How do I draw a fixed region of interest or mark on an image? {#faq-overlay-config}

- **Answer:** Configure an overlay in Cockpit’s settings file and restart Cockpit. On ctrlX OS the file is reached through the file view on the ctrlX home screen; on a PC it is `lumiscan-cockpit.json` in Cockpit’s settings folder (on Windows, `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cockpit\etc\lumiscan-cockpit`, or `%APP_RESOURCE_DIR%\etc\lumiscan-cockpit` when `APP_RESOURCE_DIR` is set). On a PC, `lumiscan-cockpit --generate-settings <folder>` writes an example.
  - Each overlay is keyed `appName/imageName`; either half can be the wildcard `*`.
  - Each element has `color` (`red`, `green`, `blue`, `black`, `white`, `yellow`, `cyan`, `magenta`, or `RRGGBB` with optional ), `shape` (`rectangle`, `circle` or `cross`), `centerX`, `centerY`, `width` and `height`. For circles, `width` is the diameter.
- **More:** [Overlays](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/overlays.html)

### Are overlay positions relative or in pixels? {#faq-overlay-coordinates}

- **Answer:** Both are possible, for position and size alike. Values below `1.0` are relative to the image dimensions (`0.0` = left or top edge, `0.5` = middle); values of `1.0` and above are absolute pixels. `1.0` is therefore one pixel, not the far edge: use a value just under `1.0` for the far edge, and note that a `width` of `1.0` is one pixel wide.
- **More:** [Overlays](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/overlays.html)

## Troubleshooting {#troubleshooting}

Problems and error messages are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html):

- [On ctrlX OS, Cockpit shuts down shortly after starting](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#ts-shuts-down-after-start)
- [On a PC, Cockpit says its port is taken and ends](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-port-taken)
- [On Windows, Cockpit opens in the browser instead of its own window](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-no-window)
- [The overview shows no applications](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-overview-empty-pc)
- [A view shows a message instead of an image](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-view-nothing-to-show)
- [Findings are not drawn, and a note shows which size the result belongs to](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-findings-not-drawn)
- [An AI Object Matching view on a stream says **approximate**](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-ai-approximate)
- [A view only updates every two seconds](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-view-updates-slowly)
- [A camera streams, but its view shows still images instead of **LIVE**](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-live-view-still)
- [An overlay change has no effect, or a shape is drawn white](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-overlay-not-applied)

## Licensing and support

### Which licence do I need, and what happens without one? {#faq-licence}

- **Answer:** The ctrlX licence for LumiScan Cockpit is `SWL-W-XCx-COCKPITxxxHDVSx-V1NN`. Bought in the ctrlX Store for ctrlX OS, it is a ctrlX licence and needs no LumiScan Key. On ctrlX OS, the application shuts down shortly after starting if the licence is missing; the reason is in the system log. For a PC, see the licence section on the Requirements page.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/requirements.html#licence), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)

### Where can I find more answers or get support? {#faq-support}

- **Answer:** See the site-wide [LumiScan FAQ](https://docs.hdvisionsystems.com/en/faq.html). For the Data Layer on both platforms, see the [Data Layer FAQ](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/faq.html). Contact HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905; for licences, [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).
- **More:** [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)

# Troubleshooting – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html

Start with the [General checks](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#general-checks): they help with every problem in LumiScan Cockpit. Then find your symptom in the sections below and work through its steps in order. The last section lists what to send to support if the problem persists.

## General checks {#general-checks}

Check these points first:

- **The applications run on the same device.** Cockpit shows other applications' data: the applications whose images and results it draws must run on the same ctrlX CORE or ctrlX IPC, or the same PC. On its own, Cockpit shows an empty overview. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/requirements.html).

- **The application overview.** It lists every compatible HD Vision Systems application currently running, and the views each one offers. See [Opening the Cockpit](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html).

- **On a PC: the same broker address.** Cockpit and the applications must use the same address. Without options they all do; an address passed with `--keryx-url` has to be passed to every one of them. With LumiScan Keryx installed, the Data Layer page `http://127.0.0.1:7555/` shows the tree. See [Broker, Window and Pages (PC)](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html#windows).

- **The settings file is read once, at start-up.** Only the live view settings, changed in the settings panel, apply at once. See [Overlays](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/overlays.html).

- **The log.**

  | Platform | Log |
  | --- | --- |
  | ctrlX OS | the ctrlX OS system log: the Logbook of the ctrlX web interface, or `journalctl`. See [ctrlX Data Layer on ctrlX OS](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html) |
  | Windows | `%LOCALAPPDATA%\LumiScan Cockpit\logs\lumiscan-cockpit.log`. Started from a console as `lumiscan-cockpit`, Cockpit also writes its log to that console |

## Opening Cockpit {#opening-cockpit}

### Problem: On ctrlX OS, Cockpit shuts down shortly after starting {#ts-shuts-down-after-start}

**Symptoms**

On ctrlX OS, the Cockpit application shuts down shortly after it starts.

**Possible causes**

- The licence is missing. The ctrlX licence for LumiScan Cockpit is `SWL-W-XCx-COCKPITxxxHDVSx-V1NN`.

**Diagnostic procedure**

1. Read the ctrlX OS system log - expected: it gives the reason why the application shut down.
2. Check the sidebar of the ctrlX web interface - expected: the **LumiScan Cockpit** link. The application adds it when it is installed and running.

**Resolution**

- **If the licence is missing:** activate the ctrlX licence `SWL-W-XCx-COCKPITxxxHDVSx-V1NN` on the device, then start the application again. See [Licence](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/requirements.html#licence) and [LumiScan Licensing](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/path-ctrlx-os.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with the lines of the system log that give the reason.

### Problem: On a PC, Cockpit says its port is taken and ends {#faq-port-taken}

**Symptoms**

On a PC, Cockpit shows a message that its port is taken, and ends.

**Possible causes**

- Cockpit serves its pages on port 8000. Another program already uses this port.
- A Cockpit started with `--no-gui` already uses this port.

**Diagnostic procedure**

1. Check whether a Cockpit started with `--no-gui` runs - expected: none, if you want to start Cockpit with its window.
2. Check whether another program uses port 8000.

**Resolution**

- **If another program or a Cockpit started with `--no-gui` uses the port:** end it, then start Cockpit again.
- **If the port must stay with the other program:** start Cockpit with `--port` and another port.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with the message Cockpit shows and the options it was started with.

### Problem: On Windows, Cockpit opens in the browser instead of its own window {#faq-no-window}

**Symptoms**

On Windows, Cockpit opens its pages in the default browser instead of its own window, and shows a message. Clicking **OK** in the message ends Cockpit.

**Possible causes**

- The Microsoft Edge WebView2 Runtime is missing. Cockpit’s window shows its pages with it.

**Diagnostic procedure**

1. Check whether Cockpit was started with `--no-gui` - expected: not, if you want its window. With `--no-gui`, Cockpit opens no window by design.
2. Check whether the Microsoft Edge WebView2 Runtime is installed on the PC.

**Resolution**

- **If the WebView2 Runtime is missing:** install it, then start Cockpit again. Or use Cockpit in the browser.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with the message Cockpit shows.

### Problem: The overview shows no applications {#faq-overview-empty-pc}

**Symptoms**

The application overview lists no applications.

**Possible causes**

- The applications are not running.
- The applications do not run on the same device as Cockpit.
- On a PC: Cockpit and the applications do not use the same broker. An address passed with `--keryx-url` was not passed to every one of them.
- On a PC: no broker was started. This happens with an `ipc://` address relative to the folder a program is started in, and with `--no-keryx-autostart` or `LUMISCAN_KERYX_AUTOSTART=0`.

**Diagnostic procedure**

1. Check that the applications run on the same device as Cockpit.
2. On a PC, compare the options Cockpit and the applications were started with - expected: the same `--keryx-url`, or none.
3. On a PC with LumiScan Keryx, open the Data Layer page `http://127.0.0.1:7555/` - expected: the tree shows the running applications.

**Resolution**

- **If the applications are not running:** start them.
- **If the applications run on another device:** run them on the same device as Cockpit.
- **If they use different broker addresses:** pass the same `--keryx-url` to every application, Cockpit included, or start them all without the option.
- **If no broker was started:** start `krxsystem --backend hdv --url <address>` yourself first. With a relative `ipc://` address, start the broker and every application from the same folder.

See also [Data Layer troubleshooting: the broker](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#no-broker) and [Data Layer troubleshooting: an app is missing](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#app-missing).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with the options Cockpit and the applications were started with.

## Views and results {#views-and-results}

### Problem: A view shows a message instead of an image {#faq-view-nothing-to-show}

**Symptoms**

A view reports why it has nothing to show, instead of an empty frame.

**Possible causes**

- The application has not produced an image yet.
- No image source is configured. The eight applications that draw findings read their image from elsewhere, and Cockpit follows the module’s `input-image-address` to find it.
- The result belongs to a different image size, see [Problem: Findings are not drawn, and a note shows which size the result belongs to](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-findings-not-drawn).

**Diagnostic procedure**

1. Read the reason the view shows.
2. For a publishing application: check whether it has run since it started.
3. For one of the eight applications that draw findings: read the module’s `input-image-address` - expected: a camera’s image node.

**Resolution**

- **If the application has not produced an image yet:** run the publishing application once.
- **If no image source is configured:** point the module at a camera’s image node first.
- **If the result belongs to a different image size:** see [Problem: Findings are not drawn, and a note shows which size the result belongs to](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#faq-findings-not-drawn).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with the reason the view shows and the module’s `input-image-address`.

### Problem: Findings are not drawn, and a note shows which size the result belongs to {#faq-findings-not-drawn}

**Symptoms**

The view shows the image without findings, and a note says which image size the result belongs to.

**Possible causes**

- The last result was found in a camera image of a different size than the one displayed, usually because the camera resolution changed after the last run.

**Diagnostic procedure**

1. Compare the size in the note with the current camera resolution - expected: they differ.

**Resolution**

- **If the camera resolution changed after the last run:** run the application again to refresh the result against the new resolution.

See [The View Region](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/the-view-region.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with the size shown in the note and the camera resolution.

### Problem: An AI Object Matching view on a stream says **approximate** {#faq-ai-approximate}

**Symptoms**

The live view of an AI Object Matching module shows the note **approximate**. While the scene moves, a box may be a little off.

**Possible causes**

- The module took longer to infer than Cockpit keeps the camera’s recent frames (64 MB). The frame the result was found in is no longer kept, so the boxes are drawn on the newest frame instead.

**Diagnostic procedure**

1. Check that the module infers on a camera’s image stream - expected: its `control/subscribe/output/stream/active` is `true`. The note appears only on such a live view.

**Resolution**

- **If the frame is no longer kept:** no action is needed. The boxes are drawn on the newest frame and marked **approximate**. When a result arrives in time, its boxes are drawn on the very frame it was found in.

See [AI Object Matching on a camera stream](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html#ai-on-a-stream).

**If the problem persists**

Contact support with the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information), if boxes that are a little off are a problem for your application.

## Live updates {#live-updates}

### Problem: A view only updates every two seconds {#faq-view-updates-slowly}

**Symptoms**

A view shows a new picture only every two seconds.

**Possible causes**

- More than eight views stream at once, still images or live. Beyond eight, a view falls back to re-fetching its image every two seconds.
- The connection through a proxy does not allow streaming.

**Diagnostic procedure**

1. Count the views that are open - expected: eight or fewer.
2. Check whether the browser reaches Cockpit through a proxy.

**Resolution**

- **If more than eight views are open:** close views you do not need.
- **If a proxy does not allow streaming:** the view keeps re-fetching its image every two seconds. The picture stays correct; it just arrives later.

See [Live Updates](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with the number of open views and whether a proxy is used.

### Problem: A camera streams, but its view shows still images instead of **LIVE** {#faq-live-view-still}

**Symptoms**

The camera streams its images, but its view shows still images, and **LIVE** does not appear beside the view’s name.

**Possible causes**

- More than four live views are open at once, counting every tab and window. Beyond four, a live view shows still images and tries again every five seconds.
- The stream was not started with LumiScan Cam Driver’s `control/publish/execute`. A view turns live only then. The view of an AI Object Matching module turns live when the module infers on camera streams.
- On ctrlX OS: the ctrlX web interface does not pass the live view through. Whether it does has not yet been verified on a device.

**Diagnostic procedure**

1. Count the live views open in every tab and window - expected: four or fewer.
2. On the camera, read `control/publish/output/stream/active` of LumiScan Cam Driver - expected: `true`. See [The producer: the Cam Driver](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html#producer).

**Resolution**

- **If more than four live views are open:** close live views you do not need. The view tries again every five seconds.
- **If the stream was not started:** start it with the Cam Driver’s `control/publish/execute`. See the Cam Driver’s manual, "Streaming Images".
- **If the ctrlX web interface does not pass the live view through:** the view shows still images. The picture stays correct; it just arrives later.

See [Live view](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html#live-view).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with the number of open live views and the value of `control/publish/output/stream/active`.

## Overlays {#overlays}

### Problem: An overlay change has no effect, or a shape is drawn white {#faq-overlay-not-applied}

**Symptoms**

After you edited Cockpit’s settings file, the overlay does not change; or a shape is drawn in white instead of its colour.

**Possible causes**

- Cockpit has not been restarted since the edit. The settings file is read only once, at start-up.
- The `color` value cannot be read. A colour that cannot be read is drawn white instead of being refused.
- A position or size of `1.0` or above is in absolute pixels: `1.0` is one pixel, not the far edge or the full width.

**Diagnostic procedure**

1. Check whether Cockpit was restarted after the file was edited.
2. Check the `color` value of every white shape - expected: `red`, `green`, `blue`, `black`, `white`, `yellow`, `cyan`, `magenta`, or six hex digits `RRGGBB` (the may be left off).
3. Check `centerX`, `centerY`, `width` and `height` - expected: values below `1.0` where you mean relative values.

**Resolution**

- **If Cockpit was not restarted:** restart the Cockpit application.
- **If the colour cannot be read:** correct the typo in the `color` value, then restart Cockpit.
- **If a value of `1.0` was meant as the far edge or the full width:** use a value just under `1.0`, then restart Cockpit.

See [Overlays](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/overlays.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html#support-information) to support, together with Cockpit’s settings file.

## Information for support {#support-information}

Contact HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905; for licences, [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com). Please send:

- the version of LumiScan Cockpit;
- the platform: ctrlX OS and its version on a ctrlX CORE or ctrlX IPC, or a PC and its operating system;
- the date and time of the error;
- the log: on ctrlX OS from the system log (Logbook of the ctrlX web interface, or `journalctl`); on Windows `%LOCALAPPDATA%\LumiScan Cockpit\logs\lumiscan-cockpit.log`;
- the communication status: the applications and views the overview lists, and on a PC the Data Layer address (`--keryx-url`) passed to Cockpit and to the applications;
- the message or note the view shows;
- the configuration: Cockpit’s settings file (`lumiscan-cockpit.json` on a PC), and on a PC the options Cockpit was started with.

# Release Notes: v1.3.0 - not yet released – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/release-notes/v1-3-0.html

The Cockpit now shows a streaming camera live.

## New

**Live view.** While a camera streams its images (LumiScan Cam Driver’s `control/publish/execute`), its view shows the stream itself, frame after frame, marked **LIVE**. When the stream stops, the view goes back to still images by itself. See [Live view](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html#live-view).

**AI Object Matching on a stream.** While a module infers on camera streams, its view shows the camera’s frames with the module’s boxes drawn on them, labelled with the class name and score - each result on the very frame it was found in. See [Viewing Results](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html#ai-on-a-stream).

**Live view settings.** A gear at the top of every page sets the frame rate (1 to 30, default 10) and the JPEG quality (50 to 95, default 85) of every live view. They apply at once and survive a restart. See [Live view settings](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html#settings).

**Runs on Windows** with LumiScan Keryx, for development and testing. See [Opening the Cockpit](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/opening-the-cockpit.html#windows).

## Worth knowing

Cockpit receives a camera’s stream only while a live view of it is open, and encodes each frame once for all the tabs showing it. Four live views may be open at once; beyond that, a view shows still images and tries again every five seconds.

AI Object Matching’s boxes are drawn on the frame the result was found in, which Cockpit keeps among the camera’s recent frames (64 MB). A result whose frame is no longer kept is drawn on the newest frame, marked **approximate**.

Whether the ctrlX web interface passes a live view through without holding it back has not yet been verified on a device. If it does not, the view shows still images as before.

## Bugfix

**A still view no longer stalls on a busy scene.** Each change restarted the image the browser was loading, so on a station changing faster than one image arrived, the view showed nothing new. The newest change now waits for the image being loaded.

# Release Notes: v1.2.0 – LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/release-notes/v1-2-0.html

The Cockpit now shows the result of every vision application in the suite, not just a camera image.

## New

**Eight applications draw their results**, each on the image it worked on: the Text Reader, Template Finder, Object Finder and Area Detector, and the Aztec Code, QR Code, Barcode and DMC readers. An application with modules is listed as its modules; a code reader has one view, named after the code it reads. See [Viewing Results](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/viewing-results.html).

**Live images.** A view refreshes about 200 ms after the picture behind it changes, rather than on a fixed two second poll, so what is on screen follows the line instead of trailing it. See [Live Updates](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/live-updates.html).

## Worth knowing

The Area Detector’s regions are drawn as a translucent tint, one colour per region, labelled `<label>:<area>` — the label is the region’s number in `output/blob-labels`, so a measured area can be traced back to the pixels it came from. A rectangle could not show that: two touching parts that were separated and two that were merged give the same overlapping boxes.

A view shows **the region that was searched**, taken from the result itself rather than from the module’s current crop settings. Editing a crop after a run therefore does not move the picture out from under the findings still on display.

If the camera resolution changed since the last run, the findings are not drawn and a note says which size the result belongs to. Run the application again to refresh.

## Earlier releases

**Version 1.0.0** — first release. Shows the images published by the Camera Driver and by AI Object Matching.

# LumiScan Cockpit

URL: https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/index.html

|   |   |   |
| --- | --- | --- |
| ![Overview page with four running LumiScan apps](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/intro/step-1.svg)<br><br>**Your vision apps run.** Cockpit lists every compatible app on one page. | ![Camera image with two found parts outlined and labelled with name and score](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/intro/step-2.svg)<br><br>**See what each app sees.** The image with what the app found drawn on top. | ![Cockpit in a browser and in a PC window](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/_images/intro/step-3.svg)<br><br>**On ctrlX OS or a PC.** In the browser on ctrlX OS, in its own window on a PC. |

LumiScan Cockpit is the viewer for the LumiScan vision apps. It shows the image each app worked on and draws what the app found: template and object matches, detected areas, decoded codes and AI detections. Views follow each new frame and update live while a camera streams, which makes commissioning and visual checks fast. Cockpit changes no settings and stores no images.

For licensing, see [Licence](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/lumiscan-cockpit/requirements.html#licence). Questions? See the [FAQ](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/faq.html). A problem or an error message? See [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cockpit/1.2.0/troubleshooting.html).
