Skip to content

Exclusion Masks

Definition

Exclusion Masks are rectangular arrays (bitmaps) that correspond to the image sensor size. For each pixel in the camera image, the Exclusion Mask determines if it is considered or ignored by the measurement algorithm. This is used to mask out regions of the image sensor, where undesirable content is located.

Exclusion Masks are applied earlier in the processing pipeline than Scan Windows, which means that masked out regions will never produce points, even if they are included in a Scan Window. You can combine Exclusion Masks and Scan Windows to effectively combat stray light and obstructions for your ScanSystem.

Example Mask

Important Considerations

  1. While there are no enforced constraints on the number and location of masked pixels in an Exclusion Mask, it is recommended to only use rectangular regions. Masking single pixels is ineffective and will likely not produced the desired result.
  2. An exclusion mask is empty by default (all pixels have the value false), only when you use the provided API functions (see below) to set specific pixels will these be masked out.
  3. Internally, Exclusion Masks are implemented as a bitfield that can hold only true or false per pixel. The value true means the pixel is excluded.
Changes in future API versions

The existing implementation of Exclusion Masks is effective, but requires some math to convert from mask region corners to actual pixels. We are considering moving from a pixel-wise access to a Rect based approach, where you would give the corner coordinates of an Exclusion Mask only. JsSetup is already using this : when you check the generated ScanSystem file that JsSetup writes, you will find that only rectangular regions are written.

Defining Exclusion Masks in code

The Pinchot API provides functions for creating and setting Exclusion Masks. Here's how:

// For this example, we will mask out 
// a rectangular area starting at line 140 and column 120, with a width of 300 pixels
// and a height of 400 pixels.
uint excludedAreaLeft = 120;
uint excludedAreaTop = 140;
uint excludedAreaWidth = 300;
uint excludedAreaHeight = 400;
// create an empty mask
var mask = scanHead.CreateExclusionMask();
// clip the region to the width and height of the mask 
uint endX = Math.Min(excludedAreaLeft + excludedAreaWidth, mask.Width);
uint endY = Math.Min(excludedAreaTop + excludedAreaHeight, mask.Height);

for (uint y = excludedAreaTop; y < endY; y++)
{
    // index of the start of the line in the mask array
    var lineStart = mask.Width * y;
    mask.SetPixels((int) (lineStart + excludedAreaLeft), (int)(lineStart + endX));
}

switch (scanHead.Type)
{
    case ProductType.JS50WX or ProductType.JS50WSC or ProductType.JS50MX:
        // a mask is typically only valid for a single camera, as the light source
        // we are trying to mask out is only visible to that camera. 
        scanHead.SetExclusionMask(Camera.CameraA, mask);
        break;
    case ProductType.JS50X6B20 or ProductType.JS50X6B30 or ProductType.JS50Z820 or ProductType.JS50Z830:
        // a mask is typically only valid for a single camera, as the light source
        // we are trying to mask out is only visible to that camera. This example
        // will mask out the first laser (Laser1) which is implicitly associated with
        // CameraB. You can apply the mask to the other lasers for CameraB as well.
        scanHead.SetExclusionMask(Laser.Laser1, mask);
        break;
}

Comments