Utility Functions

Filtering

Utility functions for searching sequences and iterables.

This module provides helper functions to find the first matching element in sequences and iterables based on a predicate or specific attribute criteria.

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

Find the first element in a sequence that satisfies the given predicate.

Parameters:

• predicate – A function that takes an element of the sequence as input and returns a boolean indicating whether the element satisfies a certain condition.

• seq – A sequence of elements to search.

Returns:

The first element of the sequence that satisfies the predicate, or None if no such element is found.

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

Find the first element in an iterable with attributes matching the specified criteria.

The function accepts keyword arguments where each key is the name of an attribute (using “__” to denote nested attributes) and the corresponding value is the value to match. For example, a keyword argument of foo__bar=10 will match objects where the attribute “foo.bar” equals 10.

Parameters:

• iterable – An iterable of elements to search.

• **kwargs – One or more attribute names and values to match against each element. The attribute names can use “__” to indicate nested attributes.

Returns:

The first element in the iterable that has all the specified attributes with matching values, or None if no such element is found.

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

GUI application for color selection and analysis from captured windows.

This application uses AutoCV to capture images from external windows, displays the captured frame, and provides pixel-level inspection (including a zoomed 3x3 region) along with a list of selected colors and computed “best color” information.