mp.Image

A container for storing an image or a video frame.

mp.Image(
    image_format: mp.ImageFormat,
    data: np.ndarray
)

Formats supported by Image are listed in the ImageFormat enum. Pixels are encoded row-major in an interleaved fashion. Image supports uint8, uint16, and float as its data types.

Image can be created by copying the data from a numpy ndarray that stores the pixel data continuously. The data in an Image will become immutable after creation.

The pixel data in an Image can be retrieved as a numpy ndarray by calling Image.numpy_view(). The returned numpy ndarray is a reference to the internal data and itself is unwritable. If the callers want to modify the numpy ndarray, it's required to obtain a copy of it.

Pixel data retrieval examples:

for channel in range(num_channel):
  for col in range(width):
    for row in range(height):
      print(image[row, col, channel])

output_ndarray = image.numpy_view()
print(output_ndarray[0, 0, 0])
copied_ndarray = np.copy(output_ndarray)
copied_ndarray[0,0,0] = 0

image_format The format of the image data.
data A numpy ndarray containing the image data.

channels Returns the number of channels in the image.
height Returns the height of the image.
image_format Returns the image format.
step Returns the width step of the image.
width Returns the width of the image.

Methods

create_from_ctypes

View source

@classmethod
create_from_ctypes(
    image_ptr: ctypes.c_void_p
) -> 'Image'

Creates an Image object from a ctypes pointer.

This methods creates a copy of the Image object, which points to the same underlying image data and extends its lifetime until the returned object gets garbage collected. If the original image is on GPU, the copy will allocate the pixel data on the CPU.

Args
image_ptr A ctypes pointer to the image data.

Returns
An Image object.

create_from_file

View source

@classmethod
create_from_file(
    file_name: str
) -> 'Image'

Creates an Image object from an image file.

Args
file_name The path to the image file.

Returns
An Image object.

Raises
RuntimeError If the image file cannot be decoded.

free_ctypes

View source

@classmethod
free_ctypes(
    image_ptr: ctypes.c_void_p
) -> None

Frees a ctypes pointer to an image.

Args
image_ptr A ctypes pointer to the image data.

is_aligned

View source

is_aligned(
    alignment_boundary: int
) -> bool

Return True if each row of the data is aligned to alignment boundary, which must be 1 or a power of 2.

Args
alignment_boundary An integer.

Returns
A boolean.

Examples
image.is_aligned(16)

is_contiguous

View source

is_contiguous() -> bool

Return True if the pixel data is stored contiguously (without any alignment padding areas).

is_empty

View source

is_empty() -> bool

Return True if the pixel data is unallocated.

numpy_view

View source

numpy_view() -> np.ndarray

Returns the image pixel data as an unwritable numpy ndarray.

Realign the pixel data to be stored contiguously and return a reference to the unwritable numpy ndarray. If the callers want to modify the numpy array data, it's required to obtain a copy of the ndarray.

Returns
An unwritable numpy ndarray.

Examples
output_ndarray = image.numpy_view() copied_ndarray = np.copy(output_ndarray) copied_ndarray[0,0,0] = 0

uses_gpu

View source

uses_gpu() -> bool

Return True if data is currently on the GPU..

__getitem__

View source

__getitem__(
    key: tuple[int, ...]
) -> Any

Use the indexer operators to access pixel data.

Args
key A tuple of integers representing the row, column, and channel indices (or row and column for single channel images).

Returns
The pixel data at the specified index.

Raises
IndexError If the index is invalid or out of bounds.

Examples
``` for channel in range(num_channel): for col in range(width): for row in range(height): print(image[row, col, channel])