mp.Image

View source on GitHub

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

Methods

create_from_file

View source

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

Creates an Image object from an image file.

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.

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.

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.

for channel in range(num_channel):
  for col in range(width):
    for row in range(height):
      print(image[row, col, channel])
</td>
</tr>

</table>