cv2ext.image package¶

Submodules¶

cv2ext.image.color module¶

Submodule containing color utility functions for images.

Classes¶

Color: A class for color representation.

class cv2ext.image.color.Color(value)[source]¶

Bases: Enum

Represents a color in BGR format.

RED = (0, 0, 255)¶

BLUE = (255, 0, 0)¶

GREEN = (0, 128, 0)¶

ORANGE = (0, 185, 255)¶

PINK = (147, 20, 255)¶

YELLOW = (0, 255, 255)¶

MAGENTA = (255, 0, 255)¶

WHITE = (255, 255, 255)¶

CYAN = (255, 255, 0)¶

DARK_GREEN = (0, 204, 0)¶

PURPLE = (51, 0, 51)¶

BLACK = (0, 0, 0)¶

GRAY = (128, 128, 128)¶

TEAL = (128, 128, 0)¶

OLIVE = (0, 128, 128)¶

NAVY = (128, 0, 0)¶

LIME = (0, 255, 0)¶

AQUA = (212, 255, 127)¶

SKY_BLUE = (235, 206, 136)¶

INDIGO = (130, 0, 75)¶

BROWN = (19, 69, 139)¶

TURQUOISE = (208, 224, 64)¶

CORAL = (80, 127, 255)¶

TAN = (140, 180, 210)¶

VIOLET = (238, 130, 238)¶

SALMON = (114, 128, 250)¶

GOLD = (0, 215, 255)¶

SILVER = (192, 192, 192)¶

BRONZE = (50, 127, 205)¶

BEIGE = (179, 222, 245)¶

IVORY = (240, 255, 255)¶

MINT = (201, 252, 189)¶

property bgr: tuple[int, int, int]¶

Get Color as BGR format.

Returns:: The BGR representation of the color.
Return type:: tuple[int, int, int]

property rgb: tuple[int, int, int]¶

Get Color as RGB format.

Returns:: The RGB representation of the color.
Return type:: tuple[int, int, int]

property hsv: tuple[float, float, float]¶

Get Color as HSV format.

Returns:: The HSV representation of the color.
Return type:: tuple[float, float, float]

property hsl: tuple[float, float, float]¶

Get Color as HSL format.

Returns:: The HSL representation of the color.
Return type:: tuple[float, float, float]

property cmyk: tuple[float, float, float, float]¶

Get Color as CMYK format.

Returns:: The CMYK representation of the color.
Return type:: tuple[int, int, int, int]

property hex: str¶

Get Color as HEX format.

Returns:: The HEX representation of the color.
Return type:: str

cv2ext.image.draw module¶

Submodule containing wrapper/utility functions for drawing on images.

Functions¶

circle(): Wrapper around cv2.circle with autofilled args.
rectangle(): Wrapper around cv2.rectangle with autofilled args and flexible types.
text(): Wrapper around cv2.putText with autofilled args.

cv2ext.image.draw.rectangle(image: ndarray, p1: tuple[int, int] | tuple[int, int, int, int], p2: tuple[int, int] | None = None, color: Color | tuple[int, int, int] = Color.RED, thickness: int = 2, linetype: int = 16, opacity: float | None = None, *, copy: bool | None = None) → ndarray[source]¶

cv2.rectangle with autofilled args and flexible types.

While the image is returned from this function, the rectangle is drawn in memory, so the image is modified in place. Thus, the return value can be ignored unless the copy parameter is set to True.

Parameters:

image (np.ndarray) – The image to draw the rectangle on.
p1 (tuple[int, int] | tuple[int, int, int, int]) – The top-left point of the rectangle or the full rectangle. If the full rectangle is given, then p2 should be None, but if provided it will be ignored. The rectangle should be in x1, y1, x2, y2 format.
p2 (tuple[int, int], optional) – The bottom-right point of the rectangle. If this is provided, then p1 should be the top-left point.
color (Color | tuple[int, int, int], optional) – The color to draw the rectangle. In BGR format and the default is Color.RED or (0, 0, 255).
thickness (int, optional) – The thickness of the rectangle lines. A negative value such as cv2.FILLED will fill the rectangle. Default is 2.
linetype (int, optional) – The type of line to draw. Default is cv2.LINE_AA. The options are cv2.FILLED, cv2.LINE_4, cv2.LINE_8, cv2.LINE_AA.
opacity (float, optional) – The opacity to use for drawing. By default None or 100% opacity. Opacity should be in the range [0.0, 1.0]
copy (bool, optional) – Whether or not to draw on a copy of the image and return that. Default is False.

