Pillow-Heif

https://pillow-heif.readthedocs.io/en/latest/
Admin
Pillow-Heif is a Python library for reading and writing HEIF image files, functioning either as a...
Tokens:59,110
Snippets:435
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example of use

Source: https://pillow-heif.readthedocs.io/en/latest/options.html

Example of setting multiple options at once.

```APIDOC
## Example of use

### Description
Example showing how to set multiple options at once.

### Example
```python
import pillow_heif

pillow_heif.options.THUMBNAILS = False
pillow_heif.options.DECODE_THREADS = 1
```
```

--------------------------------

### Install Pillow-Heif from source on FreeBSD

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Install Pillow-Heif from the source directory on FreeBSD.

```bash
python3 -m pip install .
```

--------------------------------

### Install Pillow-Heif with pip

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Recommended way to install Pillow-Heif. Upgrades pip first, then installs pillow-heif.

```bash
python3 -m pip install --upgrade pip
python3 -m pip install --upgrade pillow-heif
```

--------------------------------

### Install Pillow-Heif from source directory

Source: https://pillow-heif.readthedocs.io/en/latest/installation.html

Installs Pillow-Heif from within the uncompressed source directory.

```bash
python3 -m pip install .

```

--------------------------------

### Install Pillow-Heif from source with --no-binary

Source: https://pillow-heif.readthedocs.io/en/latest/installation.html

Installs Pillow-Heif from source, forcing a source build rather than using binary wheels.

```bash
python3 -m pip install --upgrade pillow-heif --no-binary :all:

```

--------------------------------

### Install Pillow-Heif from source (Linux)

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Install Pillow-Heif from source using pip with --no-binary :all: or from the source directory.

```bash
python3 -m pip install --upgrade pillow-heif --no-binary :all:
```

```bash
python3 -m pip install .
```

--------------------------------

### Install Pillow-Heif from source on Windows

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Install Pillow-Heif from source using pip in the Pillow-Heif directory.

```bash
python -m pip install .
```

--------------------------------

### Install dependencies on macOS

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Install Homebrew packages and upgrade pip before installing Pillow-Heif from source.

```bash
brew install x265 libjpeg libde265 libheif
python3 -m pip install --upgrade pip
```

--------------------------------

### Install dependencies and build libheif on FreeBSD

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to install required packages and build libheif on FreeBSD.

```bash
- pkg install -y gcc cmake aom x265
- pkg install -y py39-pip
- pkg install -y py39-pillow py39-numpy
- python3 libheif/build_libs.py
```

--------------------------------

### Install dependencies on macOS with Homebrew

Source: https://pillow-heif.readthedocs.io/en/latest/installation.html

Installs required libraries and upgrades pip on macOS.

```bash
brew install x265 libjpeg libde265 libheif
python3 -m pip install --upgrade pip

```

--------------------------------

### Install Python and Pillow on FreeBSD

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to install Python and Pillow packages on FreeBSD.

```bash
pkg install -y py39-pip
pkg install -y py39-pillow
```

--------------------------------

### Build libheif on Ubuntu

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to install build dependencies and build libheif using the provided build script on Ubuntu.

```bash
sudo apt update
sudo apt -y install cmake nasm build-essential curl
sudo python3 libheif/build_libs.py
```

--------------------------------

### Build libheif on Alpine

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to install build dependencies and build libheif using the provided build script on Alpine.

```bash
sudo apk add --no-cache cmake nasm build-base curl
sudo python3 libheif/build_libs.py
```

--------------------------------

### Build libheif on Windows with msys2

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to build and install libheif using msys2 terminal.

```bash
cd .../pillow_heif/libheif/windows/mingw-w64-libheif
makepkg-mingw --syncdeps
pacman -U mingw-w64-x86_64-libheif-*-any.pkg.tar.zst
```

--------------------------------

### Save HeifFile to file

Source: https://pillow-heif.readthedocs.io/en/latest/heif-file.html

Saves the HeifFile to a file using save(). The example uses quality=-1. Refer to save() for additional parameters and to the Saving images section.

```python
heif_file.save("output.heif", quality=-1)

```

--------------------------------

### Create HeifFile from bytes with OpenCV

Source: https://pillow-heif.readthedocs.io/en/latest/heif-file.html

Creates a HeifFile from raw bytes using pillow_heif.from_bytes. The example reads a 16-bit PNG with OpenCV and passes its mode, size, and byte data.

