# apple-hdr-heic
A library/tool to decode photos (HEIC files) taken on an iPhone that contain HDR gain map, and convert it to a 48-bit (16-bit per channel) HDR representation as per [Rec. 2100](https://en.wikipedia.org/wiki/Rec._2100) with PQ transfer function.
**Disclaimer:** This project is _not_ affiliated with, or endorsed by, Apple Inc. or any of its subsidiaries.
## Pre-requisites
* Python 3.10+
* [`exiftool`](https://exiftool.org/) 12.54+
- For Ubuntu or Debian, do `sudo apt install libimage-exiftool-perl`
- For other Linux distros, search `exiftool` using your package manager
- For Mac or Windows, follow the instructions in website
- For Windows, it is also available via [Scoop](https://scoop.sh/)
## Installation
To install the latest published version, do (preferrably in a [virtual environment](https://docs.python.org/3/library/venv.html)):
```
pip install apple-hdr-heic
```
Or if you want the latest development version, install using a Github archive link:
```
pip install https://github.com/johncf/apple-hdr-heic/archive/master.tar.gz
```
## Usage
### CLI Tool
```
apple-hdr-heic-decode input.heic output.png
apple-hdr-heic-decode input.heic output.heic -q 95
```
Lossless conversion:
```
apple-hdr-heic-decode input.heic output.avif -b 12 -y 444
```
Note: With 12-bit channels (in AVIF or HEIC), it's not truly lossless compared to 16-bit channels in PNG, but it's close enough.
### Library Usage
```py
from apple_hdr_heic import load_as_bt2100_pq, quantize_to_uint16
bt2100_pq = load_as_bt2100_pq("input.heic")
bt2100_pq_u16 = quantize_to_uint16(bt2100_pq)
cv2.imwrite("output.png", bt2100_pq_u16[:, :, ::-1])
```
Note: The output file `output.png` (in examples above) does not contain the necessary [cICP](https://en.wikipedia.org/wiki/Coding-independent_code_points) metadata that denotes it to have `bt2020` (9) color primaries and `smpte2084` (16) transfer characteristics. Therefore, all image viewers will display them incorrectly.
## Development
### Environment Set Up
Install [`uv`](https://github.com/astral-sh/uv).
Install `nox` using `uv`:
```
uv tool install nox
```
### Unit Testing
```
nox -s test
```
### Type Checking
```
nox -s typeck
```
### Linting
```
nox -s lint
```
### Formatting
```
nox -s style
```
### Building
```
uv tool install flit
flit build --no-use-vcs
```
## Miscellaneous Notes
### About 12-bit HEIC Files
Although this tool supports 12-bit HEIC output, it doesn't seem to be widely supported, even in Apple softwares.
### About AVIF Output
If you want to use a different AVIF encoder, first use this tool to produce a PNG file, then use [libavif](https://github.com/AOMediaCodec/libavif) with `--cicp` set to `9/16/9` to convert the PNG to AVIF:
```
avifenc -s 4 -j 4 --min 1 --max 56 -a end-usage=q -a cq-level=10 -a tune=ssim -a color:enable-qm=1 \
-a color:enable-chroma-deltaq=1 -d 12 --cicp 9/16/9 output.png output.avif
```
Raw data
{
"_id": null,
"home_page": null,
"name": "apple-hdr-heic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "heic, heif, converter, decoder, HDR, HDR Gain Map, iPhone",
"author": null,
"author_email": "John Charankattu <john.ch.fr@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/62/a3fce6257033f4e699aabf6a5869e2e184e8259a9660a257a94ab1a69c86/apple_hdr_heic-0.0.3.tar.gz",
"platform": null,
"description": "# apple-hdr-heic\n\nA library/tool to decode photos (HEIC files) taken on an iPhone that contain HDR gain map, and convert it to a 48-bit (16-bit per channel) HDR representation as per [Rec. 2100](https://en.wikipedia.org/wiki/Rec._2100) with PQ transfer function.\n\n**Disclaimer:** This project is _not_ affiliated with, or endorsed by, Apple Inc. or any of its subsidiaries.\n\n## Pre-requisites\n\n* Python 3.10+\n* [`exiftool`](https://exiftool.org/) 12.54+\n - For Ubuntu or Debian, do `sudo apt install libimage-exiftool-perl`\n - For other Linux distros, search `exiftool` using your package manager\n - For Mac or Windows, follow the instructions in website\n - For Windows, it is also available via [Scoop](https://scoop.sh/)\n\n## Installation\n\nTo install the latest published version, do (preferrably in a [virtual environment](https://docs.python.org/3/library/venv.html)):\n\n```\npip install apple-hdr-heic\n```\n\nOr if you want the latest development version, install using a Github archive link:\n\n```\npip install https://github.com/johncf/apple-hdr-heic/archive/master.tar.gz\n```\n\n## Usage\n\n### CLI Tool\n\n```\napple-hdr-heic-decode input.heic output.png\napple-hdr-heic-decode input.heic output.heic -q 95\n```\n\nLossless conversion:\n\n```\napple-hdr-heic-decode input.heic output.avif -b 12 -y 444\n```\n\nNote: With 12-bit channels (in AVIF or HEIC), it's not truly lossless compared to 16-bit channels in PNG, but it's close enough.\n\n### Library Usage\n\n```py\nfrom apple_hdr_heic import load_as_bt2100_pq, quantize_to_uint16\n\nbt2100_pq = load_as_bt2100_pq(\"input.heic\")\nbt2100_pq_u16 = quantize_to_uint16(bt2100_pq)\ncv2.imwrite(\"output.png\", bt2100_pq_u16[:, :, ::-1])\n```\n\nNote: The output file `output.png` (in examples above) does not contain the necessary [cICP](https://en.wikipedia.org/wiki/Coding-independent_code_points) metadata that denotes it to have `bt2020` (9) color primaries and `smpte2084` (16) transfer characteristics. Therefore, all image viewers will display them incorrectly.\n\n## Development\n\n### Environment Set Up\n\nInstall [`uv`](https://github.com/astral-sh/uv).\n\nInstall `nox` using `uv`:\n\n```\nuv tool install nox\n```\n\n### Unit Testing\n\n```\nnox -s test\n```\n\n### Type Checking\n\n```\nnox -s typeck\n```\n\n### Linting\n\n```\nnox -s lint\n```\n\n### Formatting\n\n```\nnox -s style\n```\n\n### Building\n\n```\nuv tool install flit\nflit build --no-use-vcs\n```\n\n## Miscellaneous Notes\n\n### About 12-bit HEIC Files\n\nAlthough this tool supports 12-bit HEIC output, it doesn't seem to be widely supported, even in Apple softwares.\n\n### About AVIF Output\n\nIf you want to use a different AVIF encoder, first use this tool to produce a PNG file, then use [libavif](https://github.com/AOMediaCodec/libavif) with `--cicp` set to `9/16/9` to convert the PNG to AVIF:\n\n```\navifenc -s 4 -j 4 --min 1 --max 56 -a end-usage=q -a cq-level=10 -a tune=ssim -a color:enable-qm=1 \\\n -a color:enable-chroma-deltaq=1 -d 12 --cicp 9/16/9 output.png output.avif\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A library/tool to decode images in HEIC/HEIF format taken on Apple devices that contain HDR gain map.",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/johncf/apple-hdr-heic"
},
"split_keywords": [
"heic",
" heif",
" converter",
" decoder",
" hdr",
" hdr gain map",
" iphone"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2158c1ce39872e6ea992d5160ba6b635840308f897bc465a1f86cc05028f0b95",
"md5": "fc94fb165dd762573eccb0a54f08dca5",
"sha256": "b0daba1e7e5aa2d375800bddfaa74e191a60b059b1d617a79207045f2876b8dc"
},
"downloads": -1,
"filename": "apple_hdr_heic-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc94fb165dd762573eccb0a54f08dca5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8606,
"upload_time": "2024-12-03T03:01:56",
"upload_time_iso_8601": "2024-12-03T03:01:56.031998Z",
"url": "https://files.pythonhosted.org/packages/21/58/c1ce39872e6ea992d5160ba6b635840308f897bc465a1f86cc05028f0b95/apple_hdr_heic-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c262a3fce6257033f4e699aabf6a5869e2e184e8259a9660a257a94ab1a69c86",
"md5": "5ccb6173f243d2fc2fc72b633f182f5f",
"sha256": "b83af9b9f8d5db81a2c84e125569549be1a82821eb554f8703bf3bb96f199719"
},
"downloads": -1,
"filename": "apple_hdr_heic-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "5ccb6173f243d2fc2fc72b633f182f5f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6892,
"upload_time": "2024-12-03T03:01:57",
"upload_time_iso_8601": "2024-12-03T03:01:57.142577Z",
"url": "https://files.pythonhosted.org/packages/c2/62/a3fce6257033f4e699aabf6a5869e2e184e8259a9660a257a94ab1a69c86/apple_hdr_heic-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-03 03:01:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "johncf",
"github_project": "apple-hdr-heic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "colour-science",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "imageio",
"specs": [
[
"==",
"2.36.0"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.1.2"
]
]
},
{
"name": "opencv-python-headless",
"specs": [
[
"==",
"4.10.0.84"
]
]
},
{
"name": "pillow",
"specs": [
[
"==",
"11.0.0"
]
]
},
{
"name": "pillow-heif",
"specs": [
[
"==",
"0.20.0"
]
]
},
{
"name": "pyexiftool",
"specs": [
[
"==",
"0.5.6"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.14.1"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.12.2"
]
]
}
],
"lcname": "apple-hdr-heic"
}
JSON
