HeifFile object — pillow-heif 0.22.0 documentation

# HeifFile object

The `HeifFile` provide all necessary methods for HEIF and AVIF image manipulations.

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

  Representation of the `HeifImage` classes container.

  To create `HeifFile` object, use the appropriate factory functions.

  - `open_heif()`

  - `read_heif()`

  - `from_pillow()`

  - `from_bytes()`

  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

    Helper method to create Pillow `Image`.

    Returns:

      `Image` class created from the primary image.

  save(fp, **kwargs) → None

    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’.

      `format` - string with encoder format name. Possible values: `HEIF` (default) or `AVIF`.

      `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)

    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

    Add image to the container.

    Parameters:

      image – `HeifImage` class to add from.

    Returns:

      `HeifImage` added object.

  add_from_pillow(image: Image) → HeifImage

    Add image to the container.

    Parameters:

      image – Pillow `Image` class to add from.

    Returns:

      `HeifImage` added object.

  get_aux_image(aux_id)

    get_aux_image` method of the primary `HeifImage` in the container.

    Raises:

      IndexError – If there are no images.