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. 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, reached through the file view on the ctrlX home screen.

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.

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.