Returns:

The image with the rectangle drawn.

Return type:

np.ndarray

Raises:

ValueError – If p1 is a single point and p2 is not provided. If a valid combination from p1/p2 cannot be achieved.

cv2ext.image.draw.circle(image: ndarray, center: tuple[int, int], radius: int, color: Color | tuple[int, int, int] = Color.RED, thickness: int = 2, linetype: int = 16, opacity: float | None = None, *, copy: bool | None = None) → ndarray[source]¶

cv2.circle with autofilled args.

While the image is returned from this function, the circle is drawn in memory, so the image is modified in place. Thus, the return value can be ignored unless the copy parameter is set to True.

Parameters:

image (np.ndarray) – The image to draw the circle on.
center (tuple[int, int]) – The center of the circle.
radius (int) – The radius of the circle.
color (Color | tuple[int, int, int], optional) – The color to draw the circle. In BGR format and the default is Color.RED or (0, 0, 255).
thickness (int, optional) – The thickness of the circle lines. A negative value such as cv2.FILLED will fill the circle. Default is 2.
linetype (int, optional) – The type of line to draw. Default is cv2.LINE_AA. The options are cv2.FILLED, cv2.LINE_4, cv2.LINE_8, cv2.LINE_AA.
opacity (float, optional) – The opacity to use for drawing. By default None or 100% opacity. Opacity should be in the range [0.0, 1.0]
copy (bool, optional) – Whether or not to draw on a copy of the image and return that. Default is False.

Returns:

The image with the circle drawn.

Return type:

np.ndarray

cv2ext.image.draw.text(image: ndarray, text: str, p: tuple[int, int], font: int = 0, font_scale: float = 1.0, color: Color | tuple[int, int, int] = Color.RED, thickness: int = 2, linetype: int = 16, opacity: float | None = None, *, copy: bool | None = None, bottom_left_origin: bool | None = None) → ndarray[source]¶

cv2.putText with autofilled args.

While the image is returned from this function, the text is drawn in memory, so the image is modified in place. Thus, the return value can be ignored unless the copy parameter is set to True.

Parameters:

image (np.ndarray) – The image to draw the text on.
text (str) – The text to draw on the image.
p (tuple[int, int]) – The origin of the text. By default this is the top-left corner of the text. When bottom_left_origin is set to True, this is the bottom-left corner of the text.
font (int, optional) – The font to use for the text. Default is cv2.FONT_HERSHEY_SIMPLEX. Options are: cv2.FONT_HERSHEY_SIMPLEX, cv2.FONT_HERSHEY_PLAIN, cv2.FONT_HERSHEY_DUPLEX, cv2.FONT_HERSHEY_COMPLEX, cv2.FONT_HERSHEY_TRIPLEX, cv2.FONT_HERSHEY_COMPLEX_SMALL, cv2.FONT_HERSHEY_SCRIPT_SIMPLEX, cv2.FONT_HERSHEY_SCRIPT_COMPLEX. cv2.FONT_ITALIC can be added to any of these options.
font_scale (float, optional) – The size of the font. Default is 1.0.
color (Color, tuple[int, int, int], optional) – The color of the text. Default is Color.RED or (0, 0, 255).
thickness (int, optional) – The thickness of the text. Default is 2.
linetype (int, optional) – The type of line to draw. Default is cv2.LINE_AA. The options are cv2.FILLED, cv2.LINE_4, cv2.LINE_8, cv2.LINE_AA.
opacity (float, optional) – The opacity to use for drawing. By default None or 100% opacity. Opacity should be in the range [0.0, 1.0]
copy (bool, optional) – Whether or not to draw on a copy of the image and return that. Default is False.
bottom_left_origin (bool, optional) – Whether or not the origin is the bottom-left corner of the text. Default is False.

Returns:

The image with the text drawn.

Return type:

np.ndarray

Module contents¶

Submodule containing utilities for working with images.

Submodules¶

color: Color utilities for images.
draw: Drawing utilities for images.

Functions¶