```python
import cv2  # OpenCV

cv_img = cv2.imread("image_16bit.png", cv2.IMREAD_UNCHANGED)
heif_file = pillow_heif.from_bytes(
    mode="BGRA;16",
    size=(cv_img.shape[1], cv_img.shape[0]),
    data=bytes(cv_img)
)

```

--------------------------------

### Override multiple options when registering plugin

Source: https://pillow-heif.readthedocs.io/en/latest/options.html

Example of passing multiple options to register_heif_opener() to override defaults when registering the Pillow plugin. This sets thumbnails to False, quality to 100, and decode_threads to 10.

```python
register_heif_opener(thumbnails=False, quality=100, decode_threads=10)

```

--------------------------------

### Get numpy array of image by index

Source: https://pillow-heif.readthedocs.io/en/latest/heif-file.html

Gets the decoded image data as a numpy array for a specific image index (for multi-frame images).

```python
heif_file = pillow_heif.open_heif("file.heif")
np_array = np.asarray(heif_file[0])     # accessing image by index.

```

--------------------------------

### Get numpy array of primary image

Source: https://pillow-heif.readthedocs.io/en/latest/heif-file.html

Gets the decoded primary image data as a numpy array using np.asarray(heif_file). The array format matches what Pillow would produce.

```python
heif_file = pillow_heif.open_heif("file.heif")
np_array = np.asarray(heif_file)

```

--------------------------------

### _LibHeifImageFile.load_prepare method

Source: https://pillow-heif.readthedocs.io/en/latest/_modules/pillow_heif/as_plugin.html

Prepares image memory before loading, recreating the core image when size or mode changed due to seek or draft. Required for Pillow 11+ behavior.

```python
def load_prepare(self) -> None:
    # Pillow 11+ creates the image memory only when there is none, `seek` and `draft` can change the size or mode
    if self._im is not None and (self.im.size != self.size or self.im.mode != self.mode):
        self.im = Image.core.new(self.mode, self.size)  # pylint: disable=too-many-function-args
    super().load_prepare()
```

--------------------------------

### Overriding multiple options at once

Source: https://pillow-heif.readthedocs.io/en/latest/options.html

Example of overriding multiple options when registering the Pillow plugin.

```APIDOC
## Overriding multiple options at once

### Description
When registering a Pillow plugin with `pillow_heif.register_heif_opener()`, you can pass multiple options at once.

### Example
```python
register_heif_opener(thumbnails=False, quality=100, decode_threads=10)
```
```

--------------------------------

### open

Source: https://pillow-heif.readthedocs.io/en/latest/_modules/pillow_heif/heif.html

Opens an image file and returns a HeifFile object. The image data is loaded lazily; call load() on each image to decode it.

```APIDOC
## open

### Description
Opens an image file and returns a HeifFile object. The image data is loaded lazily; call load() on each image to decode it.

### Method
open

### Parameters
- **fp** - See parameter fp in is_supported.
- **convert_hdr_to_8bit** (boolean) - Optional - Indicates whether 10-bit or 12-bit images should be converted to 8-bit during decoding. Otherwise, they will open in 16-bit mode. Does not affect monochrome or depth images.
- **bgr_mode** (boolean) - Optional - Indicates whether RGB(A) images should be opened in BGR(A) mode.
- **kwargs** - Optional - Additional keyword arguments. Supports hdr_to_16bit: a boolean 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 is True.

### Returns
- HeifFile object.

### Exceptions
- ValueError: invalid input data.
- EOFError: corrupted image data.
- SyntaxError: unsupported feature.
- RuntimeError: some other error.
- OSError: out of memory.
```

--------------------------------

### Create HEIC with primary image index

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/pillow-plugin.rst.txt

Opens three PNG images and saves them as a HEIC file with the second image as primary using primary_index=1 and quality=-1.

```python
img1 = Image.open(Path("images/jpeg_gif_png/1.png"))
img2 = Image.open(Path("images/jpeg_gif_png/2.png"))
img3 = Image.open(Path("images/jpeg_gif_png/3.png"))
img1.save("1_2P_3.heic", append_images=[img2, img3], save_all=True, primary_index=1, quality=-1)
```

--------------------------------

### Manual plugin registration with register_heif_opener

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/pillow-plugin.rst.txt

Registers the plugin manually by calling register_heif_opener() before opening a HEIC image and saving a rotated version.

```python
from PIL import Image
from pillow_heif import register_heif_opener

register_heif_opener()
with Image.open("image.heic") as im:
    im.rotate(45).save("rotated_image.heic")
```

--------------------------------

### pillow_heif.get_file_mimetype

Source: https://pillow-heif.readthedocs.io/en/latest/reference/API.html

