First steps

Intro to PixelFlow Quick Start

Core Concepts

Detections Converters Filters

Visualization

Overview Box Filled Box Label Mask Oval Anchors Blur Pixelate Grid Overlay

Grid Overlay Annotator

Draw grid lines inside bounding boxes for spatial reference, measurement, and analysis.

Output
PixelFlow Grid Overlay Annotator

Overview

The grid_overlay() annotator draws evenly-spaced grid lines inside each detection's bounding box. This is useful for spatial analysis, proportional measurements, pose alignment verification, and visual debugging. Optionally creates a filled checkerboard pattern for enhanced visibility.

Python 
pf.annotators.grid_overlay(image, detections)

Function Signature

Python 
def grid_overlay(    image: np.ndarray,    detections: Detections,    grid_size: Optional[Tuple[int, int]] = None,    thickness: Optional[int] = None,    colors: Optional[List[tuple]] = None,    filled: bool = False,    opacity: Optional[float] = None) -> np.ndarray

Parameters

Parameter Type Default Description
image np.ndarray required Input image in BGR format. Modified in-place.
detections Detections required PixelFlow detections with bounding boxes.
grid_size (rows, cols) or None None Grid dimensions. None = auto (~1 line per 50px).
thickness int or None None Line thickness in pixels. None = auto (thinner than boxes).
colors List[tuple] or None None List of BGR colors. None = use default palette.
filled bool False If True, creates checkerboard pattern with filled cells.
opacity float or None None Fill opacity when filled=True. None = 0.25.

Returns:
np.ndarray - The input image with grid overlays drawn (same array, modified in-place).

Basic Usage

Python 
import cv2import pixelflow as pffrom ultralytics import YOLO# Load image and run detectionimage = cv2.imread("people.jpg")model = YOLO("yolo11n.pt")results = model.predict(image)detections = pf.from_ultralytics(results)# Draw boxes with grid overlays insideimage = pf.annotators.box(image, detections)image = pf.annotators.grid_overlay(image, detections)cv2.imshow("Result", image)cv2.waitKey(0)

Grid Size Control

The grid_size parameter specifies (rows, cols) - the number of divisions in each direction. This creates rows-1 horizontal lines and cols-1 vertical lines.

Text only 
grid_size=(2,2)     grid_size=(3,3)      grid_size=(4,4)┌─────┬─────┐       ┌───┬───┬───┐        ┌──┬──┬──┬──┐│     │     │       │   │   │   │        │  │  │  │  │├─────┼─────┤       ├───┼───┼───┤        ├──┼──┼──┼──┤│     │     │       │   │   │   │        │  │  │  │  │└─────┴─────┘       ├───┼───┼───┤        ├──┼──┼──┼──┤   1 line each      │   │   │   │        │  │  │  │  │                    └───┴───┴───┘        ├──┼──┼──┼──┤                       2 lines each      │  │  │  │  │                                         └──┴──┴──┴──┘                                            3 lines each
Output
grid_size=(2,2)
Output
grid_size=(4,8)
Python 
# Simple 2x2 grid (one horizontal, one vertical line)image = pf.annotators.grid_overlay(image, detections, grid_size=(2, 2))# Standard 4x4 gridimage = pf.annotators.grid_overlay(image, detections, grid_size=(4, 4))# Fine 8x8 grid for detailed analysisimage = pf.annotators.grid_overlay(image, detections, grid_size=(8, 8))# Non-square grid: 3 rows, 5 columnsimage = pf.annotators.grid_overlay(image, detections, grid_size=(3, 5))

Auto-Sizing (Default)

When grid_size=None, the grid density is automatically calculated based on box dimensions (~1 line every 50 pixels):

Box Size Auto Grid
< 100px 2x2
100-150px 3x3
150-250px 4x4 to 5x5
250-500px 5x5 to 10x10
> 500px 10x10 (max)

Filled Mode (Checkerboard)

Set filled=True to create an alternating checkerboard pattern with filled cells. This makes the grid more visible and adds a stylistic effect.

Text only 
filled=False              filled=True (opacity=0.25)┌───┬───┬───┐            ┌───┬───┬───┐│   │   │   │            │███│   │███│├───┼───┼───┤            ├───┼───┼───┤│   │   │   │            │   │███│   │├───┼───┼───┤            ├───┼───┼───┤│   │   │   │            │███│   │███│└───┴───┴───┘            └───┴───┴───┘  Lines only              Checkerboard pattern
Python 
# Checkerboard with default opacity (0.25)image = pf.annotators.grid_overlay(image, detections, filled=True)# More visible checkerboardimage = pf.annotators.grid_overlay(image, detections, filled=True, opacity=0.4)# Subtle checkerboardimage = pf.annotators.grid_overlay(image, detections, filled=True, opacity=0.15)# Dense checkerboard patternimage = pf.annotators.grid_overlay(image, detections, grid_size=(6, 6), filled=True)
Output
filled=True, opacity=0.4

Styling Options

Line Thickness

Python 
# Thin lines for subtle gridimage = pf.annotators.grid_overlay(image, detections, thickness=1)# Thicker lines for visibilityimage = pf.annotators.grid_overlay(image, detections, thickness=3)

Custom Colors

Python 
# White grid for dark objectsimage = pf.annotators.grid_overlay(image, detections, colors=[(255, 255, 255)])# Custom color per classcustom_colors = [(0, 255, 0), (0, 0, 255), (255, 0, 0)]image = pf.annotators.grid_overlay(image, detections, colors=custom_colors)

Common Use Cases

Pose Analysis Reference

Python 
# Grid helps visualize body proportions for pose estimationimage = pf.annotators.box(image, detections)image = pf.annotators.grid_overlay(image, detections, grid_size=(4, 4))
Output
box() +&nbsp;grid_overlay()

Measurement and Alignment

Python 
# Fine grid for precise spatial analysisimage = pf.annotators.box(image, detections)image = pf.annotators.grid_overlay(image, detections)

Detection Debugging

Python 
# Verify detection coverage and proportionsimage = pf.annotators.box(image, detections)image = pf.annotators.grid_overlay(image, detections, filled=True, opacity=0.2)image = pf.annotators.label(image, detections)

Video Processing

Python 
import pixelflow as pffrom ultralytics import YOLOmodel = YOLO("yolo11n.pt")media = pf.Media("video.mp4")for frame in media.frames:    results = model.predict(frame, verbose=False)    detections = pf.from_ultralytics(results)        frame = pf.annotators.box(frame, detections)    frame = pf.annotators.grid_overlay(frame, detections, grid_size=(3, 3))        pf.show_frame("Analysis", frame)

Notes

  • In-place modification: The input image is modified directly. Use image.copy() if you need the original preserved.
  • Minimum grid: Grid size is automatically clamped to minimum 2x2.
  • Auto-sizing range: Auto-calculated grids range from 2x2 to 10x10 maximum.
  • Lines inside box: Grid lines are drawn inside the bounding box boundaries, not extending beyond.
  • Color matching: Grid color automatically matches the box color for visual consistency per class.
  • Checkerboard formula: Filled cells use (row + col) % 2 == 0 pattern.
  • Performance: Filled mode with opacity uses alpha blending which may impact performance on large images.

See Also

  • box() - Draw bounding boxes (typically used before grid_overlay)
  • keypoint() - Draw keypoints for pose estimation
  • anchors() - Draw anchor points for spatial reference