# 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 `HeifImage` 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 `HeifImage` 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 HeifImage object
The `HeifImage` 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 UndecodedHeifImage object
This is a HEIF image that has not been decoded. Calling the `UndecodedHeifImage.load()` method will load the data and the object will become a `HeifImage`
### 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 `UndecodedHeifImage` or `HeifImage` 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 `UndecodedHeifImage` or `HeifImage` object of the image
### The HeifAuxiliaryImage object
The `HeifAuxiliaryImage` has the following properties:
* `id` - the id of the image
* `image` - the `UndecodedHeifImage` or `HeifImage` 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": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "heif heic",
"author": "Anthony Paes",
"author_email": "ant32bit-carsales@users.noreply.github.com",
"download_url": null,
"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 `HeifImage` 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 `HeifImage` 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 HeifImage object\n\nThe `HeifImage` 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 UndecodedHeifImage object\n\nThis is a HEIF image that has not been decoded. Calling the `UndecodedHeifImage.load()` method will load the data and the object will become a `HeifImage`\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 `UndecodedHeifImage` or `HeifImage` 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 `UndecodedHeifImage` or `HeifImage` 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 `UndecodedHeifImage` or `HeifImage` object of the image\n* `type` - a string indicating the type of auxiliary image\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python 3.6+ interface to libheif library",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/carsales/pyheif"
},
"split_keywords": [
"heif",
"heic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "529840d97d38454f6708db7b819b8c206e206e4730183860b3a3be56fa44cdab",
"md5": "d8f1fc8d85b5f95faf27fb158b896df1",
"sha256": "6a9df316c695c7a4588633486c5f93508474653488dbcb8c968dc0c611875106"
},
"downloads": -1,
"filename": "pyheif-0.8.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "d8f1fc8d85b5f95faf27fb158b896df1",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.6",
"size": 5382401,
"upload_time": "2024-09-01T03:24:50",
"upload_time_iso_8601": "2024-09-01T03:24:50.009825Z",
"url": "https://files.pythonhosted.org/packages/52/98/40d97d38454f6708db7b819b8c206e206e4730183860b3a3be56fa44cdab/pyheif-0.8.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "62e752450ce4cf5e682ea8950f86725dffad461ca8b24c9215ac76d61e2d8392",
"md5": "9397567376aa90ecb82a8b5a244c6218",
"sha256": "01c94cc524446d6e23a2726d4cec94c764b277466cbeca4d95e083390b09ad34"
},
"downloads": -1,
"filename": "pyheif-0.8.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "9397567376aa90ecb82a8b5a244c6218",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.6",
"size": 5382393,
"upload_time": "2024-09-01T03:25:02",
"upload_time_iso_8601": "2024-09-01T03:25:02.527815Z",
"url": "https://files.pythonhosted.org/packages/62/e7/52450ce4cf5e682ea8950f86725dffad461ca8b24c9215ac76d61e2d8392/pyheif-0.8.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc4907d1c047e52fd4de1474759e202b2fd7ac99e945db0ce149af2f85be7625",
"md5": "3e529a7fedda111678f5043cfe11795e",
"sha256": "ac5ec62a90c4f9f96125aaebd6ac994b95895ace4427ecf34752951e1d34be96"
},
"downloads": -1,
"filename": "pyheif-0.8.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "3e529a7fedda111678f5043cfe11795e",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.6",
"size": 5382780,
"upload_time": "2024-09-01T03:25:08",
"upload_time_iso_8601": "2024-09-01T03:25:08.188391Z",
"url": "https://files.pythonhosted.org/packages/fc/49/07d1c047e52fd4de1474759e202b2fd7ac99e945db0ce149af2f85be7625/pyheif-0.8.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "68361d15e207f0f2903c86c93ac03d1c33bcc62d8e546ade3836d0704a5ca47e",
"md5": "ac9789678117130125ed026a84232580",
"sha256": "4e4aa21e9bd92dbca7f3d281a4176611ccbcbb13990adcc74ccf4503498d2947"
},
"downloads": -1,
"filename": "pyheif-0.8.0-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "ac9789678117130125ed026a84232580",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.6",
"size": 5382014,
"upload_time": "2024-09-01T03:25:15",
"upload_time_iso_8601": "2024-09-01T03:25:15.594396Z",
"url": "https://files.pythonhosted.org/packages/68/36/1d15e207f0f2903c86c93ac03d1c33bcc62d8e546ade3836d0704a5ca47e/pyheif-0.8.0-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2bb4947f2bc3800fcbead2e264b9ceaa41b6bb9eb85e7458847fa9aec6877f50",
"md5": "f599bb0dfb747ebf673252ee0d29ac6e",
"sha256": "037fcfb4facb5160c6c874824b4fe4dab7855653a3114ed08c8273209d7e5cf5"
},
"downloads": -1,
"filename": "pyheif-0.8.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "f599bb0dfb747ebf673252ee0d29ac6e",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.6",
"size": 5382533,
"upload_time": "2024-09-01T03:25:21",
"upload_time_iso_8601": "2024-09-01T03:25:21.421492Z",
"url": "https://files.pythonhosted.org/packages/2b/b4/947f2bc3800fcbead2e264b9ceaa41b6bb9eb85e7458847fa9aec6877f50/pyheif-0.8.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "25ed108eabdcbd8a12ac31b4979dd9a9bfd8342590db27037ecba3ce5a773276",
"md5": "cfcc385a95654cb3833a7b84ff347ddd",
"sha256": "adba452e061b4b1edf57ad561daf69f3e67de4be42088885685ef4e6a8dd9baf"
},
"downloads": -1,
"filename": "pyheif-0.8.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "cfcc385a95654cb3833a7b84ff347ddd",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.6",
"size": 5382397,
"upload_time": "2024-09-01T03:25:26",
"upload_time_iso_8601": "2024-09-01T03:25:26.472647Z",
"url": "https://files.pythonhosted.org/packages/25/ed/108eabdcbd8a12ac31b4979dd9a9bfd8342590db27037ecba3ce5a773276/pyheif-0.8.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "35175a5a70da5b6dd52937e38259e65180414e4c5625717b139a6f7aa30a79a5",
"md5": "34e7088e2a39f13cfe98b4d8bea19f2b",
"sha256": "c9f1c8e3158b98fc82b3833e7358f6ca0ef9d50fa93d20993925917e9189bbc6"
},
"downloads": -1,
"filename": "pyheif-0.8.0-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "34e7088e2a39f13cfe98b4d8bea19f2b",
"packagetype": "bdist_wheel",
"python_version": "pp310",
"requires_python": ">=3.6",
"size": 5328137,
"upload_time": "2024-09-01T03:25:31",
"upload_time_iso_8601": "2024-09-01T03:25:31.672205Z",
"url": "https://files.pythonhosted.org/packages/35/17/5a5a70da5b6dd52937e38259e65180414e4c5625717b139a6f7aa30a79a5/pyheif-0.8.0-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8d97a180a87119f81f06d032a0530f4636e1c1e75d9589c8c6b915d80cb0743f",
"md5": "247ed0ccba9d0e459b70cddcab41b775",
"sha256": "39214792559eab90814f9551540156550619fc6f8f0d794091488563577da5ca"
},
"downloads": -1,
"filename": "pyheif-0.8.0-pp39-pypy39_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "247ed0ccba9d0e459b70cddcab41b775",
"packagetype": "bdist_wheel",
"python_version": "pp39",
"requires_python": ">=3.6",
"size": 5328131,
"upload_time": "2024-09-01T03:25:37",
"upload_time_iso_8601": "2024-09-01T03:25:37.544386Z",
"url": "https://files.pythonhosted.org/packages/8d/97/a180a87119f81f06d032a0530f4636e1c1e75d9589c8c6b915d80cb0743f/pyheif-0.8.0-pp39-pypy39_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-01 03:24:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "carsales",
"github_project": "pyheif",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyheif"
}
JSON