color_euclidean_dist(): Compute the euclidean distance between two colors.
divide(): Divide an image into multiple sub-images.
dominant_color(): Compute the dominant color in an image.
mean_color(): Compute the mean color in an image.
image_tiler(): Tile an image across another image.
create_tiled_image(): Tile an image across another image, or create a new image of the tile.
letterbox(): Resize an image using the letterbox method.
resize_linear(): Resize an image using linear scaling.
patch(): Divide an image into equal size patches.
rescale(): Rescale an image from [0:255] to another range.

cv2ext.image.color_euclidean_dist(color1: tuple[int, int, int], color2: tuple[int, int, int]) → float[source]¶

Compute the euclidean distance between two colors.

The user can provide two colors manually, but this function was intended to be used with the outputs of ‘mean_color’ and ‘dominant_color’. Primarily, this function is used to compare color changes over time or difference between the two methods.

Parameters:

color1 (tuple[int, int, int]) – The first color.
color2 (tuple[int, int, int]) – The second color.

Returns:

The euclidean distance between the two colors.

Return type:

float

cv2ext.image.create_tiled_image(tile: ndarray, base: ndarray | None = None, tile_shape: tuple[int, int] | None = None, image_shape: tuple[int, int] | None = None) → ndarray[source]¶

Tile an image across another image, or create a new image of the tile.

Parameters:

tile (np.ndarray) – The image to tile across the base image.
base (np.ndarray, optional) – The base image to tile the image across. If provided, the tiles will be placed across the image in a grid pattern. Only placing a tile where the entrie tile can fit (i.e. no partial tiles). Only one of base, tile_shape, or image_shape can be provided.
tile_shape (tuple[int, int], optional) – The shape of the tiles to create. This should be in the form of (rows, cols). Where rows is the number of tiles in the y direction, and cols is the number of tiles in the x direction. Only one of base, tile_shape, or image_shape can be provided.
image_shape (tuple[int, int], optional) – The shape of the image to create. This should be in the form of (height, width). This is used to create a new image based on the tiles. Only one of base, tile_shape, or image_shape can be provided.

Returns:

The tiled image.

Return type:

np.ndarray

Raises:

ValueError – If no base, tile shape, or image shape is provided.
ValueError – If more than one of base, tile shape, or image shape is provided.

cv2ext.image.divide(image: np.ndarray, num_rows: int, num_cols: int, padding: int | tuple[int, int] | None = None, overlap_ratio: float | tuple[float, float] | None = None, *, copy: bool | None = None) → tuple[list[list[np.ndarray]], list[list[tuple[int, int]]]][source]¶

Split an image into multiple sub-images.

Parameters:

image (np.ndarray) – The image to split
num_rows (int) – The number of rows to divide the image into
num_cols (int) – The number of columns to divide the image into
padding (int, tuple[int, int], optional) – The padding to add to each region. Adds this value to each side (edges do not get padding). Can be a single value integer or a tuple representing the padding for (x, y)
overlap_ratio (float, tuple[float, float], optional) – An alternative to padding. Represents the overlap as a ratio of the overall size of the patch. This can be provided as an alternative to padding.
copy (bool, optional) – If set to True, then will return copies of the subregions instead of memory views. Can have a performance impact.

Returns:

The computed subregions in a row major format and offsets in same format. The overall list represents rows and each sublist iterates over the patches column wise. The offsets are the same list dimensions as the subimages.

Return type:

tuple[list[list[np.ndarray]], list[list[tuple[int, int]]]]

Raises:

ValueError – If both padding and overlap_ratio are given.

cv2ext.image.dominant_color(image: ndarray, bbox: tuple[int, int, int, int] | None = None, num_colors: int = 4, black_threshold: int = 50, *, ignore_black: bool | None = None) → tuple[int, int, int][source]¶

Get the dominant color from an image.

If there is no bounding box provided, then the color is computed across the entire image given. If a bbox is given then only the data within the bounding box is considered. The underlying computation is completed by using KMeans clustering on the pixel values.

Parameters:

image (np.ndarray) – The image to compute the color on
bbox (tuple[int, int, int, int], optional) – The optional bounding box to sample the image with. The bounding box should be in form: x1, y1, x2, y2 (top-left, bottom-right) format
num_colors (int) – The number of clusters to use for kmeans.
black_threshold (int) – The cutoff for when a pixel can be considered black. This cutoff is assessed by compared the B, G, and R channel values individually.
ignore_black (bool, optional) – Whether or not to ignore black pixels when returning the dominant color.

Returns:

The dominant color in BGR format.

Return type:

tuple[int, int, int]

