Public API — pillow-heif 0.22.0 documentation

# Public API

## Opening HEIF file

pillow_heif.is_supported(fp) → bool

  Checks if the given fp object contains a supported file type.

  Parameters:

    fp – A filename (string), pathlib.Path object or a file object. The file object must implement `file.read`, `file.seek`, and `file.tell` methods, and be opened in binary mode.

  Returns:

    A boolean indicating if the object can be opened.

pillow_heif.open_heif(fp, convert_hdr_to_8bit=True, bgr_mode=False, **kwargs) → HeifFile

  Opens the given HEIF(AVIF) image file.

  Parameters:

    - fp – See parameter `fp` in `is_supported()`

    - convert_hdr_to_8bit – Boolean indicating should 10 bit or 12 bit images be converted to 8-bit images during decoding. Otherwise, they will open in 16-bit mode. `Does not affect "monochrome" or "depth images".`

    - bgr_mode – Boolean indicating should be RGB(A) images be opened in BGR(A) mode.

    - kwargs – hdr_to_16bit a boolean value indicating that 10/12-bit image data should be converted to 16-bit mode during decoding. Has lower priority than convert_hdr_to_8bit! Default = True

  Returns:

    `HeifFile` object.

  Raises:

    - ValueError – invalid input data.

    - EOFError – corrupted image data.

    - SyntaxError – unsupported feature.

    - RuntimeError – some other error.

    - OSError – out of memory.

pillow_heif.read_heif(fp, convert_hdr_to_8bit=True, bgr_mode=False, **kwargs) → HeifFile

  Opens the given HEIF(AVIF) image file and decodes all images.

  Note

  In most cases it is better to call `open_heif()`, and let images decoded automatically only when needed.

  Parameters:

    - fp – See parameter `fp` in `is_supported()`

    - convert_hdr_to_8bit – Boolean indicating should 10 bit or 12 bit images be converted to 8-bit images during decoding. Otherwise, they will open in 16-bit mode. `Does not affect "monochrome" or "depth images".`

    - bgr_mode – Boolean indicating should be RGB(A) images be opened in BGR(A) mode.

    - kwargs – hdr_to_16bit a boolean value indicating that 10/12-bit image data should be converted to 16-bit mode during decoding. Has lower priority than convert_hdr_to_8bit! Default = True

  Returns:

    `HeifFile` object.

  Raises:

    - ValueError – invalid input data.

    - EOFError – corrupted image data.

    - SyntaxError – unsupported feature.

    - RuntimeError – some other error.

    - OSError – out of memory.

pillow_heif.from_pillow(pil_image: Image) → HeifFile

  Creates `HeifFile` from a Pillow Image.

  Parameters:

    pil_image – Pillow `Image` class.

  Returns:

    New `HeifFile` object.

pillow_heif.from_bytes(mode: str, size: tuple[int, int], data, **kwargs) → HeifFile

  Creates `HeifFile` from bytes.

  Note

  Supports `stride` value if needed.

  Parameters:

    - mode – see Modes.

    - size – tuple with `width` and `height` of an image.

    - data – bytes object with raw image data.

  Returns:

    New `HeifFile` object.

pillow_heif.encode(mode: str, size: tuple[int, int], data, fp, **kwargs) → None

  Encodes data in a `fp`.

  Parameters:

    - mode – BGR(A);16, RGB(A);16, LA;16`, L;16, I;16L, BGR(A), RGB(A), LA, L

    - size – tuple with `width` and `height` of an image.

    - data – bytes object with raw image data.

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

## Low Level API

pillow_heif.get_file_mimetype(fp) → str

  Gets the MIME type of the HEIF(or AVIF) object.

  Parameters:

    fp – A filename (string), pathlib.Path object, file object or bytes. The file object must implement `file.read`, `file.seek` and `file.tell` methods, and be opened in binary mode.

  Returns:

    “image/heic”, “image/heif”, “image/heic-sequence”, “image/heif-sequence”, “image/avif”, “image/avif-sequence” or “”.

pillow_heif.set_orientation(info: dict) → int | None

  Reset orientation in `EXIF` to `1` if any orientation present.

  Removes `XMP` orientation tag if it is present. In Pillow plugin mode, it is called automatically for images. When `pillow_heif` used in `standalone` mode, if you wish, you can call it manually.

  Note

  If there is no orientation tag, this function will not add it and do nothing.

  If both XMP and EXIF orientation tags are present, EXIF orientation tag will be returned, but both tags will be removed.

  Parameters:

    info – info dictionary from `Image` or `HeifImage`.

  Returns:

    Original orientation or None if it is absent.