# Class SegmentationMask

java.lang.Object
com.codename1.ai.vision.SegmentationMask

public final class SegmentationMask extends Object

Dense per-pixel foreground confidence mask. The confidence array is row-major with exactly `width * height` values in the range 0..1. It is defensively copied on construction and access.

The mask's resolution is the segmentation model's, not the source image's, so it is normally smaller than the frame it describes. `cutOut(Image, float)` and `toMaskImage(int)` rescale it for you; when reading `getConfidence()` directly, index it with `getWidth()` and `getHeight()` rather than the frame size.

    SelfieSegmenter segmenter = new SelfieSegmenter();
    segmenter.process(VisionImage.encoded(jpeg)).ready(mask -> {
        Image person = mask.cutOut(EncodedImage.create(jpeg), 0.6f);
        background.getStyle().setBgImage(person);
    }).except(error -> Log.e(error));

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SegmentationMask(int width, int height, float[] confidence)`
  Creates a row-major confidence mask without backend metadata.
  `SegmentationMask(int width, int height, float[] confidence, VisionMetadata metadata)`
  Creates a row-major confidence mask with backend diagnostics.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Image`
  `cutOut(Image source, float threshold)`
  Keeps the foreground of an image and makes the rest transparent.
  `float[]`
  `getConfidence()`
  `float`
  `getConfidenceAt(int x, int y)`
  Reads one mask pixel.
  `int`
  `getHeight()`
  `VisionMetadata`
  `getMetadata()`
  `int`
  `getWidth()`
  `Image`
  `toMaskImage(int rgb)`
  Renders the mask itself as a translucent tint, for drawing over the frame it describes as a foreground highlight.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### SegmentationMask

    public SegmentationMask(int width, int height, float[] confidence)
    Creates a row-major confidence mask without backend metadata.
    Parameters:
      `width` - mask width in pixels
      `height` - mask height in pixels
      `confidence` - one foreground probability per pixel, defensively copied
    Throws:
      `IllegalArgumentException` - if either dimension is negative, the pixel count exceeds the maximum Java array length, or `confidence` does not contain exactly one value per pixel

  - ### SegmentationMask

    public SegmentationMask(int width, int height, float[] confidence, VisionMetadata metadata)
    Creates a row-major confidence mask with backend diagnostics.
    Parameters:
      `width` - mask width in pixels
      `height` - mask height in pixels
      `confidence` - one foreground probability per pixel, defensively copied
      `metadata` - backend details, or `null`
    Throws:
      `IllegalArgumentException` - if either dimension is negative, the pixel count exceeds the maximum Java array length, or `confidence` does not contain exactly one value per pixel

- ## Method Details

  - ### getWidth

    public int getWidth()
    Returns:
      mask width, which may differ from source image width

  - ### getHeight

    public int getHeight()
    Returns:
      mask height, which may differ from source image height

  - ### getConfidence

    public float[] getConfidence()
    Returns:
      defensive copy of row-major foreground confidences

  - ### getConfidenceAt

    public float getConfidenceAt(int x, int y)
    Reads one mask pixel.
    Parameters:
      `x` - column in the range 0 to `getWidth()` - 1
      `y` - row in the range 0 to `getHeight()` - 1
    Returns:
      foreground probability in the range 0..1
    Throws:
      `IndexOutOfBoundsException` - if the position is outside the mask

  - ### cutOut

    public Image cutOut(Image source, float threshold)

    Keeps the foreground of an image and makes the rest transparent.

    The mask is sampled with nearest-neighbour scaling, so the result has `source`'s dimensions no matter what resolution the segmentation model produced. Pixels whose confidence is below `threshold` become fully transparent; the rest keep their original color and alpha.

    Parameters:
      `source` - the image the mask was computed from
      `threshold` - minimum foreground confidence to keep, clamped to 0..1
    Returns:
      a new image with the background removed
    Throws:
      `NullPointerException` - if `source` is `null`
      `IllegalArgumentException` - if this mask has no pixels

  - ### toMaskImage

    public Image toMaskImage(int rgb)

    Renders the mask itself as a translucent tint, for drawing over the frame it describes as a foreground highlight.

    Each pixel takes `rgb` as its color and the mask confidence as its alpha, so a fully confident foreground pixel is opaque and a background pixel is invisible. The result has the mask's own resolution; draw it scaled to the frame's bounds.

    Parameters:
      `rgb` - tint color as `0xRRGGBB`; any alpha in the value is ignored in favor of the mask
    Returns:
      a new image at this mask's resolution
    Throws:
      `IllegalArgumentException` - if this mask has no pixels

  - ### getMetadata

    public VisionMetadata getMetadata()
    Returns:
      backend metadata, or `null` when manually constructed