Utility Functions

Filtering

Sequence filtering helpers.

AutoCV frequently needs to pick a single “best” item from collections (OCR hits, template matches, shapes, etc.). This module provides lightweight helpers for common selection patterns without introducing additional dependencies.

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

Return the first element that satisfies predicate.

Parameters:

• predicate – Predicate evaluated against each item.

• seq – Sequence to scan in order.

Returns:

The first matching element, or None if nothing matches.

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 of candidates to evaluate.

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

Returns:

First element satisfying every attribute constraint, otherwise None.

Geometry

Geometry helpers for rectangles and OpenCV contours.

The public functions in this module accept either rectangle tuples in (x, y, w, h) form or OpenCV contour arrays and provide convenient operations such as computing centers, sampling random points, and sorting shapes.

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

Return the center (x, y) of a rectangle or contour.

Parameters:

shape – Rectangle as (x, y, w, h) or contour array shaped (N, 2) or (N, 1, 2).

Returns:

Center coordinates.

Raises:

ValueError – If the contour area is zero.

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

Return a random point (x, y) within a rectangle or contour.

Parameters:

shape – Rectangle as (x, y, w, h) or contour array shaped (N, 2) or (N, 1, 2).

Returns:

Random point inside the shape.

Raises:

ValueError – If the contour is empty or invalid, or the rectangle is malformed.

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

Sort shapes based on the specified criterion.

Shapes can be rectangles or contours and are ordered using their centers.

Parameters:

• window_size – Window size as (width, height) for computing the window center.

• shapes – List of rectangles (x, y, w, h) or contour arrays.

• sort_by – Sorting criterion: inner_outer, outer_inner, left_right, right_left, top_bottom, or bottom_top.

Returns:

Sorted shapes. When sort_by is unrecognised, returns shapes unchanged.

Raises:

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