> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datamarkin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mask

> Overlay segmentation masks on a video frame with support for both binary masks and polygon formats.

## Overview

Provides efficient mask visualization using optimized single-pass rendering and OpenCV's accelerated blending operations. Supports both binary mask arrays and polygon coordinate lists, with automatic format detection and conversion for seamless integration.

## Function Signature

```python theme={null}
mask(
    frame: np.ndarray,
    detections: Detections,
    opacity: float = 0.5,
    colors: Optional[List[tuple]] = None
) -> np.ndarray
```

## Parameters

<ParamField path="frame" type="np.ndarray" required>
  Input video frame in BGR format (height, width, 3). Modified in-place with overlaid masks.
</ParamField>

<ParamField path="detections" type="Detections" required>
  Detections object containing mask data. Each detection's masks attribute can contain binary arrays or polygon coordinate lists.
</ParamField>

<ParamField path="opacity" type="float" optional default="0.5">
  Opacity level for blending masks with the frame. Range: \[0.0, 1.0]. Default is 0.5 (semi-transparent). Value of 1.0 creates opaque masks, 0.0 makes them invisible.
</ParamField>

<ParamField path="colors" type="Optional[List[tuple]]" optional default="None">
  List of BGR color tuples to override default colors. Colors are mapped to unique class\_ids in order of appearance. If None, uses default ColorManager colors.
</ParamField>

## Returns

<ResponseField name="result" type="np.ndarray">
  Frame with masks overlaid using the specified opacity. The input frame is modified in-place for memory efficiency.
</ResponseField>

## Examples

<CodeGroup>
  ```python Example theme={null}
  import cv2
  import pixelflow as pf
  from ultralytics import YOLO

  # Load image and get segmentation predictions
  image = cv2.imread("path/to/image.jpg")
  model = YOLO("yolo11n-seg.pt")  # Segmentation model
  outputs = model.predict(image)  # Raw model outputs
  detections = pf.results.from_ultralytics(outputs)  # Convert to PixelFlow format

  # Apply masks with default semi-transparent overlay
  annotated = pf.annotators.mask(image, detections)

  # Use custom colors for specific classes
  custom_colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255)]  # Blue, Green, Red
  annotated = pf.annotators.mask(image, detections, colors=custom_colors)

  # Create opaque masks for clear segmentation boundaries
  annotated = pf.annotators.mask(image, detections, opacity=1.0)

  # Subtle overlay for background preservation
  annotated = pf.annotators.mask(image, detections, opacity=0.2)

  ```
</CodeGroup>

## Error Handling

<Warning>
  This function may raise the following exceptions:

  * **ValueError**: If binary mask dimensions do not match frame dimensions.
  * **AttributeError**: If detection objects lack required 'masks' attribute.
</Warning>

## Notes

<Note>
  * Input frame is modified in-place for memory efficiency
  * Supports both binary mask arrays (boolean or uint8) and polygon coordinate lists
  * Binary masks must match frame dimensions exactly
  * Polygon coordinates are automatically converted to binary masks using cv2.fillPoly
  * Uses single-pass rendering for optimal performance with multiple masks
  * OpenCV's addWeighted function provides hardware-accelerated blending
  * Empty or None mask data is automatically skipped
  * Single overlay creation minimizes memory allocation
  * Batch blending operation reduces computational overhead
  * Direct pixel assignment used for full opacity (opacity=1.0) to bypass blending
  * Polygon-to-mask conversion cached within the function scope
</Note>