# pyheif
Python 3.6+ interface to [libheif](https://github.com/strukturag/libheif) library using CFFI
*Note*: currently only reading is supported.
## Installation
### Simple installation - Linux (installs manylinux2014 wheel, doesn't work with Alpine)
```
pip install --upgrade pip
pip install pyheif
```
### Installing from source - MacOS
```
brew install libffi libheif
pip install git+https://github.com/carsales/pyheif.git
```
### Installing from source - Linux
```
apt install libffi libheif-dev libde265-dev
```
or
```
yum install libffi libheif-devel libde265-devel
```
then
```
pip install git+https://github.com/carsales/pyheif.git
```
### Installing from source - Windows
```
Sorry, not going to happen!
```
## Usage
### Read the primary image of a HEIF encoded file
The `pyheif.read(path_or_bytes)` function can be used to read the primary image of a HEIF encoded file. It can be passed any of the following:
* A string path to a file on disk
* A `pathlib.Path` path object
* A Python `bytes` or `bytearray` object containing HEIF content
* A file-like object with a `.read()` method that returns bytes
It returns a `HeifFile` object.
```python
import pyheif
# Using a file path:
heif_file = pyheif.read("IMG_7424.HEIC")
# Or using bytes directly:
heif_file = pyheif.read(open("IMG_7424.HEIC", "rb").read())
```
### Converting to a Pillow Image object
If your HEIF file contains an image that you would like to manipulate, you can do so using the [Pillow](https://pillow.readthedocs.io/) Python library. You can convert a `HeifFile` to a Pillow image like so:
```python
from PIL import Image
import pyheif
heif_file = pyheif.read("IMG_7424.HEIC")
image = Image.frombytes(
heif_file.mode,
heif_file.size,
heif_file.data,
"raw",
heif_file.mode,
heif_file.stride,
)
```
*Note*: the `mode` property is passed twice - once to the `mode` argument of the `frombytes` method, and again to the `mode` argument of the `raw` decoder.
You can now use any Pillow method to manipulate the file. Here's how to convert it to JPEG:
```python
image.save("IMG_7424.jpg", "JPEG")
```
### Read the entire container within the HEIF file
The `pyheif.open_container(path_or_bytes)` function can be used to read the HEIF container from a HEIF encoded file. It takes the same parameter as `pyheif.read()`
It returns a `HeifContainer` object.
## Objects
### The HeifFile object
The `HeifFile` has the following properties:
* `mode` - the image mode, e.g. "RGB" or "RGBA"
* `size` - the size of the image as a `(width, height)` tuple of integers
* `data` - the raw decoded file data, as bytes
* `metadata` - a list of metadata dictionaries
* `color_profile` - a color profile dictionary
* `stride` - the number of bytes in a row of decoded file data
* `bit_depth` - the number of bits in each component of a pixel
### The UndecodedHeifFile object
This is a HEIF image that has not been decoded. Calling the `UndecodedHeifFile.load()` method will load the data and the object will become a `HeifFile`
### The HeifContainer object
The `HeifContainer` has the following properties:
* `primary_image` - the `HeifTopLevelImage` object of the primary image in the file.
* `top_level_images` - a list of all `HeifTopLevelImage` objects in the file.
### The HeifTopLevelImage object
The `HeifTopLevelImage` has the following properties:
* `id` - the id of the image
* `image` - the `UndecodedHeifFile` or `HeifFile` object of the image
* `is_primary` - is this the primary image in the container
* `depth_image` - the `HeifDepthImage` if there is one
* `auxiliary_images` - a list of `HeifAuxiliaryImage` objects
### The HeifDepthImage object
The `HeifDepthImage` has the following properties:
* `id` - the id of the image
* `image` - the `UndecodedHeifFile` or `HeifFile` object of the image
### The HeifAuxiliaryImage object
The `HeifAuxiliaryImage` has the following properties:
* `id` - the id of the image
* `image` - the `UndecodedHeifFile` or `HeifFile` object of the image
* `type` - a string indicating the type of auxiliary image
Raw data
{
"_id": null,
"home_page": "https://github.com/carsales/pyheif",
"name": "pyheif",
"maintainer": "",
"docs_url": null,
"requires_python": ">= 3.6",
"maintainer_email": "",
"keywords": "heif heic",
"author": "Anthony Paes",
"author_email": "ant32bit-carsales@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/f3/2f/0492ad16c6936944bf9575a789e2dd6af4a27eb2475a04fb02cf84b2a5db/pyheif-0.7.1.tar.gz",
"platform": null,
"description": "# pyheif\nPython 3.6+ interface to [libheif](https://github.com/strukturag/libheif) library using CFFI\n\n*Note*: currently only reading is supported.\n\n## Installation\n\n### Simple installation - Linux (installs manylinux2014 wheel, doesn't work with Alpine)\n```\npip install --upgrade pip\npip install pyheif\n```\n\n### Installing from source - MacOS\n```\nbrew install libffi libheif\npip install git+https://github.com/carsales/pyheif.git\n```\n\n### Installing from source - Linux\n```\napt install libffi libheif-dev libde265-dev\n```\nor\n```\nyum install libffi libheif-devel libde265-devel\n```\nthen\n```\npip install git+https://github.com/carsales/pyheif.git\n```\n\n### Installing from source - Windows\n```\nSorry, not going to happen!\n```\n\n## Usage\n\n### Read the primary image of a HEIF encoded file\n\nThe `pyheif.read(path_or_bytes)` function can be used to read the primary image of a HEIF encoded file. It can be passed any of the following:\n\n* A string path to a file on disk\n* A `pathlib.Path` path object\n* A Python `bytes` or `bytearray` object containing HEIF content\n* A file-like object with a `.read()` method that returns bytes\n\nIt returns a `HeifFile` object.\n\n```python\nimport pyheif\n\n# Using a file path:\nheif_file = pyheif.read(\"IMG_7424.HEIC\")\n# Or using bytes directly:\nheif_file = pyheif.read(open(\"IMG_7424.HEIC\", \"rb\").read())\n```\n\n### Converting to a Pillow Image object\n\nIf your HEIF file contains an image that you would like to manipulate, you can do so using the [Pillow](https://pillow.readthedocs.io/) Python library. You can convert a `HeifFile` to a Pillow image like so:\n\n```python\nfrom PIL import Image\nimport pyheif\n\nheif_file = pyheif.read(\"IMG_7424.HEIC\")\nimage = Image.frombytes(\n heif_file.mode, \n heif_file.size, \n heif_file.data,\n \"raw\",\n heif_file.mode,\n heif_file.stride,\n )\n```\n\n*Note*: the `mode` property is passed twice - once to the `mode` argument of the `frombytes` method, and again to the `mode` argument of the `raw` decoder.\n\nYou can now use any Pillow method to manipulate the file. Here's how to convert it to JPEG:\n\n```python\nimage.save(\"IMG_7424.jpg\", \"JPEG\")\n```\n\n### Read the entire container within the HEIF file\n\nThe `pyheif.open_container(path_or_bytes)` function can be used to read the HEIF container from a HEIF encoded file. It takes the same parameter as `pyheif.read()`\n\nIt returns a `HeifContainer` object.\n\n## Objects\n\n### The HeifFile object\n\nThe `HeifFile` has the following properties:\n\n* `mode` - the image mode, e.g. \"RGB\" or \"RGBA\"\n* `size` - the size of the image as a `(width, height)` tuple of integers\n* `data` - the raw decoded file data, as bytes\n* `metadata` - a list of metadata dictionaries\n* `color_profile` - a color profile dictionary\n* `stride` - the number of bytes in a row of decoded file data\n* `bit_depth` - the number of bits in each component of a pixel\n\n### The UndecodedHeifFile object\n\nThis is a HEIF image that has not been decoded. Calling the `UndecodedHeifFile.load()` method will load the data and the object will become a `HeifFile`\n\n### The HeifContainer object\n\nThe `HeifContainer` has the following properties:\n\n* `primary_image` - the `HeifTopLevelImage` object of the primary image in the file.\n* `top_level_images` - a list of all `HeifTopLevelImage` objects in the file.\n\n### The HeifTopLevelImage object\n\nThe `HeifTopLevelImage` has the following properties:\n\n* `id` - the id of the image\n* `image` - the `UndecodedHeifFile` or `HeifFile` object of the image\n* `is_primary` - is this the primary image in the container\n* `depth_image` - the `HeifDepthImage` if there is one\n* `auxiliary_images` - a list of `HeifAuxiliaryImage` objects\n\n### The HeifDepthImage object\n\nThe `HeifDepthImage` has the following properties:\n\n* `id` - the id of the image\n* `image` - the `UndecodedHeifFile` or `HeifFile` object of the image\n\n### The HeifAuxiliaryImage object\n\nThe `HeifAuxiliaryImage` has the following properties:\n\n* `id` - the id of the image\n* `image` - the `UndecodedHeifFile` or `HeifFile` object of the image\n* `type` - a string indicating the type of auxiliary image\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Python 3.6+ interface to libheif library",
"version": "0.7.1",
"split_keywords": [
"heif",
"heic"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d2ce1514b625584616d401f8fad42037",
"sha256": "99c4df0588f65c1e4bb2a184338980e4810b70641f1df6414841c089f8273175"
},
"downloads": -1,
"filename": "pyheif-0.7.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "d2ce1514b625584616d401f8fad42037",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">= 3.6",
"size": 9836274,
"upload_time": "2022-12-05T00:01:07",
"upload_time_iso_8601": "2022-12-05T00:01:07.744698Z",
"url": "https://files.pythonhosted.org/packages/3e/8b/905c7b3dcd5405ddb582a67334eef9f3259108816547cb0bf3c213c2d821/pyheif-0.7.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "f2531d5e957825cf9cbce1702fa70b10",
"sha256": "1e55e36c9c704f86045122719be0b511ecb585c90c71fe9b7dbf602e37081686"
},
"downloads": -1,
"filename": "pyheif-0.7.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "f2531d5e957825cf9cbce1702fa70b10",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">= 3.6",
"size": 9836269,
"upload_time": "2022-12-05T00:01:49",
"upload_time_iso_8601": "2022-12-05T00:01:49.865924Z",
"url": "https://files.pythonhosted.org/packages/72/01/648e08f9a8e13dfc7d0a356f3d6ca8b00639012bb69f6bd16850abe96d93/pyheif-0.7.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "06f60525e1fdb351eb509f54334c8cf4",
"sha256": "d1b6a553028ae21cc874acdacf925585b163096d1d71311092b8f15b215c61ea"
},
"downloads": -1,
"filename": "pyheif-0.7.1-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "06f60525e1fdb351eb509f54334c8cf4",
"packagetype": "bdist_wheel",
"python_version": "cp36",
"requires_python": ">= 3.6",
"size": 9835868,
"upload_time": "2022-12-05T00:02:38",
"upload_time_iso_8601": "2022-12-05T00:02:38.410700Z",
"url": "https://files.pythonhosted.org/packages/f5/9f/c34c498c33c289a6bf3eaf4c6f473ad75b7cb9de66b691887f904596d943/pyheif-0.7.1-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "7d9989a0ca0124f4462463748034d8f2",
"sha256": "f7aa211959538954ceeb69d64c8910445f78fa7bf3da850dcdd3512b9342a417"
},
"downloads": -1,
"filename": "pyheif-0.7.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "7d9989a0ca0124f4462463748034d8f2",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">= 3.6",
"size": 9835855,
"upload_time": "2022-12-05T00:03:25",
"upload_time_iso_8601": "2022-12-05T00:03:25.740406Z",
"url": "https://files.pythonhosted.org/packages/22/d2/38b42481142a9f6947d423c88c959ee9715ffdb5e79620a0dc8be775c816/pyheif-0.7.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "3106306bbd4d46a0e9712b478ac10e7a",
"sha256": "7577c7d28f795145a549349fc7125f2ffa54ad9341b1db9701c0c86615a0f3ed"
},
"downloads": -1,
"filename": "pyheif-0.7.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "3106306bbd4d46a0e9712b478ac10e7a",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">= 3.6",
"size": 9836482,
"upload_time": "2022-12-05T00:04:06",
"upload_time_iso_8601": "2022-12-05T00:04:06.644131Z",
"url": "https://files.pythonhosted.org/packages/87/b0/e192ed0a6cfcbf5264fc4ec1c2d163a6a02406d83ee1f5cb92c744949956/pyheif-0.7.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "c329cc1150b09ee9a5d3a0c3ce84224d",
"sha256": "aa6e37ef23a8049225c7185c7a3fef66109c7f1c8e6ba7894f60d3689e2997ad"
},
"downloads": -1,
"filename": "pyheif-0.7.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "c329cc1150b09ee9a5d3a0c3ce84224d",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">= 3.6",
"size": 9836274,
"upload_time": "2022-12-05T00:04:31",
"upload_time_iso_8601": "2022-12-05T00:04:31.469332Z",
"url": "https://files.pythonhosted.org/packages/65/a6/3ea1ec2492629c66eddd14c2cebd08f886a72a38543e049479dbbee74ee1/pyheif-0.7.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "2fa54949052fef6209dda11a85ce1a17",
"sha256": "5cb43912f35ab0ad503d1d7dc974b93fde78248b3563d7ff665d2508b161ff27"
},
"downloads": -1,
"filename": "pyheif-0.7.1-pp37-pypy37_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "2fa54949052fef6209dda11a85ce1a17",
"packagetype": "bdist_wheel",
"python_version": "pp37",
"requires_python": ">= 3.6",
"size": 9744952,
"upload_time": "2022-12-05T00:05:14",
"upload_time_iso_8601": "2022-12-05T00:05:14.872633Z",
"url": "https://files.pythonhosted.org/packages/63/28/ca9589d9a576bf23fb1cff23add3138613674dc0eee076f2d98c7fc2d032/pyheif-0.7.1-pp37-pypy37_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "1496bfde16d9200825a0057eb2c96d18",
"sha256": "407d2ac679e0a093c11e9f6423de9692ab9b22ac0e18f51123d78e877cd049c8"
},
"downloads": -1,
"filename": "pyheif-0.7.1-pp38-pypy38_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "1496bfde16d9200825a0057eb2c96d18",
"packagetype": "bdist_wheel",
"python_version": "pp38",
"requires_python": ">= 3.6",
"size": 9744949,
"upload_time": "2022-12-05T00:05:46",
"upload_time_iso_8601": "2022-12-05T00:05:46.046814Z",
"url": "https://files.pythonhosted.org/packages/38/16/4e430b5f8761aba01d0aaa4f31c76dc88688fa1f09f885bb6a109a967811/pyheif-0.7.1-pp38-pypy38_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "9162c75e756b2f0a2e879f0b0b070c0d",
"sha256": "86a5c5174379d7146b5ed1a68892faf7268a135fb7f5039a011bfb7a6e903200"
},
"downloads": -1,
"filename": "pyheif-0.7.1.tar.gz",
"has_sig": false,
"md5_digest": "9162c75e756b2f0a2e879f0b0b070c0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">= 3.6",
"size": 22089,
"upload_time": "2022-12-05T00:15:02",
"upload_time_iso_8601": "2022-12-05T00:15:02.822714Z",
"url": "https://files.pythonhosted.org/packages/f3/2f/0492ad16c6936944bf9575a789e2dd6af4a27eb2475a04fb02cf84b2a5db/pyheif-0.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-05 00:15:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "carsales",
"github_project": "pyheif",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyheif"
}
JSON