cv2ext.image.image_tiler(base: np.ndarray, tile: np.ndarray) → Generator[np.ndarray, None, None][source]¶

Tile an image across another image.

This function yields images with the tile progressively tiling across the base image. Each tile is placed in a grid fashion in row then column order. All tiles stay on the image, such that the final image produced will be fully filed (without partial fills).

The first image produced will be the base image.

Parameters:

base (np.ndarray) – The base image to tile the image across.
tile (np.ndarray) – The image to tile across the base image.

Yields:

np.ndarray – The tiled image.

cv2ext.image.letterbox(image: ndarray, new_shape: tuple[int, int] = (640, 640), stride: int = 32, color: tuple[int, int, int] = (114, 114, 114), *, auto: bool | None = None, scale_fill: bool | None = None, scaleup: bool | None = None) → tuple[ndarray, tuple[float, float], tuple[float, float]][source]¶

Resize an image using the letterbox method.

This method resizes an image to a new shape while maintaining the aspect ratio of the original image. The new image is padded with a specified color to fill the remaining space. The padding can be adjusted to be divisible by a specified stride.

Parameters:

image (np.ndarray) – The image to resize
new_shape (tuple[int, int]) – The new shape to resize the image to. In form (width, height)
stride (int) – The stride to use for padding
color (tuple[int, int, int]) – The color to use for padding
auto (bool, optional) – Whether or not to automatically adjust the padding to be divisible by the stride
scale_fill (bool, optional) – Whether or not to scale the image to fill the new shape
scaleup (bool, optional) – Whether or not to scale the image up if the new shape is larger than the original image

Returns:

The resized image, the ratio of the new shape to the old shape, and the padding values used.

Return type:

tuple[np.ndarray, tuple[float, float], tuple[float, float]]

cv2ext.image.mean_color(image: ndarray, bbox: tuple[int, int, int, int] | None = None) → tuple[int, int, int][source]¶

Get the mean color from an image.

The mean color is computed by splitting the image into the corresponding blue, green, and red channels and then performing the mean computation on each channel.

Parameters:

image (np.ndarray) – The image to compute the color on
bbox (tuple[int, int, int, int], optional) – The optional bounding box to sample the image with. The bounding box should be in form: x1, y1, x2, y2 (top-left, bottom-right) format

Returns:

The mean color in BGR format.

Return type:

tuple[int, int, int]

cv2ext.image.patch(image: np.ndarray, patch_size: tuple[int, int], padding: int | tuple[int, int] | None = None, overlap: float | tuple[float, float] | None = None) → tuple[list[np.ndarray], list[tuple[int, int]], tuple[int, int]][source]¶

Divide an image into patches of a specific size.

If the image is not evenly divisble by the patch size, it will be scaled up to be evenly divisible based on the patch size and the provided padding/overlap.

Parameters:

image (np.ndarray) – The image to patch into sections.
patch_size (tuple[int, int]) – The patch size in (width, height).
padding (int, tuple[int, int], optional) – The padding to apply between the patches. This is the number of pixels (or pixel x/y) to overlap.
overlap (float, tuple[float, float], optional) – The overlap ratio to apply between the patches. For example, overlap=0.25 will have 25% of patch dimension be overlapping.

Returns:

The list of patches, list of offsets, and the image size which the patches and offsets are based off (could be different than input image size). The size is in format (width, height).

Return type:

tuple[list[np.ndarray], list[tuple[int, int]], tuple[int, int]]

Raises:

ValueError – If the padding in x or y is larger than patch size in width or height.

cv2ext.image.rescale(image: np.ndarray, value_range: tuple[float, float]) → np.ndarray[source]¶

Rescale an image to be within the values given.

Parameters:

image (np.ndarray) – The image to scale. Should be a np.ndarray of type np.uint8.
value_range (tuple[float, float]) – The values to convert the image to

Returns:

The rescaled image

Return type:

np.ndarray

Raises:

ValueError – If value_range[0] is not less than value_range[1]

cv2ext.image.resize_linear(image: ndarray, new_shape: tuple[int, int]) → tuple[ndarray, tuple[float, float]][source]¶

Resize an image using linear scaling.

Parameters:

image (np.ndarray) – The image to resize.
new_shape (tuple[int, int]) – The shape to resize the image to. In form (width, height)

Returns:

The resized image and the scaling factors from resizing

Return type:

tuple[np.ndarray, tuple[float, float]]