Gets the MIME type of the HEIF or AVIF object. Returns one of the recognized MIME strings or an empty string if not recognized.

```APIDOC
## get_file_mimetype

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

### Method
Function

### Signature
`pillow_heif.get_file_mimetype(_fp_) → str`

### Parameters
- **fp** - string, pathlib.Path, file object, or bytes - Required - 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 “”.

```

--------------------------------

### Access primary image data

Source: https://pillow-heif.readthedocs.io/en/latest/heif-file.html

Accesses the decoded data of the primary image via the data property. The example prints the length of the data.

```python
print(len(heif_file.data))

```

--------------------------------

### _output_nclx_params: compute NCLX color parameters

Source: https://pillow-heif.readthedocs.io/en/latest/_modules/pillow_heif/misc.html

Returns NCLX color parameters (primaries, transfer, matrix, full range) for saving. Uses existing profile, explicit kwargs, or libheif sRGB defaults (1, 13, 6, 1) when saving is enabled and no profile or explicit parameters are given. Falls back to -1 values otherwise.

```python
def _output_nclx_params(kwargs: dict, nclx_profile=None) -> tuple[int, int, int, int]:
    nclx_keys = ("color_primaries", "transfer_characteristics", "matrix_coefficients", "full_range_flag")
    save_nclx = kwargs.get("save_nclx_profile", options.SAVE_NCLX_PROFILE)
    has_explicit_nclx = any(k in kwargs for k in nclx_keys)
    if save_nclx and nclx_profile and not has_explicit_nclx:
        return (
            nclx_profile["color_primaries"],
            nclx_profile["transfer_characteristics"],
            nclx_profile["matrix_coefficients"],
            nclx_profile["full_range_flag"],
        )
    # When NCLX saving is enabled and no existing NCLX profile is on the image and no explicit NCLX parameters
    # were provided, write an NCLX box that matches libheif internal sRGB encoding defaults.
    # Without this, no NCLX box is written and viewers must guess the color space, which causes color shifts.
    # See issue #365.
    # Values match libheif nclx_profile::set_sRGB_defaults() exactly:
    #   primaries=1 (BT.709)
    #   transfer=13 (sRGB)
    #   matrix=6 (BT.601-6)
    #   full_range=1
    if save_nclx and not kwargs.get("nclx_profile") and not has_explicit_nclx:
        return 1, 13, 6, 1
    return (
        kwargs.get("color_primaries", -1),
        kwargs.get("transfer_characteristics", -1),
        kwargs.get("matrix_coefficients", -1),
        kwargs.get("full_range_flag", -1),
    )
```

--------------------------------

### Pass multiple config values to register_heif_opener

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/pillow-plugin.rst.txt

Passes multiple configuration values to register_heif_opener at once, disabling thumbnails and setting quality to -1.

```python
register_heif_opener(thumbnails=False, quality=-1)
```

--------------------------------

### Set global options: THUMBNAILS and DECODE_THREADS

Source: https://pillow-heif.readthedocs.io/en/latest/options.html

Example of setting pillow_heif options globally by assigning to the options attributes. This disables thumbnails and sets decode threads to 1.

```python
import pillow_heif

pillow_heif.options.THUMBNAILS = False
pillow_heif.options.DECODE_THREADS = 1

```

--------------------------------

### _LibHeifImageFile class and _open method

Source: https://pillow-heif.readthedocs.io/en/latest/_modules/pillow_heif/as_plugin.html

Base Pillow plugin class that opens a HEIF file via HeifFile, converting HDR to 8-bit and 16-bit, and raising SyntaxError on decode failures. Initializes frame state, custom mimetype, and clears the tile list.

```python
class _LibHeifImageFile(ImageFile.ImageFile):
    """Base class with all functionality for ``HeifImageFile`` class."""

    _heif_file: HeifFile | None = None
    _close_exclusive_fp_after_loading = True
    _mode: str

    def __init__(self, *args, **kwargs):
        self.__frame = 0
        self.__thumbnail: HeifThumbnail | None = None
        self.__loaded = False
        super().__init__(*args, **kwargs)

    def _open(self):
        try:
            # when Pillow starts supporting 16-bit multichannel images change `convert_hdr_to_8bit` to False
            heif_file = HeifFile(self.fp, convert_hdr_to_8bit=True, hdr_to_16bit=True, remove_stride=False)
        except (OSError, ValueError, SyntaxError, RuntimeError, EOFError) as exception:
            raise SyntaxError(str(exception)) from None
        self.custom_mimetype = heif_file.mimetype
        self._heif_file = heif_file
        self.__frame = heif_file.primary_index
        self._init_from_heif_file(self.__frame)
        self.tile = []
```

