Overlays

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

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.

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.

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:

{
  "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

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

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.

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:

{
  "$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.