hdr-conversion 0.1.2

tools for converting HDR images between different formats

HDR Format Conversion Tool

简体中文 | English

Note: In alpha stage, API may change frequently. Currently, color conversion may be incorrect.

Note: PyExifTool requires the exiftool executable in the system path, see https://exiftool.org/ . Otherwise, reading Apple HEIC may hang without prompt. Please use exiftool -ver to check if it is installed correctly. This issue will be fixed in the next version.

API Reference: https://jackchou00.github.io/hdr-conversion

Project Overview

This project provides Python-based research on HDR format parsing and writing, supporting parsing, writing, and conversion of multiple formats including UltraHDR, Adaptive Gainmap (ISO 21496-1), and pure PQ/HLG formats (ISO 22028-5).

Note: This project is for research and learning purposes only and does not aim for production readiness.

Getting Started

To install, using uv (recommended):

uv add hdr-conversion

or use pip:

pip install hdr-conversion

The package can be imported as follows:

import hdrconv

Features

Parsing

For UltraHDR and Adaptive Gainmap formats, supports structured extraction of:

• Main image data
• Gainmap image data
• Gainmap metadata

For pure PQ/HLG formats, supports extraction of image data and related metadata.

Add experimental support for iOS 26 HDR screenshot parsing.

Writing

Writes image data and structured metadata into corresponding formats.

UltraHDR and Adaptive Gainmap formats are implemented through manual byte stream editing combined with existing library JPEG encoding capabilities, while pure PQ/HLG formats are implemented through existing libraries.

UltraHDR I/O APIs: read_ultrahdr() / write_ultrahdr().

Conversion

Calculates alternate images based on metadata to enable conversion between Gainmap and pure HDR formats.

Reference Standards

• UltraHDR: Version 1.1 released in April 2025
• ISO 21496-1
• ISO 22028-5

License

MIT. Please refer to the respective LICENSE files for specific format and dependency details.