image_transform

Composable transforms for image arrays and pixel coordinates.

The transforms support two-dimensional grayscale images and channel-last color images. Each transform can be applied both to image data and to corresponding (x, y) coordinates.

robotblockset.cameras.image_transform.ImageArrayType: Grayscale (H, W) or channel-last color (H, W, C) image array.

robotblockset.cameras.image_transform.HWCImageType: Compatibility alias for ImageArrayType.

class robotblockset.cameras.image_transform.ImageTransform(input_shape: Tuple[int, int] | Tuple[int, int, int])[source]

Bases: ABC

Base interface for related image and point-coordinate transforms.

Initialize a transform for images with a known input shape.

Parameters:: input_shape (ImageShapeType) – Grayscale (height, width) or color (height, width, channels) input shape.

__init__(input_shape: Tuple[int, int] | Tuple[int, int, int]) → None[source]

Initialize a transform for images with a known input shape.

Parameters:: input_shape (ImageShapeType) – Grayscale (height, width) or color (height, width, channels) input shape.

property shape: Tuple[int, int] | Tuple[int, int, int]

Return the shape of the transformed image.

Returns:: Grayscale or channel-last output shape.
Return type:: ImageShapeType
Raises:: NotImplementedError – If a subclass does not implement the property.

transform_image(image: ndarray) → ndarray[source]

Apply the transform to an image array.

Parameters:: image (ImageArrayType) – Source image. Implementations return a transformed image without intentionally modifying this array.
Returns:: Transformed image array.
Return type:: ImageArrayType
Raises:: NotImplementedError – If a subclass does not implement the method.

transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]

Map a source-image point into transformed-image coordinates.

Parameters:: point (ImagePointType) – Source (x, y) coordinate.
Returns:: Coordinate in the transformed image.
Return type:: ImagePointType
Raises:: NotImplementedError – If a subclass does not implement the method.

reverse_transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]

Map a transformed-image point back to source-image coordinates.

Parameters:: point (ImagePointType) – Transformed (x, y) coordinate.
Returns:: Coordinate in the source image.
Return type:: ImagePointType
Raises:: NotImplementedError – If a subclass does not implement the method.

class robotblockset.cameras.image_transform.ComposedTransform(transforms: Sequence[ImageTransform])[source]

Bases: ImageTransform

Apply a non-empty sequence of image transforms in order.

Create a transform composition.

Parameters:: transforms (Sequence[ImageTransform]) – Ordered, non-empty sequence of transforms.
Raises:: ValueError – If transforms is empty.

__init__(transforms: Sequence[ImageTransform]) → None[source]

Create a transform composition.

Parameters:: transforms (Sequence[ImageTransform]) – Ordered, non-empty sequence of transforms.
Raises:: ValueError – If transforms is empty.

property shape: Tuple[int, int] | Tuple[int, int, int]: Return the output shape of the final transform.

transform_image(image: ndarray) → ndarray[source]: Apply every transform to an image in sequence.

transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]: Map a point through every transform in sequence.

reverse_transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]: Map a point backward through the transforms in reverse order.

robotblockset.cameras.image_transform.crop(image: ndarray, x: int, y: int, w: int, h: int) → ndarray[source]

Return a copy of a rectangular image region.

Parameters:

image (ImageArrayType) – Grayscale or channel-last source image.
x (int) – X-coordinate of the top-left crop corner.
y (int) – Y-coordinate of the top-left crop corner.
w (int) – Crop width in pixels.
h (int) – Crop height in pixels.

Returns:

Copy of the selected region. Coordinates outside the image follow NumPy slicing semantics.

Return type:

ImageArrayType

class robotblockset.cameras.image_transform.Crop(input_shape: Tuple[int, int] | Tuple[int, int, int], x: int, y: int, w: int, h: int)[source]

Bases: ImageTransform

Crop an image and translate corresponding point coordinates.

Create a rectangular crop transform.

Parameters:

input_shape (ImageShapeType) – Shape of the source image.
x (int) – X-coordinate of the crop’s top-left corner.
y (int) – Y-coordinate of the crop’s top-left corner.
w (int) – Crop width in pixels.
h (int) – Crop height in pixels.

__init__(input_shape: Tuple[int, int] | Tuple[int, int, int], x: int, y: int, w: int, h: int) → None[source]

Create a rectangular crop transform.

Parameters:

input_shape (ImageShapeType) – Shape of the source image.
x (int) – X-coordinate of the crop’s top-left corner.
y (int) – Y-coordinate of the crop’s top-left corner.
w (int) – Crop width in pixels.
h (int) – Crop height in pixels.

