Utility Functions

Filtering

Sequence filtering helpers used across AutoCV utilities.

autocv.utils.filtering.find_first(predicate: Callable[[T], bool], seq: Sequence[T]) → T | None

Return the first element that satisfies predicate.

Parameters:

• predicate (Callable[[T], bool]) – Predicate evaluated against each item.

• seq (Sequence[T]) – Sequence to scan in order.

Returns:

First matching element, or None if nothing matches.

Return type:

T | None

autocv.utils.filtering.get_first(iterable: Iterable[T], **kwargs: object) → T | None

Return the first element whose attributes match kwargs.

Attribute lookups support Django-style __ separators so foo__bar maps to foo.bar.

Parameters:

• iterable (Iterable[T]) – Iterable of candidates to evaluate.

• **kwargs (object) – Attribute/value pairs that must all match.

Returns:

First element satisfying every attribute constraint, otherwise None.

Return type:

T | None

Geometry

Utility functions for working with shapes.

This module provides helper functions to get the center of a shape, obtain a random point within a shape, and sort shapes based on various criteria.

autocv.utils.geometry.get_center(shape: tuple[int, int, int, int] | ndarray[tuple[Any, ...], dtype[uint64]]) → tuple[int, int]

Return the center (x, y) of a shape.

If the shape is a rectangle (x, y, width, height), returns:

(x + width // 2, y + height // 2).

If the shape is a contour (a NumPy array of points), returns the centroid computed from image moments (m10/m00, m01/m00).

Parameters:

shape – Either a tuple of four integers (x, y, w, h) representing a rectangle, or a NumPy array representing a contour with shape (N, 2) or (N, 1, 2).

Returns:

A tuple (center_x, center_y) as integers.

Raises:

ValueError – If the contour area (m00) is zero.

autocv.utils.geometry.get_random_point(shape: tuple[int, int, int, int] | ndarray[tuple[Any, ...], dtype[uint64]]) → tuple[int, int]

Return a random point (x, y) within a shape.

If the shape is a rectangle (x, y, width, height), returns a random point within that rectangle. If the shape is a contour (a NumPy array of points), returns a random point that lies inside the contour.

Parameters:

shape – Either a tuple of four integers (x, y, w, h) representing a rectangle, or a NumPy array representing a contour with shape (N, 2) or (N, 1, 2).

Returns:

A tuple (rand_x, rand_y) as integers representing a random point inside the shape.

Raises:

ValueError – If the contour is empty or invalid, or if the shape cannot be unpacked into (x, y, w, h).

autocv.utils.geometry.sort_shapes(window_size: tuple[int, int], shapes: list[tuple[int, int, int, int] | ndarray[tuple[Any, ...], dtype[uint64]]], sort_by: Literal['inner_outer', 'outer_inner', 'left_right', 'right_left', 'top_bottom', 'bottom_top']) → list[tuple[int, int, int, int] | ndarray[tuple[Any, ...], dtype[uint64]]]

Sort shapes based on the specified criterion.

Shapes can be either rectangles (x, y, w, h) or contours (NumPy arrays of points). Sorting is performed based on the center of each shape, computed using get_center.

Sorting options:

• “inner_outer”: Sort in ascending order of distance from the window center.

• “outer_inner”: Sort in descending order of distance from the window center.

• “left_right”: Sort in ascending order of the x-coordinate of the shape center.

• “right_left”: Sort in descending order of the x-coordinate of the shape center.

• “top_bottom”: Sort in ascending order of the y-coordinate of the shape center.

• “bottom_top”: Sort in descending order of the y-coordinate of the shape center.

Parameters:

• window_size – A tuple (width, height) representing the size of the window. Used to compute the window center.

• shapes – A list of shapes, each of which is either a tuple (x, y, w, h) or a NumPy array representing a contour.

• sort_by – The sorting criterion. Must be one of “inner_outer”, “outer_inner”, “left_right”, “right_left”, “top_bottom”, or “bottom_top”.

Returns:

A sorted list of shapes according to the specified criterion.

Raises:

ValueError – If any shape is unrecognized or has an area of zero when calculating the center.

AutoColorAid

class autocv.auto_color_aid.AutoColorAid

Bases: Tk

Tkinter application for sampling colours from AutoCV-captured frames.

Streams window frames via AutoCV, offers pixel inspection tools, and computes helper statistics for automation tuning.