HeifImage object

class pillow_heif.HeifImage(c_image)[source]

Bases: BaseImage

One image in a HeifFile container.

info["exif"]: bytes

Note

In HEIF orientation tag is only for information purposes and must not be used to rotate image.

EXIF metadata. Can be None

info["xmp"]: bytes

XMP metadata. String in bytes in UTF-8 encoding. Absent if xmp data is missing.

info["metadata"]: list[dict]

Other metadata(IPTC for example). List of dictionaries. Usual will be empty. Keys:

  • type: str

  • content_type: str

  • data: bytes

info["primary"]: bool

A boolean value that specifies whether the image is the main image when the file contains more than one image.

info["bit_depth"]: int

Shows the bit-depth of image in file(not the decoded one, so it may differs from bit depth of mode). Possible values: 8, 10 and 12.

info["chroma"]: int

Chroma subsampling of the image in file. Possible values: 420, 422 and 444. Absent for monochrome images.

info["thumbnails"]: list[int]

List of thumbnail boxes sizes. Can be empty.

info["icc_profile"]: bytes

ICC Profile. Can be absent. Can be empty.

info["icc_profile_type"]: str

Possible values: prof or rICC. Can be absent.

info["nclx_profile"]: dict

NCLX color profile. Can be absent. Keys:

info["content_light_level"]: dict

Content light level information(clli). Can be absent. Keys:

  • max_content_light_level: int

  • max_pic_average_light_level: int

info["mastering_display_colour_volume"]: dict

Mastering display colour volume(mdcv). Can be absent. Keys:

  • display_primaries_x: tuple[int, int, int]

  • display_primaries_y: tuple[int, int, int]

  • white_point_x: int

  • white_point_y: int

  • max_display_mastering_luminance: int

  • min_display_mastering_luminance: int

info["ambient_viewing_environment"]: dict

Ambient viewing environment(amve). Can be absent. Keys:

  • ambient_illumination: int

  • ambient_light_x: int

  • ambient_light_y: int

Note

These three properties hold the raw code values as defined in ITU-T H.274. Like nclx_profile and icc_profile they are written back during save; remove a key from info if you do not want it in the output file.

info["pixel_aspect_ratio"]: tuple[int, int]

Pixel aspect ratio(pasp) as (horizontal_spacing, vertical_spacing). Absent when the image has no pasp box. It is written back during save.

info["depth_images"]: list

List of HeifDepthImage if any present for image. Currently libheif does not support writing of them, only reading.

info["aux"]: dict

Auxiliary images present for the image. Keys are the auxiliary types, e.g. urn:com:apple:photo:2020:aux:hdrgainmap, values are lists of IDs to pass to get_aux_image(). Empty when the image has no auxiliary images. Currently libheif does not support writing of them, only reading.

info["tiling"]: dict

Tiling information when the image is stored as a grid of tiles. Absent for non-tiled images. All values are in the display space, the same as size. Keys:

  • num_columns: int

  • num_rows: int

  • tile_width: int

  • tile_height: int

  • image_width: int

  • image_height: int

info["heif"]: dict

Camera matrices of the image, present only when the file contains them. Keys:

  • camera_intrinsic_matrix: dict with focal_length_x, focal_length_y, principal_point_x, principal_point_y and skew

  • camera_extrinsic_matrix_rot: tuple of nine float, the rotation matrix

Note

These values are currently not written back during save.

property has_alpha: bool

True for images with the alpha channel, False otherwise.

property premultiplied_alpha: bool

True for images with premultiplied alpha channel, False otherwise.

to_pillow() → Image[source]

Helper method to create Image class.

Returns:

Image class created from an image.

get_aux_image(aux_id: int) → HeifAuxImage[source]

Method to retrieve the auxiliary image at the given ID.

Returns:

a HeifAuxImage class instance.

property data

Decodes image and returns image data.

Returns:

bytes of the decoded image.

load() → None

Method to decode image.

Note

In normal cases, you should not call this method directly, when reading data or stride property of image will be loaded automatically.

property stride: int

Stride of the image.

Note

from 0.10.0 version this value always will have width * sizeof pixel in default usage mode.

Returns:

An Int value indicating the image stride after decoding.

size: tuple[int, int]

Width and height of the image.

mode: str

A string which defines the type and depth of a pixel in the image: Pillow Modes

For currently supported modes by Pillow-Heif see Modes.

class pillow_heif.heif.BaseImage(c_image)[source]

Bases: object

Base class for HeifImage, HeifDepthImage and HeifAuxImage.

size: tuple[int, int]

Width and height of the image.

mode: str

A string which defines the type and depth of a pixel in the image: Pillow Modes

For currently supported modes by Pillow-Heif see Modes.

property data

Decodes image and returns image data.

Returns:

bytes of the decoded image.

property stride: int

Stride of the image.

Note

from 0.10.0 version this value always will have width * sizeof pixel in default usage mode.

Returns:

An Int value indicating the image stride after decoding.

to_pillow() → Image[source]

Helper method to create Image class.

Returns:

Image class created from an image.

load() → None[source]

Method to decode image.

Note

In normal cases, you should not call this method directly, when reading data or stride property of image will be loaded automatically.

class pillow_heif.heif.HeifDepthImage(c_image)[source]

Bases: BaseImage

Class representing the depth image associated with the HeifImage class.

info["metadata"]: dict

Represents libheif heif_depth_representation_info struct as a dictionary.

If someone have an example when this struct got filled let me know.

to_pillow() → Image[source]

Helper method to create Image class.

Returns:

Image class created from an image.

property data

Decodes image and returns image data.

Returns:

bytes of the decoded image.

load() → None

Method to decode image.

Note

In normal cases, you should not call this method directly, when reading data or stride property of image will be loaded automatically.

property stride: int

Stride of the image.

Note

from 0.10.0 version this value always will have width * sizeof pixel in default usage mode.

Returns:

An Int value indicating the image stride after decoding.

size: tuple[int, int]

Width and height of the image.

mode: str

A string which defines the type and depth of a pixel in the image: Pillow Modes

For currently supported modes by Pillow-Heif see Modes.

class pillow_heif.heif.HeifAuxImage(c_image)[source]

Bases: BaseImage

Class representing the auxiliary image associated with the HeifImage class.

property data

Decodes image and returns image data.

Returns:

bytes of the decoded image.

load() → None

Method to decode image.

Note

In normal cases, you should not call this method directly, when reading data or stride property of image will be loaded automatically.

property stride: int

Stride of the image.

Note

from 0.10.0 version this value always will have width * sizeof pixel in default usage mode.

Returns:

An Int value indicating the image stride after decoding.

to_pillow() → Image

Helper method to create Image class.

Returns:

Image class created from an image.

size: tuple[int, int]

Width and height of the image.

mode: str

A string which defines the type and depth of a pixel in the image: Pillow Modes

For currently supported modes by Pillow-Heif see Modes.