s6.vision.drawing

Drawing helpers and lightweight overlay API for OpenCV images.

This module provides a stateful, but convenient, interface for annotating images produced by the pipeline. The central Markers class exposes static methods to draw points, lines, shapes, text, and simple 3D wireframes onto NumPy image arrays. Two concepts make usage ergonomic:

  • Target context: Markers.target(image) sets a default image so calls can omit the image argument inside the context manager.

  • Buffered rendering: Markers.render_scope() batches drawing calls and flushes them in order on exit. This can reduce flicker and keep draw order clear when many annotations are produced per frame.

All colors are BGR tuples as used by OpenCV. Coordinates use the same pixel convention as the rest of the project: Vector2D(x, y) for image space and Vector3D(x, y, z) for world/camera space.

class s6.vision.drawing.Markers(*args, **kwargs)

Bases: object

Convenience API for drawing annotations on images.

The class is effectively a singleton and maintains global state for: - enable/disable switch for all drawing operations; - a stack of default target images (managed by target()); - an optional command buffer (managed by render_scope() and render()).

Public methods accept an optional image parameter; when omitted, the current target image from Markers.target(…) is used. Most methods return the image they drew on for convenience/chaining.

static disable()

Disable all drawing operations globally.

Returns:

Always returns False for convenience.

Return type:

bool

static enable()

Enable all drawing operations globally.

Returns:

Always returns True for convenience.

Return type:

bool

classmethod crosshair(image: ndarray = None, center: Vector2D = None, r: float = 1000, color: tuple = (255, 255, 255))

Draw a crosshair centered on a point.

Parameters:

  • image (np.ndarray | None) – Target image; if None, uses the current Markers.target image.

  • center (Vector2D) – Center of the crosshair.

  • r (float, optional) – Half-length of cross arms in pixels, by default 1000.

  • color (tuple, optional) – BGR color, by default white.

classmethod cross(image: ndarray = None, point: Vector2D = None, color=None, length: int = 15, thickness: int = 1)

Draw a diagonal X-shaped cross at a point.

Parameters:

  • image (np.ndarray | None) – Target image; if None, uses the current Markers.target image.

  • point (Vector2D) – Center of the X.

  • color (tuple | None) – BGR color (default derives from image if None).

  • length (int, optional) – Arm length in pixels, by default 15.

  • thickness (int, optional) – Line thickness, by default 1.

classmethod dot(image: ndarray = None, point: Vector2D = None, color=None)

Draw a simple dot marker at a point.

Uses the current Markers.target image if image is None.

classmethod circle(image: ndarray = None, point: Vector2D = None, radius: float = 5, color=(255, 255, 0), thickness: int = 1, filled: bool = True)

Draw a filled or outlined circle.

Parameters:

  • image (np.ndarray | None) – Target image; if None, uses the current Markers.target image.

  • point (Vector2D) – Circle center.

  • radius (float, optional) – Radius in pixels, by default 5.

  • color (tuple, optional) – BGR color, by default yellow.

  • thickness (int, optional) – Outline thickness if filled=False.

  • filled (bool, optional) – If True, draw a filled disk; otherwise outline only.

classmethod box(image: ndarray = None, center: Vector2D = None, size: float = 15, width: float = None, height: float = None, color=(255, 255, 255), thickness: int = 1)

Draw a rectangle centered at a point.

Parameters:

  • image (np.ndarray | None) – Target image; if None, uses the current Markers.target image.

  • center (Vector2D) – Center of the rectangle.

  • size (float, optional) – Half-side of a square. Ignored if width and height provided.

  • width (float | None) – Full dimensions of the rectangle in pixels. Both must be provided to override size.

  • height (float | None) – Full dimensions of the rectangle in pixels. Both must be provided to override size.

  • color (tuple, optional) – BGR color, by default white.

  • thickness (int, optional) – Line thickness, by default 1.

classmethod line(image: ndarray = None, start: Vector2D = None, end: Vector2D = None, thickness: int = 1, color=(255, 255, 255))

Draw a line segment between two points.

classmethod arrow(image: ndarray = None, start: Vector2D = None, end: Vector2D = None, thickness: int = 1, color=(255, 255, 255))

Draw an arrow from start to end with ~45° head.

classmethod guide(image: ndarray = None, point: Vector2D = None, color=(255, 255, 255), text: str = None)

Draw a guide arrow from image center toward an external point.

The arrow is clipped at the image boundary with a 5% margin and starts at an inner radius of 200 px from the center. Optional text is drawn near the start.

classmethod text(image: ndarray = None, text: str = None, location: Vector2D = None, font=0, fontScale: int = 1, color=(255, 255, 255), thickness: int = 2)

Draw a text string at a location.

Parameters:

  • image (np.ndarray | None) – Target image; if None, uses the current Markers.target image.

  • text (str) – Text content to draw.

  • location (Vector2D) – Bottom-left anchor of the text.

  • font (int, optional) – OpenCV font identifier.

  • fontScale (int, optional) – Scale factor applied to the font base size.

  • color (tuple, optional) – BGR color, defaults to white.

  • thickness (int, optional) – Stroke thickness in pixels.

classmethod vector_text(image: ndarray = None, prefix: str = '', vector=None, location: Vector2D = None, offset: Vector2D = None, font=0, fontScale: int = 1, thickness: int = 2, colors=None, line_height: int = 25, scale: float = 1.0, fmt: str = '{:1.4f}')

Draw components of a vector as stacked text lines.

Parameters:

  • image (np.ndarray | None) – Target image; if None, uses the current Markers.target image.

  • prefix (str, optional) – Optional text prefix for each line (e.g., “B.”).

  • vector (Vector2D | Vector3D) – Vector to display.

  • location (Vector2D) – Bottom-left anchor for the first line.

  • offset (Vector2D | None) – Additional offset applied to location.

  • font (int) – cv2.putText parameters.

  • fontScale (int) – cv2.putText parameters.

  • thickness (int) – cv2.putText parameters.

  • colors (sequence[tuple] | None) – Per-component BGR colors; defaults to R/G/B mapping.

  • line_height (int, optional) – Vertical pixels between lines, by default 25.

  • scale (float, optional) – Scalar applied to component values, useful for unit conversion.

  • fmt (str, optional) – Python format string used for numbers.

Returns:

The image the text was drawn on.

Return type:

np.ndarray

classmethod icosphere_3d(image: ndarray = None, camera: Camera = None, point: Vector3D = None, radius: float = None, subdivision: int = 2, color=(255, 255, 255), thickness: int = 1)

Draw a wireframe icosphere projected into the image.

Parameters:

  • image (np.ndarray | None) – Target image; if None, uses the current Markers.target image.

  • camera (Camera) – Camera used to project the mesh.

  • point (Vector3D) – Center of the sphere in world coordinates.

  • radius (float) – Sphere radius in world units.

  • subdivision (int, optional) – Mesh subdivision level, by default 2.

  • color (tuple, optional) – Line color, by default white.

  • thickness (int, optional) – Line thickness in pixels.

classmethod render()

Execute all buffered drawing operations.

classmethod render_scope()

Context manager that buffers operations until exit, then renders.

classmethod target(tgt: ndarray)

Context manager to set a default target image for drawing operations.

Within this context, drawing calls without an explicit image will draw on tgt.