​
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

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

​
Parameters

​
frame
np.ndarray
required
Input video frame in BGR format (height, width, 3). Modified in-place with overlaid masks.
​
detections
Detections
required
Detections object containing mask data. Each detection’s masks attribute can contain binary arrays or polygon coordinate lists.
​
opacity
float
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.
​
colors
Optional[List[tuple]]
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.

​
Returns

​
result
np.ndarray
Frame with masks overlaid using the specified opacity. The input frame is modified in-place for memory efficiency.

​
Examples

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)

​
Error Handling

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.

​
Notes

  • 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