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:

python3 -m pip 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:

Building for first time will take a long time, if in your system cmake version >=3.16.1 is not present.
Arm7(32 bit):
- On Alpine you need additionally install aom and aom-dev packages.
- On Ubuntu(22.04+) you need additionally install libaom-dev package for AV1 codecs.
- On Ubuntu less then 22.04 you can compile it from source, but AV1 codecs will be not avalaible.

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.

aptalca / pillow_heif