property shape: Tuple[int, int] | Tuple[int, int, int]: Return the declared crop shape.

transform_image(image: ndarray) → ndarray[source]: Return a copy of the cropped image region.

transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]

Translate a source point into crop-local coordinates.

Raises:: ValueError – If the source point lies outside the crop rectangle.

reverse_transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]

Translate a crop-local point into source-image coordinates.

Raises:: ValueError – If the point lies outside the crop dimensions.

class robotblockset.cameras.image_transform.Resize(input_shape: Tuple[int, int] | Tuple[int, int, int], h: int, w: int, round_transformed_points: bool = True)[source]

Bases: ImageTransform

Resize an image and scale corresponding point coordinates.

Create an image resize transform.

Transforming points to or from a resized image can produce fractional coordinates. By default these coordinates are rounded to the nearest integer. Set round_transformed_points to False to preserve the floating-point result.

Parameters:

input_shape (ImageShapeType) – Shape of the source image.
h (int) – Output height in pixels.
w (int) – Output width in pixels.
round_transformed_points (bool, optional) – Whether point transformations return rounded coordinates. The default is True.

__init__(input_shape: Tuple[int, int] | Tuple[int, int, int], h: int, w: int, round_transformed_points: bool = True) → None[source]

Create an image resize transform.

Transforming points to or from a resized image can produce fractional coordinates. By default these coordinates are rounded to the nearest integer. Set round_transformed_points to False to preserve the floating-point result.

Parameters:

input_shape (ImageShapeType) – Shape of the source image.
h (int) – Output height in pixels.
w (int) – Output width in pixels.
round_transformed_points (bool, optional) – Whether point transformations return rounded coordinates. The default is True.

property shape: Tuple[int, int] | Tuple[int, int, int]: Return the resized image shape.

transform_image(image: ndarray) → ndarray[source]: Resize an image using OpenCV’s default interpolation.

transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]

Scale a source point into resized-image coordinates.

Raises:: ValueError – If the point lies outside the source image dimensions.

reverse_transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]

Scale a resized-image point back into source coordinates.

Raises:: ValueError – If the point lies outside the resized image dimensions.

class robotblockset.cameras.image_transform.Rotate90(input_shape: Tuple[int, int] | Tuple[int, int, int], num_rotations: int = 1)[source]

Bases: ImageTransform

Rotate images and corresponding points by multiples of 90 degrees.

Create a counter-clockwise right-angle rotation transform.

Parameters:

input_shape (ImageShapeType) – Shape of the source image.
num_rotations (int, optional) – Number of counter-clockwise 90-degree rotations. Values are reduced modulo four. The default is 1.

Raises:

TypeError – If num_rotations is not an integer.

__init__(input_shape: Tuple[int, int] | Tuple[int, int, int], num_rotations: int = 1) → None[source]

Create a counter-clockwise right-angle rotation transform.

Parameters:

input_shape (ImageShapeType) – Shape of the source image.
num_rotations (int, optional) – Number of counter-clockwise 90-degree rotations. Values are reduced modulo four. The default is 1.

Raises:

TypeError – If num_rotations is not an integer.

property shape: Tuple[int, int] | Tuple[int, int, int]: Return the rotated image shape.

transform_image(image: ndarray) → ndarray[source]: Return a copied array rotated counter-clockwise by 90-degree steps.

transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]

Rotate a source point into output-image coordinates.

Raises:: ValueError – If the point lies outside the source image dimensions.

reverse_transform_point(point: Tuple[int | float, int | float]) → Tuple[int | float, int | float][source]: Rotate an output-image point back into source coordinates.

Attributes

`ImageArrayType`	Grayscale `(H, W)` or channel-last color `(H, W, C)` image array.
`HWCImageType`	Compatibility alias for `ImageArrayType`.

Functions

crop(image, x, y, w, h)

Return a copy of a rectangular image region.

Classes

`ComposedTransform`(transforms)	Apply a non-empty sequence of image transforms in order.
`Crop`(input_shape, x, y, w, h)	Crop an image and translate corresponding point coordinates.
`ImageTransform`(input_shape)	Base interface for related image and point-coordinate transforms.
`Resize`(input_shape, h, w[, ...])	Resize an image and scale corresponding point coordinates.
`Rotate90`(input_shape[, num_rotations])	Rotate images and corresponding points by multiples of 90 degrees.