pillow-heif 0.1.9

Python 3.6+ interface to libheif library

pillow_heif

A HEIF/HEIC/AVIF add-on for Pillow using the libheif library via CFFI.

Wheels table:

	macOS Intel	macOS Silicon	Windows 64bit	musllinux	manylinux
CPython 3.6	N/A	N/A	N/A	✅	✅
CPython 3.7	✅	N/A	✅	✅	✅
CPython 3.8	✅	N/A	✅	✅	✅
CPython 3.9	✅	✅	✅	✅	✅
CPython 3.10	✅	✅	✅	✅	✅
PyPy 3.7 v7.3	N/A	N/A	N/A	N/A	✅
PyPy 3.8 v7.3	N/A	N/A	N/A	N/A	✅

Note: CPython musllinux/manylinux wheels for i686, x64_86 and aarch64(arm8)

Versions 0.2.X will be last to support Python 3.6

Pull requests are greatly welcome.

Installation

(Recommended) From PyPi:

pip3 install pillow_heif

Installation from source

Linux

Debian(Ubuntu):

sudo apt install -y python3-pip libtool git cmake
sudo -H python3 -m pip install --upgrade pip
sudo -H python3 -m pip install pillow_heif

Alpine:

sudo apk --no-cache add py3-pip python3-dev libtool git gcc m4 perl alpine-sdk cmake
sudo apk --no-cache add fribidi-dev harfbuzz-dev jpeg-dev lcms2-dev openjpeg-dev
sudo -H python3 -m pip install --upgrade pip
sudo -H python3 -m pip install pillow_heif

See build_libs_linux for additional info what will happen during installing from source.

Notes:

1. Building for first time will take a long time, if in your system cmake version >=3.16.1 is not present.
2. Arm7(32 bit): On Alpine you need additionally install aom and aom-dev packages.
3. Arm7(32 bit): On Ubuntu(22.04+) you need additionally install libaom-dev package.
4. Arm7(32 bit): Ubuntu < 22.04 is not supported currently.

MacOS

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install x265 libjpeg libde265 libheif
pip3 install --no-binary pillow_heif

Windows

vcpkg install aom libheif --triplet=x64-windows
VCPKG_PREFIX="path_to:vcpkg/installed/x64-windows"
pip3 install --no-binary pillow_heif

Example of use as opener

from PIL import Image
from pillow_heif import register_heif_opener

register_heif_opener()

image = Image.open('image.heic')
image.load()

Example of use as reader

from PIL import Image
import pillow_heif


if not pillow_heif.is_supported('ABC.HEIC'):
  exit(0)
heif_file = pillow_heif.read_heif('ABC.HEIC')
image = Image.frombytes(
    heif_file.mode,
    heif_file.size,
    heif_file.data,
    'raw',
    heif_file.mode,
    heif_file.stride,
)

More examples

The HeifImageFile object (as Pillow plugin)

The returned HeifImageFile by Pillow function Image.open has the following additional properties beside regular:

• info dictionary keys:
  • brand - value from int enum HeifBrand.
  • exif - exif data or None.
  • metadata - is a list of dictionaries with type and data keys, excluding exif. May be empty.
  • color_profile - is a dictionary with type and data keys. May be empty.
  • icc_profile - contains data and present only when file has ICC color profile(prof or rICC).
  • nclx_profile - contains data and present only when file has NCLX color profile.

An UndecodedHeifFile object

The returned UndecodedHeifFile by function open_heif has the following properties:

• size - the size of the image as a (width, height) tuple of integers.
• has_alpha - is a boolean indicating the presence of an alpha channel.
• mode - the image mode, e.g. 'RGB' or 'RGBA'.
• bit_depth - the number of bits in each component of a pixel.
• data - the raw decoded file data, as bytes. Contains None until load method is called.
• stride - the number of bytes in a row of decoded file data. Contains None until load method is called.
• info dictionary with the same content as in HeifImageFile.info.

The HeifFile object

HeifFile can be obtained by calling load method of UndecodedHeifFile or by calling read_heif function. HeifFile has all properties of UndecodedHeifFile plus filled data and stride.