--------------------------------

### Orientation helper functions (_get_orientation_for_encoder, _get_orientation_xmp, _get_orientation)

Source: https://pillow-heif.readthedocs.io/en/latest/_modules/pillow_heif/misc.html

Internal functions that parse EXIF and XMP orientation tags. _get_orientation returns the original orientation (or None) and optionally resets it to 1 in the info dictionary. _get_orientation_xmp handles XMP orientation and resets it if requested. _get_orientation_for_encoder returns 1 when no orientation is found.

```python
def _get_orientation_for_encoder(info: dict) -> int:
    image_orientation = _get_orientation(info, False)
    return 1 if image_orientation is None else image_orientation


def _get_orientation_xmp(info: dict, exif_orientation: int | None, reset: bool = False) -> int | None:
    xmp_orientation = 1
    if info.get("xmp"):
        xmp_data = info["xmp"].rsplit(b"\x00", 1)
        if xmp_data[0]:
            decoded_xmp_data = None
            for encoding in ("utf-8", "latin1"):
                try:
                    decoded_xmp_data = xmp_data[0].decode(encoding)
                    break
                except Exception:  # noqa # pylint: disable=broad-except
                    pass
            if decoded_xmp_data:
                match = re.search(r'tiff:Orientation(="|>)([0-9])', decoded_xmp_data)
                if match:
                    xmp_orientation = int(match[2])
                    if reset:
                        decoded_xmp_data = re.sub(r'tiff:Orientation="([0-9])"', "", decoded_xmp_data)
                        decoded_xmp_data = re.sub(r"<tiff:Orientation>([0-9])</tiff:Orientation>", "", decoded_xmp_data)
                # should encode in "utf-8" anyway, as `defusedxml` do not work with `latin1` encoding.
                if encoding != "utf-8" or xmp_orientation != 1:
                    info["xmp"] = b"".join([decoded_xmp_data.encode("utf-8"), b"\x00" if len(xmp_data) > 1 else b""])
    return xmp_orientation if exif_orientation is None and xmp_orientation != 1 else None


def _get_orientation(info: dict, reset: bool = False) -> int | None:
    original_orientation = None
    if info.get("exif"):
        try:
            tif_tag = info["exif"]
            skipped_exif00 = False
            if tif_tag.startswith(b"Exif\x00\x00"):
                skipped_exif00 = True
                tif_tag = tif_tag[6:]
            endian_mark = "<" if tif_tag[0:2] == b"\x49\x49" else ">"
            pointer = unpack(endian_mark + "L", tif_tag[4:8])[0]
            tag_count = unpack(endian_mark + "H", tif_tag[pointer : pointer + 2])[0]
            offset = pointer + 2
            for tag_n in range(tag_count):
                pointer = offset + 12 * tag_n
                if unpack(endian_mark + "H", tif_tag[pointer : pointer + 2])[0] != 274:
                    continue
                value = tif_tag[pointer + 8 : pointer + 12]
                t_original_orientation = unpack(endian_mark + "H", value[0:2])[0]
                if t_original_orientation != 1:
                    original_orientation = t_original_orientation
                    if not reset:
                        break
                    p_value = pointer + 8
                    if skipped_exif00:
                        p_value += 6
                    new_orientation = pack(endian_mark + "H", 1)
                    info["exif"] = info["exif"][:p_value] + new_orientation + info["exif"][p_value + 2 :]
                    break
        except Exception:  # noqa # pylint: disable=broad-except
            pass
    xmp_orientation = _get_orientation_xmp(info, original_orientation, reset=reset)
    return xmp_orientation or original_orientation
```

--------------------------------

### Encode image to HEIF with pillow_heif.encode

Source: https://pillow-heif.readthedocs.io/en/latest/heif-file.html

Encodes a raw image (read with OpenCV) directly to a HEIF file using pillow_heif.encode. The example uses mode="BGRA;16" and quality=-1.

```python
cv_img = cv2.imread("images/non_heif/RGBA_16__128x128.png", cv2.IMREAD_UNCHANGED)
pillow_heif.encode(
   mode="BGRA;16",
   size=(cv_img.shape[1], cv_img.shape[0]),
   data=bytes(cv_img),
   fp="RGBA_10bit.heic",
   quality=-1)

```

--------------------------------

### Get embedded thumbnail

Source: https://pillow-heif.readthedocs.io/en/latest/heif-file.html

Decodes an embedded thumbnail without decoding the full image. Checks info["thumbnails"] for available sizes, then uses get_thumbnail(0) on the primary image and converts to a Pillow image.

