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["nominal_diffuse_white_luminance"]: int

Nominal diffuse white luminance(ndwt) in units of 0.0001 candelas per square metre. Can be absent; 0 is a valid value and selects the default definition of ISO/TS 22028-5. It is written back during save; remove the 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. Depth images that libheif cannot represent (an unsupported item type) are not listed. 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.

info["entity_groups"]: list

Entity groups(grpl) of the file the image was read from, every image of the file gets the same list. Absent when the file has no entity groups. Each group is a dict with keys:

  • id: int, the group ID

  • type: str, four-character group type, e.g. ster for a stereo pair

  • entities: list[int], item IDs of the group members in the order stored in the file. For ster the first one is the left view and the second one is the right view.

  • images: list[int | None], the same members as indexes of the images in HeifFile (frame numbers in Pillow) at the time the file was opened, None for members that are not top-level images

Note

Only group types known to libheif are reported, as of libheif 1.23 these are altr, ster and pymd. Entity groups are 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.

get_thumbnail(index: int) → HeifThumbnail[source]

Method to retrieve the thumbnail at the given position of info["thumbnails"].

Raises:

IndexError – If there is no thumbnail with such index.

Returns:

a HeifThumbnail 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.

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

Bases: BaseImage

Class representing the thumbnail of the HeifImage class.

info holds the bit_depth, chroma and color profile(icc_profile, icc_profile_type or nclx_profile) keys of the thumbnail, with the same meaning as in HeifImage.

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.