pillow-heif 0.1.11

Python 3.6+ interface to libheif library

pillow-heif

Library to work with HEIF files and an add-on for Pillow. Using the libheif library via CFFI.

Installation

From PyPi or Build from source

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	✅
PyPy 3.8 v7.3	✅	N/A	N/A	N/A	✅

* i686, x86_64, aarch64 wheels.

Versions 0.2.X will be last to support Python 3.6

Example of use as opener

from PIL import Image, ImageSequence
from pillow_heif import register_heif_opener

register_heif_opener()

image = Image.open('image.heic')
for frame in ImageSequence.Iterator(image):
    image.show()

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')
for img in heif_file:       # you still can use it without iteration, like before.
    image = Image.frombytes(
        img.mode,
        img.size,
        img.data,
        'raw',
        img.mode,
        img.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.
  • img_id - id of image, will be needed for encoding operations later.

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 - same dictionary as in HeifImageFile.info plus main - a boolean indicating is this a default picture.
• thumbnails - list of HeifThumbnail or UndecodedHeifThumbnail classes.
• top_lvl_images - list of UndecodedHeifFile or HeifFile classes, excluding main image.
• class supports len, iter and __getitem__:
  • len - returns number of top level images including main.
  • iter - returns a generator to iterate through all images, first image will be main.
  • __getitem__ - return image by index.
• other useful class methods:
  • thumbnails_all - returns an iterator to access thumbnails for all images in file.

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.

Thumbnails

To enable thumbnails, set thumbnails property in options to True:

import pillow_heif

pillow_heif.options().thumbnails = True
pillow_heif.options().thumbnails_autoload = True # if you wish
# or
pillow_heif.register_heif_opener(thumbnails=True, thumbnails_autoload=True)

The UndecodedHeifThumbnail object

• 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.
• img_id - id of thumbnail, will be needed for encoding operations later.

The HeifThumbnail object

You can enable thumbnail autoload by setting thumbnails_autoload property to True.

Also HeifThumbnail can be obtained by calling load method of UndecodedHeifThumbnail, UndecodedHeifFile or HeifImageFile.

HeifThumbnail has all properties of UndecodedHeifThumbnail plus filled data and stride.