AnyImage

AnyImage = Image | CompressedImage, a type alias for image interface return types. Image represents raw pixel images (numpy arrays), CompressedImage represents compressed encoded images (such as JPEG, PNG byte streams). Both inherit from ImageBase and provide the same conversion interface.

Common properties:

Property	Type	Description
header	Header	Image metadata header
width	int	Image width
height	int	Image height

Image-specific properties:

Property	Type	Description
encoding	str	Pixel format, such as "rgb8", "bgr8", "mono8", "16uc1"

CompressedImage-specific properties:

Property	Type	Description
format	str	Codec format, such as "jpeg", "png"

Image

Signature:

Image(
    data: np.ndarray,
    header: Header,
    encoding: str = "unknown",
    width: int = 0,
    height: int = 0,
)

Description:

Construct a raw pixel image.

Parameters:

Parameter	Type	Required	Description
data	np.ndarray	Yes	Pixel array in HWC layout
header	Header	Yes	Image metadata header
encoding	str	No	Pixel format, such as "rgb8", "bgr8"
width	int	No	Image width; inferred from data when 0
height	int	No	Image height; inferred from data when 0

Returns:

Image instance.

CompressedImage

Signature:

CompressedImage(
    data: bytes,
    header: Header,
    format: str = "unknown",
    width: int = 0,
    height: int = 0,
)

Description:

Construct a compressed image.

Parameters:

Parameter	Type	Required	Description
data	bytes	Yes	Compressed image byte stream, such as JPEG payload
header	Header	Yes	Image metadata header
format	str	No	Codec format, such as "jpeg", "png"
width	int	No	Image width; detected from byte stream when 0
height	int	No	Image height; detected from byte stream when 0

Returns:

CompressedImage instance.

Raises:

None.

to_numpy

Signature:

AnyImage.to_numpy() -> np.ndarray

Description:

Returns a numpy array in HWC layout.

Parameters:

No parameters.

Returns:

np.ndarray, image array with shape (H, W, C) or (H, W).

Raises:

TypeError: Internal data of CompressedImage is not of bytes type.

Example:

arr = image.to_numpy()
print(arr.shape)
# Example output: (480, 640, 3)

to_pil

Signature:

AnyImage.to_pil() -> PIL.Image.Image

Description:

Convert to PIL image; non-8-bit data (depth maps, etc.) will be normalized to 0-255.

Parameters:

No parameters.

Returns:

PIL.Image.Image.

Raises:

TypeError: Internal data of CompressedImage is not of bytes type.

to_bytes

Signature:

AnyImage.to_bytes() -> bytes

Description:

Returns raw image bytes. Compressed images return the compressed payload, raw images return numpy tobytes() result.

Parameters:

No parameters.

Returns:

bytes.

Raises:

TypeError: Internal data type is not supported.

size

Signature:

AnyImage.size() -> tuple[int, int]

Description:

Returns (width, height); when dimensions are unknown, decoding will be triggered to retrieve metadata.

Parameters:

No parameters.

Returns:

tuple[int, int], (width, height).

Raises:

None.

Example:

size = image.size()
print(size)
# Example output: (640, 480)

save

Signature:

AnyImage.save(path: str, **kwargs: Any) -> None

Description:

Save image to file. Compressed images write raw bytes directly when the format matches the file extension; otherwise, save via PIL transcoding.

Parameters:

Parameter	Type	Required	Description
path	str	Yes	Output file path, format auto-selected based on extension
**kwargs	Any	No	Additional parameters passed to PIL.Image.save, such as quality

Returns:

None.

Raises:

OSError: Write failed.

resize

Signature:

AnyImage.resize(width: int, height: int) -> Image

Description:

Returns a new resized image object; the original object remains unchanged.

Parameters:

Parameter	Type	Required	Description
width	int	Yes	Target width
height	int	Yes	Target height

Returns:

Image, the new resized image object (always a raw pixel image).

Raises:

None.

show

Signature:

AnyImage.show() -> None

Description:

Displays the image in a PIL popup window, suitable for debugging.

Parameters:

No parameters.

Returns:

None.

Raises:

None.