https://github.com/bigcat88/pillow_heif
Python library for working with HEIF images and plugin for Pillow.
https://github.com/bigcat88/pillow_heif
avif heic heif opencv pillow python python3
Last synced: 4 months ago
JSON representation
Python library for working with HEIF images and plugin for Pillow.
- Host: GitHub
- URL: https://github.com/bigcat88/pillow_heif
- Owner: bigcat88
- License: bsd-3-clause
- Created: 2021-09-10T16:24:22.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-05-09T16:40:37.000Z (about 1 year ago)
- Last Synced: 2025-05-09T17:44:24.322Z (about 1 year ago)
- Topics: avif, heic, heif, opencv, pillow, python, python3
- Language: Python
- Homepage:
- Size: 63.4 MB
- Stars: 250
- Watchers: 1
- Forks: 19
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# pillow-heif
[](https://github.com/bigcat88/pillow_heif/actions/workflows/analysis-coverage.yml)
[](https://github.com/bigcat88/pillow_heif/actions/workflows/nightly-src-build.yml)
[](https://pillow-heif.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/bigcat88/pillow_heif)
[](https://pepy.tech/project/pillow-heif)
[](https://pepy.tech/project/pillow-heif)
Python bindings to [libheif](https://github.com/strukturag/libheif) for working with HEIF images and plugin for Pillow.
Features:
* Decoding of `8`, `10`, `12` bit HEIC files.
* Encoding of `8`, `10`, `12` bit HEIC files.
* `EXIF`, `XMP`, `IPTC` read & write support.
* Support of multiple images in one file and a `PrimaryImage` attribute.
* Adding & removing `thumbnails`.
* Reading of `Depth Images`.
* (beta) Reading of `Auxiliary Images` by [johncf](https://github.com/johncf)
* Adding HEIF support to Pillow in one line of code as a plugin.
Note: Here is a light version [pi-heif](https://pypi.org/project/pi-heif/) of this project without encoding capabilities.
### Install
```console
python3 -m pip install -U pip
python3 -m pip install pillow-heif
```
### Example of use as a Pillow plugin
```python3
from PIL import Image
from pillow_heif import register_heif_opener
register_heif_opener()
im = Image.open("image.heic") # do whatever need with a Pillow image
im = im.rotate(13)
im.save(f"rotated_image.heic", quality=90)
```
### 16 bit PNG to 10 bit HEIF using OpenCV
```python3
import cv2
import pillow_heif
cv_img = cv2.imread("16bit_with_alpha.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)
)
heif_file.save("RGBA_10bit.heic", quality=-1)
```
### 8/10/12 bit HEIF to 8/16 bit PNG using OpenCV
```python3
import numpy as np
import cv2
import pillow_heif
heif_file = pillow_heif.open_heif("image.heic", convert_hdr_to_8bit=False, bgr_mode=True)
np_array = np.asarray(heif_file)
cv2.imwrite("image.png", np_array)
```
### Accessing decoded image data
```python3
import pillow_heif
if pillow_heif.is_supported("image.heic"):
heif_file = pillow_heif.open_heif("image.heic", convert_hdr_to_8bit=False)
print("image size:", heif_file.size)
print("image mode:", heif_file.mode)
print("image data length:", len(heif_file.data))
print("image data stride:", heif_file.stride)
```
### Get decoded image data as a Numpy array
```python3
import numpy as np
import pillow_heif
if pillow_heif.is_supported("input.heic"):
heif_file = pillow_heif.open_heif("input.heic")
np_array = np.asarray(heif_file)
```
### Accessing Depth Images
```python3
from PIL import Image
from pillow_heif import register_heif_opener
import numpy as np
register_heif_opener()
im = Image.open("../tests/images/heif_other/pug.heic")
if im.info["depth_images"]:
depth_im = im.info["depth_images"][0] # Access the first depth image (usually there will be only one).
# Depth images are instances of `class HeifDepthImage(BaseImage)`,
# so work with them as you would with any usual image in pillow_heif.
# Depending on what you need the depth image for, you can convert it to a NumPy array or convert it to a Pillow image.
pil_im = depth_im.to_pillow()
np_im = np.asarray(depth_im)
print(pil_im)
print(pil_im.info["metadata"])
```
### More Information
- [Documentation](https://pillow-heif.readthedocs.io/)
- [Installation](https://pillow-heif.readthedocs.io/en/latest/installation.html)
- [Pillow plugin](https://pillow-heif.readthedocs.io/en/latest/pillow-plugin.html)
- [Using HeifFile](https://pillow-heif.readthedocs.io/en/latest/heif-file.html)
- [Image modes](https://pillow-heif.readthedocs.io/en/latest/image-modes.html)
- [Options](https://pillow-heif.readthedocs.io/en/latest/options.html)
- [Examples](https://github.com/bigcat88/pillow_heif/tree/master/examples)
- [Contribute](https://github.com/bigcat88/pillow_heif/blob/master/.github/CONTRIBUTING.md)
- [Discussions](https://github.com/bigcat88/pillow_heif/discussions)
- [Issues](https://github.com/bigcat88/pillow_heif/issues)
- [Changelog](https://github.com/bigcat88/pillow_heif/blob/master/CHANGELOG.md)
### Wheels
| **_Wheels table_** | macOS
Intel | macOS
Silicon | Windows
| musllinux* | manylinux* |
|--------------------|:---------------:|:-----------------:|:------------:|:----------:|:----------:|
| CPython 3.10 | ✅ | ✅ | ✅ | ✅ | ✅ |
| CPython 3.11 | ✅ | ✅ | ✅ | ✅ | ✅ |
| CPython 3.12 | ✅ | ✅ | ✅ | ✅ | ✅ |
| CPython 3.13 | ✅ | ✅ | ✅ | ✅ | ✅ |
| CPython 3.14 | ✅ | ✅ | ✅ | ✅ | ✅ |
| CPython 3.14t | ✅ | ✅ | ✅ | ✅ | ✅ |
| PyPy 3.11 v7.3 | ✅ | ✅ | ✅ | N/A | ✅ |
* **x86_64**, **aarch64** wheels.