HeifFile object

The HeifFile provide all necessary methods for HEIF image manipulations.

class pillow_heif.HeifFile(fp=None, convert_hdr_to_8bit=True, bgr_mode=False, **kwargs)[source]

Representation of the HeifImage classes container.

To create HeifFile object, use the appropriate factory functions.

Exceptions that can be raised when working with methods:

ValueError, EOFError, SyntaxError, RuntimeError, OSError

property size

size property of the primary HeifImage.

Raises:

IndexError – If there are no images.

property mode

mode property of the primary HeifImage.

Raises:

IndexError – If there are no images.

property has_alpha

has_alpha property of the primary HeifImage.

Raises:

IndexError – If there are no images.

property premultiplied_alpha

premultiplied_alpha property of the primary HeifImage.

Raises:

IndexError – If there are no images.

property data

data property of the primary HeifImage.

Raises:

IndexError – If there are no images.

property stride

stride property of the primary HeifImage.

Raises:

IndexError – If there are no images.

property info

info` dict of the primary HeifImage in the container.

Raises:

IndexError – If there are no images.

to_pillow() Image[source]

Helper method to create Pillow Image.

Returns:

Image class created from the primary image.

save(fp, **kwargs) None[source]

Saves image(s) under the given fp.

Keyword options can be used to provide additional instructions to the writer. If a writer does not recognize an option, it is silently ignored.

Supported options:

save_all - boolean. Should all images from HeiFile be saved? (default = True)

append_images - do the same as in Pillow. Accepts the list of HeifImage

Note

Appended images always will have info["primary"]=False

quality - see QUALITY

enc_params - dictionary with key:value to pass to x265 encoder.

exif - override primary image’s EXIF with specified. Accepts None, bytes or PIL.Image.Exif class.

xmp - override primary image’s XMP with specified. Accepts None or bytes.

primary_index - ignore info["primary"] and set PrimaryImage by index.

chroma - custom subsampling value. Possible values: 444, 422 or 420 (x265 default).

subsampling - synonym for chroma. Format is string, compatible with Pillow: x:x:x, e.g. ‘4:4:4’.

save_nclx_profile - boolean, see SAVE_NCLX_PROFILE

matrix_coefficients - int, nclx profile: color conversion matrix coefficients, default=6 (see h.273)

color_primaries - int, nclx profile: color primaries (see h.273)

transfer_characteristic - int, nclx profile: transfer characteristics (see h.273)

full_range_flag - nclx profile: full range flag, default: 1

Parameters:

fp – A filename (string), pathlib.Path object or an object with write method.

add_frombytes(mode: str, size: tuple[int, int], data, **kwargs)[source]

Adds image from bytes to container.

Note

Supports stride value if needed.

Parameters:
  • mode – see Modes.

  • size – tuple with width and height of image.

  • data – bytes object with raw image data.

Returns:

HeifImage added object.

add_from_heif(image: HeifImage) HeifImage[source]

Add image to the container.

Parameters:

imageHeifImage class to add from.

Returns:

HeifImage added object.

add_from_pillow(image: Image) HeifImage[source]

Add image to the container.

Parameters:

image – Pillow Image class to add from.

Returns:

HeifImage added object.

get_aux_image(aux_id)[source]

get_aux_image` method of the primary HeifImage in the container.

Raises:

IndexError – If there are no images.