```python
heif_file = pillow_heif.open_heif("image.heif")
if heif_file.info["thumbnails"]:
    thumbnail = heif_file[0].get_thumbnail(0)
    print(thumbnail.size, thumbnail.mode)
    pil_image = thumbnail.to_pillow()

```

--------------------------------

### Add all images from another HeifFile

Source: https://pillow-heif.readthedocs.io/en/latest/heif-file.html

Adds all images from a second HEIF file to the current HeifFile using add_from_heif.

```python
heif_file_to_add = pillow_heif.open_heif("file2.heif")
heif_file.add_from_heif(heif_file_to_add)

```

--------------------------------

### size property

Source: https://pillow-heif.readthedocs.io/en/latest/reference/HeifImage.html

Width and height of the image.

```APIDOC
## size property

### Description
Width and height of the image.

### Returns
`tuple[int, int]`

```

--------------------------------

### Edit info["exif"] in place

Source: https://pillow-heif.readthedocs.io/en/latest/_sources/pillow-plugin.rst.txt

Edits info["exif"] in place for each frame and saves the modified image with save_all=True.

```python
heic_pillow = Image.open(Path("test.heic"))
for frame in ImageSequence.Iterator(heic_pillow):
    frame.info["exif"] = None
heic_pillow.save("no_exif.heic", save_all=True)
```

--------------------------------

### _LibHeifImageFile.draft method

Source: https://pillow-heif.readthedocs.io/en/latest/_modules/pillow_heif/as_plugin.html

Selects an embedded thumbnail for draft decoding, ignoring the requested mode and choosing the smallest thumbnail not smaller than size that matches the image's properties. Returns (mode, box) when a thumbnail is selected, otherwise None.

```python
def draft(self, mode: str | None, size: tuple[int, int] | None) -> tuple[str, tuple[int, int, float, float]] | None:
    """Configures the loader to decode an embedded thumbnail instead of the image.

    The smallest thumbnail that is not smaller than ``size`` and is a scaled copy of the image (same mode,
    aspect ratio, crop, rotation and mirroring, no other color profile) is selected, ``mode`` is ignored.
    :external:py:meth:`~PIL.Image.Image.thumbnail` calls this with ``size`` multiplied by its ``reducing_gap``.

    :returns: ``(mode, box)`` when a thumbnail was selected, ``None`` otherwise.
    """
    if not size or not self._heif_file or self.__loaded or self.__thumbnail:
        return None
    thumbnail = _thumbnail_for_size(self._heif_file[self.tell()], size)
    if thumbnail is None:
        return None
    self.__thumbnail = thumbnail
    self._size = thumbnail.size
    self._mode = thumbnail.mode
    return self.mode, (0, 0, *thumbnail.size)
```

--------------------------------

### load_libheif_plugin function

Source: https://pillow-heif.readthedocs.io/en/latest/_modules/pillow_heif/misc.html

Loads a specified LibHeif plugin by delegating to `_pillow_heif.load_plugin`. The `plugin_path` can be a string or `Path`.

```python
def load_libheif_plugin(plugin_path: str | Path) -> None:
    """Load specified LibHeif plugin."""
    _pillow_heif.load_plugin(plugin_path)
```

--------------------------------

### _LibHeifImageFile.load method

Source: https://pillow-heif.readthedocs.io/en/latest/_modules/pillow_heif/as_plugin.html

Loads the current frame's raw data, updating size and mode, and closes the exclusive file pointer after decoding. Handles truncated images when ImageFile.LOAD_TRUNCATED_IMAGES is enabled, and releases the HeifFile for non-animated images.

```python
def load(self):
    if self._heif_file and not self.__loaded:
        frame_heif = self.__thumbnail or self._heif_file[self.tell()]
        try:
            data = frame_heif.data  # Size of Image can change during decoding
            self._size = frame_heif.size  # noqa
            self.load_prepare()
            self.frombytes(data, "raw", (frame_heif.mode, frame_heif.stride))
        except (EOFError, ValueError):
            if not ImageFile.LOAD_TRUNCATED_IMAGES:
                raise
            self.load_prepare()
        self.__loaded = True
        # In any case, we close `fp`, since the input data bytes are held by the `HeifFile` class.
        if self.fp and getattr(self, "_exclusive_fp", False) and hasattr(self.fp, "close"):
            self.fp.close()
        self.fp = None
        if not self.is_animated:
            self._heif_file = None
            self.__thumbnail = None
    return super().load()
```
Tokens:
Raw