hdr-conversion 0.1.0__py3-none-any.whl

hdr_conversion-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: hdr-conversion
+Version: 0.1.0
+Summary: tools for converting HDR images between different formats
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: colour-science>=0.4.6
+Requires-Dist: imagecodecs>=2025.11.11
+Requires-Dist: pillow-heif>=0.22.0
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pyexiftool>=0.5.6
+Description-Content-Type: text/markdown
+
+# HDR Format Conversion Tool
+
+[简体中文](README-zhCN.md) | [English](README.md)
+
+> Note: In alpha stage, API may change frequently. Currently, color conversion may be incorrect.
+
+API Reference: [https://jackchou.top/hdr-conversion](https://jackchou.top/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):
+
+```bash
+uv add hdr-conversion
+```
+
+or use `pip`:
+
+```bash
+pip install hdr-conversion
+```
+
+The package can be imported as follows:
+
+```python
+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.
+
+### 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.
+
+### Conversion
+
+Calculates alternate images based on metadata to enable conversion between Gainmap and pure HDR formats.
+
+## Reference Standards
+
+- [UltraHDR](https://developer.android.com/media/platform/hdr-image-format): Version 1.1 released in April 2025
+- [ISO 21496-1](https://www.iso.org/standard/86775.html)
+- [ISO 22028-5](https://www.iso.org/standard/81863.html)
+
+## License
+
+MIT. Please refer to the respective LICENSE files for specific format and dependency details.

hdr_conversion-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+hdrconv/__init__.py,sha256=NROgdFe10SnJuT0PsdVxFwQ5AYCMl9jBIjEMXAWW0O8,342
+hdrconv/convert/__init__.py,sha256=hRpXwiDeJ486uEMzTJ4K425mwR-okcOVjRX7JbEsR0M,745
+hdrconv/convert/apple.py,sha256=8gWAiMXWvPn3vb0m8OEUTJZzhDEBtKOBxq3SGxlZ3jc,3585
+hdrconv/convert/colorspace.py,sha256=xEo9j7dTwzx7cBb2rY0MwmKDyz4hCOIKZU2B5_LqcW8,2504
+hdrconv/convert/gainmap.py,sha256=q0r0kMiEf4H4qfGjpU2jdFqWEidoFlIZdKBXptjRFE4,9455
+hdrconv/convert/transfer.py,sha256=EznALcPcFUBj9_idkwTMpSkxNzE7c0OPU_sg8zUvmro,2875
+hdrconv/core/__init__.py,sha256=maPeWAh0bXJssiu01OFw8JfQ3fFf1Jf5MVhipyte9LY,589
+hdrconv/core/types.py,sha256=cmno3kiPzKPQCup_XxPluzjs8M7OkYmjKsPw-ORO7Ts,5574
+hdrconv/identify/__init__.py,sha256=kMiFBbWgYPthAYBog6MMMFnJ4fyCP4ceY2heLpqHu7E,288
+hdrconv/identify/apple_heic.py,sha256=bnPA9n-Xr4Kl6vkKjS7WQJo-jj4y82TyMr0OdBl1QPk,1557
+hdrconv/io/__init__.py,sha256=e_TVKDTTJDAsd1uL6N3qUQwJR1RtD0S0v3Kd3ceEBJg,542
+hdrconv/io/apple_heic.py,sha256=_DamZpxoc9nxdA80IG5Y3Pkd68hnvgPXs2dAkmgpUx0,6383
+hdrconv/io/iso21496.py,sha256=Qk0TEZ5_gNFFXhPIFH03upvq6AyspCZWVGw4TaCneAg,28713
+hdrconv/io/iso22028.py,sha256=_DBqCImxDHM3ovTrEFdl-2hNEOnWGvjE8LwcS6cf9Tc,3908
+hdr_conversion-0.1.0.dist-info/METADATA,sha256=MQapN8HhE5yvdxmMS_qaPUxyznq3G8ZLmxOjeff5eDs,2271
+hdr_conversion-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+hdr_conversion-0.1.0.dist-info/licenses/LICENSE,sha256=yt-PreLOGv7lJBruB4S8-HO4yxZSJayyVD9jEMz6I-0,1083
+hdr_conversion-0.1.0.dist-info/RECORD,,

hdr_conversion-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hdr_conversion-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright © 2025 <Jack Chou>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

hdrconv/__init__.py

@@ -0,0 +1,18 @@
+"""HDR conversion research library.
+
+Public usage is via submodules (two-level imports), e.g.:
+    - ``hdrconv.io.read_21496``
+    - ``hdrconv.convert.gainmap_to_hdr``
+    - ``hdrconv.core.GainmapImage``
+"""
+
+__version__ = "0.1.0"
+
+from . import convert, core, identify, io
+
+__all__ = [
+    "convert",
+    "core",
+    "identify",
+    "io",
+]

hdrconv/convert/__init__.py

@@ -0,0 +1,24 @@
+"""HDR conversion algorithms.
+
+This module provides functions for converting between HDR formats and applying
+color space and transfer function transformations:
+
+- Gainmap conversion: `gainmap_to_hdr`, `hdr_to_gainmap`
+- Apple HEIC conversion: `apple_heic_to_hdr`
+- Color space conversion: `convert_color_space`
+- Transfer functions: `apply_pq`, `inverse_pq`
+"""
+
+from hdrconv.convert.apple import apple_heic_to_hdr
+from hdrconv.convert.colorspace import convert_color_space
+from hdrconv.convert.gainmap import gainmap_to_hdr, hdr_to_gainmap
+from hdrconv.convert.transfer import apply_pq, inverse_pq
+
+__all__ = [
+    "gainmap_to_hdr",
+    "hdr_to_gainmap",
+    "apple_heic_to_hdr",
+    "convert_color_space",
+    "apply_pq",
+    "inverse_pq",
+]

hdrconv/convert/apple.py

@@ -0,0 +1,100 @@
+"""Apple HEIC HDR conversion utilities.
+
+This module provides functions for converting Apple's proprietary HEIC
+HDR format (with gain map) to standard linear HDR representation.
+
+Apple's HDR format uses a single-channel gain map with the formula:
+    hdr_rgb = sdr_rgb * (1.0 + (headroom - 1.0) * gainmap)
+
+Public APIs:
+    - `apple_heic_to_hdr`: Convert AppleHeicData to HDRImage
+
+See Also:
+    Apple Developer Documentation:
+    https://developer.apple.com/documentation/appkit/applying-apple-hdr-effect-to-your-photos
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image
+
+from hdrconv.core import AppleHeicData, HDRImage
+
+
+def apple_heic_to_hdr(data: AppleHeicData) -> HDRImage:
+    """Convert Apple HEIC gain map data to linear HDR.
+
+        Applies Apple's proprietary gain map formula to reconstruct the HDR image
+        from the SDR base and single-channel gain map.
+
+        The reconstruction formula is:
+            hdr_rgb = sdr_rgb * (1.0 + (headroom - 1.0) * gainmap)
+
+        Where all values are in linear light space.
+
+        Args:
+            data: AppleHeicData dict containing:
+                - `base`: SDR image, uint8, shape (H, W, 3), Display P3.
+                - `gainmap`: Gain map, uint8, shape (H, W, 1).
+                - `headroom`: Peak luminance multiplier.
+
+        Returns:
+            HDRImage dict with the following keys:
+            - ``data`` (np.ndarray): Linear HDR array, float32, shape (H, W, 3).
+            - ``color_space`` (str): 'p3' (Display P3, Apple's default).
+            - ``transfer_function`` (str): 'linear'.
+            - ``icc_profile`` (bytes | None): None.
+
+        Note:
+            The gain map is upscaled from 1/4 resolution using bilinear interpolation.
+            Both base image (sRGB transfer) and gain map (Rec. 709 transfer) are
+            linearized before applying the formula.
+
+        See Also:
+            - `read_apple_heic`: Read AppleHeicData from HEIC file.
+            - `convert_color_space`: Convert output to BT.2020 if needed.
+    """
+
+    def apply_gain_map(
+        base_image: np.ndarray, gain_map: np.ndarray, headroom: float
+    ) -> np.ndarray:
+        if base_image is None or gain_map is None:
+            raise ValueError("Both base_image and gain_map must be provided.")
+
+        gain_map_resized = np.array(
+            Image.fromarray(gain_map).resize(
+                (base_image.shape[1], base_image.shape[0]), Image.BILINEAR
+            )
+        )
+
+        gain_map_norm = gain_map_resized.astype(np.float32) / 255.0
+        gain_map_linear = np.where(
+            gain_map_norm <= 0.08145,
+            gain_map_norm / 4.5,
+            np.power((gain_map_norm + 0.099) / 1.099, 1 / 0.45),
+        )
+        gain_map_linear = np.clip(gain_map_linear, 0.0, 1.0)
+
+        base_image_norm = base_image.astype(np.float32) / 255.0
+        base_image_linear = np.where(
+            base_image_norm <= 0.04045,
+            base_image_norm / 12.92,
+            np.power((base_image_norm + 0.055) / 1.055, 2.4),
+        )
+        base_image_linear = np.clip(base_image_linear, 0.0, 1.0)
+
+        hdr_image_linear = base_image_linear * (
+            1.0 + (headroom - 1.0) * gain_map_linear[..., np.newaxis]
+        )
+        hdr_image_linear = np.clip(hdr_image_linear, 0.0, None)
+        return hdr_image_linear
+
+    hdr_linear = apply_gain_map(data["base"], data["gainmap"], data["headroom"])
+
+    return HDRImage(
+        data=hdr_linear,
+        color_space="p3",  # Apple uses Display P3
+        transfer_function="linear",
+        icc_profile=None,
+    )

hdrconv/convert/colorspace.py

@@ -0,0 +1,74 @@
+"""Color space conversion utilities.
+
+This module provides functions for converting between different RGB color
+spaces used in HDR imaging workflows.
+
+Supported color spaces:
+    - 'bt709': ITU-R BT.709 (sRGB primaries)
+    - 'p3': DCI-P3 / Display P3
+    - 'bt2020': ITU-R BT.2020 (wide gamut HDR)
+
+Public APIs:
+    - `convert_color_space`: Transform between color spaces
+
+Note:
+    All conversions require linear light input. Apply EOTF first if
+    working with gamma-encoded data.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore")
+    import colour
+
+
+def convert_color_space(
+    image: np.ndarray, source_space: str, target_space: str, clip: bool = False
+) -> np.ndarray:
+    """Convert image between color spaces.
+
+        Transforms RGB values from one color space to another using chromatic
+        adaptation and matrix transformations. Input must be in linear light.
+
+        Args:
+            image: Linear RGB image data, float32, shape (H, W, 3).
+                Values should be in linear light (not gamma-encoded).
+            source_space: Source color space identifier.
+                Options: 'bt709' (Rec. 709), 'p3' (Display P3), 'bt2020' (Rec. 2020).
+            target_space: Target color space identifier.
+                Options: 'bt709', 'p3', 'bt2020'.
+            clip: Whether to clip output to [0, inf). Default: False.
+                Enable when negative values from gamut mapping are undesirable.
+
+        Returns:
+            Converted image in target color space, same shape as input.
+            Values remain in linear light.
+
+        Note:
+            If source_space equals target_space, returns input unchanged.
+            Uses colour-science library for accurate color transformations.
+
+        See Also:
+            - `apply_pq`: Apply PQ transfer function after color space conversion.
+            - `gainmap_to_hdr`: Includes color space conversion in HDR reconstruction.
+    """
+    space_map = {"bt709": "ITU-R BT.709", "p3": "DCI-P3", "bt2020": "ITU-R BT.2020"}
+
+    if source_space == target_space:
+        return image
+
+    source_name = space_map.get(source_space, source_space)
+    target_name = space_map.get(target_space, target_space)
+
+    target_image = colour.RGB_to_RGB(
+        image, input_colourspace=source_name, output_colourspace=target_name
+    )
+
+    if clip:
+        target_image = np.clip(target_image, 0.0, None)
+    return target_image

hdrconv/convert/gainmap.py

@@ -0,0 +1,261 @@
+"""ISO 21496-1 Gainmap conversion utilities.
+
+This module provides functions for converting between ISO 21496-1 Gainmap
+format and linear HDR representation.
+
+The ISO 21496-1 standard defines a method for encoding HDR content using
+a baseline (SDR) image plus a gainmap that encodes the HDR-to-SDR ratio
+in log2 space.
+
+Public APIs:
+    - `gainmap_to_hdr`: Reconstruct HDR from gainmap
+    - `hdr_to_gainmap`: Create gainmap from HDR
+
+See Also:
+    ISO/TS 21496-1: Adaptive gain map for HDR still image
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+import warnings
+
+from PIL import Image
+import numpy as np
+
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore")
+    import colour
+
+from hdrconv.core import GainmapImage, GainmapMetadata, HDRImage
+from hdrconv.convert.colorspace import convert_color_space
+
+
+def gainmap_to_hdr(
+    data: GainmapImage,
+    baseline_color_space: str = "p3",
+    alt_color_space: str = "p3",
+    target_color_space: str = "bt2020",
+) -> HDRImage:
+    """Convert ISO 21496-1 Gainmap to linear HDR image.
+
+        Applies the gainmap to the baseline image to reconstruct the alternate
+        (HDR) representation using the ISO 21496-1 formula:
+
+        - G' = (G^(1/gamma)) * (max - min) + min
+        - L = 2^G'
+        - HDR = L * (baseline + baseline_offset) - alternate_offset
+
+        Args:
+            data: GainmapImage dict containing baseline, gainmap, and metadata.
+            baseline_color_space: Color space of baseline image.
+                Options: 'bt709', 'p3', 'bt2020'. Default: 'p3'.
+            alt_color_space: Color space of alternate/HDR image.
+                Options: 'bt709', 'p3', 'bt2020'. Default: 'p3'.
+            target_color_space: Target output color space.
+                Options: 'bt709', 'p3', 'bt2020'. Default: 'bt2020'.
+
+        Returns:
+            HDRImage dict with the following keys:
+            - ``data`` (np.ndarray): Linear HDR array, float32, shape (H, W, 3).
+            - ``color_space`` (str): Target color space string.
+            - ``transfer_function`` (str): Always 'linear'.
+            - ``icc_profile`` (bytes | None): Always None.
+
+        Note:
+            The baseline image is assumed to be sRGB-encoded. The function
+            automatically applies EOTF conversion to linear light before
+            applying the gainmap formula.
+
+        See Also:
+            - `hdr_to_gainmap`: Inverse operation, create gainmap from HDR.
+            - `convert_color_space`: For additional color space transformations.
+    """
+    baseline = data["baseline"].astype(np.float32) / 255.0  # Normalize to [0, 1]
+    baseline = colour.eotf(baseline, function="sRGB")
+    gainmap = data["gainmap"].astype(np.float32) / 255.0
+    metadata = data["metadata"]
+
+    use_base_colour_space = metadata["use_base_colour_space"]
+    if not use_base_colour_space:
+        baseline = convert_color_space(
+            baseline,
+            source_space=baseline_color_space,
+            target_space=alt_color_space,
+        )
+    else:
+        gainmap = convert_color_space(
+            gainmap,
+            source_space=alt_color_space,
+            target_space=baseline_color_space,
+        )
+
+    # Resize gainmap to match baseline if needed
+    h, w = baseline.shape[:2]
+    if gainmap.shape[:2] != (h, w):
+        # Use Pillow for resizing: convert float32 [0,1] -> uint8 [0,255] -> resize -> back to float32
+        gainmap_uint8 = np.clip(gainmap * 255.0, 0, 255).astype(np.uint8)
+
+        # Handle 2D grayscale and 3D RGB arrays
+        if gainmap_uint8.ndim == 2:
+            pil_image = Image.fromarray(gainmap_uint8, mode="L")
+        else:
+            pil_image = Image.fromarray(gainmap_uint8, mode="RGB")
+
+        # Resize using bilinear interpolation (equivalent to cv2.INTER_LINEAR)
+        pil_image_resized = pil_image.resize((w, h), Image.BILINEAR)
+
+        # Convert back to float32 [0,1]
+        gainmap = np.array(pil_image_resized, dtype=np.float32) / 255.0
+
+    # Ensure gainmap is 3-channel for calculations
+    if gainmap.ndim == 2:
+        gainmap = gainmap[:, :, np.newaxis]
+    if gainmap.shape[2] == 1:
+        gainmap = np.repeat(gainmap, 3, axis=2)
+
+    # Extract metadata (convert to arrays for broadcasting)
+    gainmap_min = np.array(metadata["gainmap_min"], dtype=np.float32)
+    gainmap_max = np.array(metadata["gainmap_max"], dtype=np.float32)
+    gainmap_gamma = np.array(metadata["gainmap_gamma"], dtype=np.float32)
+    baseline_offset = np.array(metadata["baseline_offset"], dtype=np.float32)
+    alternate_offset = np.array(metadata["alternate_offset"], dtype=np.float32)
+
+    gainmap = np.clip(gainmap, 0.0, 1.0)
+
+    # Decode gainmap: apply gamma, scale, and offset
+    gainmap_decoded = (gainmap ** (1 / gainmap_gamma)) * (
+        gainmap_max - gainmap_min
+    ) + gainmap_min
+
+    # Convert to linear multiplier
+    gainmap_linear = np.exp2(gainmap_decoded)
+
+    # Reconstruct alternate (HDR) image
+    hdr_linear = gainmap_linear * (baseline + baseline_offset) - alternate_offset
+
+    # Color space conversion
+    if not use_base_colour_space:
+        hdr_linear = convert_color_space(
+            hdr_linear, source_space=alt_color_space, target_space=target_color_space
+        )
+    else:
+        hdr_linear = convert_color_space(
+            hdr_linear,
+            source_space=baseline_color_space,
+            target_space=target_color_space,
+        )
+
+    hdr_linear = np.clip(hdr_linear, 0.0, None)
+
+    return HDRImage(
+        data=hdr_linear,
+        color_space=target_color_space,
+        transfer_function="linear",
+        icc_profile=None,
+    )
+
+
+def hdr_to_gainmap(
+    hdr: HDRImage,
+    baseline: Optional[np.ndarray] = None,
+    color_space: str = "bt709",
+    icc_profile: Optional[bytes] = None,
+    gamma: float = 1.0,
+) -> GainmapImage:
+    """Convert linear HDR image to ISO 21496-1 Gainmap format.
+
+        Creates a gainmap by computing the log2 ratio between HDR and SDR images.
+        If baseline is not provided, generates one by clipping HDR to [0, 1].
+
+        Args:
+            hdr: HDRImage dict with linear HDR data in any supported color space.
+            baseline: Optional pre-computed baseline (SDR) image.
+                If None, generated by clipping HDR to [0, 1].
+                Expected format: float32, shape (H, W, 3), range [0, 1].
+            color_space: Target color space for output.
+                Options: 'bt709', 'p3', 'bt2020'. Default: 'bt709'.
+            icc_profile: Optional ICC profile bytes to embed in output.
+                Should match the specified color_space.
+            gamma: Gainmap gamma parameter for encoding.
+                Higher values compress highlights. Default: 1.0.
+
+        Returns:
+            GainmapImage dict containing:
+            - ``baseline`` (np.ndarray): SDR image, uint8, shape (H, W, 3).
+            - ``gainmap`` (np.ndarray): Gain map, uint8, shape (H, W, 3).
+            - ``metadata`` (GainmapMetadata): Computed transformation parameters.
+            - ``baseline_icc`` (bytes | None): Provided ICC profile.
+            - ``gainmap_icc`` (bytes | None): Provided ICC profile.
+
+        Note:
+            Uses fixed offsets of 1/64 for both baseline and alternate to
+            avoid division by zero in dark regions.
+
+        See Also:
+            - `gainmap_to_hdr`: Inverse operation, reconstruct HDR from gainmap.
+            - `write_21496`: Write GainmapImage to ISO 21496-1 JPEG.
+    """
+    hdr_data = hdr["data"].astype(np.float32)
+
+    # convert to target colour space
+    hdr_data = convert_color_space(
+        hdr_data, source_space=hdr["color_space"], target_space=color_space
+    )
+
+    hdr_data = np.clip(hdr_data, 0.0, None)
+
+    # Generate baseline if not provided
+    if baseline is None:
+        baseline = hdr_data.copy()
+        baseline = np.clip(baseline, 0.0, 1.0)
+
+    # Compute alt headroom
+    alt_headroom = np.log2(hdr_data.max() + 1e-6)
+
+    # preset offset for both baseline and alternate = 1/64
+    alt_offset = float(1 / 64)
+    base_offset = float(1 / 64)
+
+    ratio = (hdr_data + alt_offset) / (baseline + base_offset)
+    ratio = np.clip(ratio, 1e-6, None)
+
+    gainmap_log = np.log2(ratio)
+
+    gainmap_min_val = np.min(gainmap_log, axis=(0, 1))
+    gainmap_max_val = np.max(gainmap_log, axis=(0, 1))
+
+    gainmap_norm = (gainmap_log - gainmap_min_val) / (gainmap_max_val - gainmap_min_val)
+    gainmap_norm = np.clip(gainmap_norm, 0, 1)
+
+    gainmap_norm = gainmap_norm**gamma
+
+    gainmap_uint8 = (gainmap_norm * 255).astype(np.uint8)
+
+    baseline = colour.eotf_inverse(baseline, function="sRGB")
+    baseline_uint8 = (baseline * 255).astype(np.uint8)
+
+    gainmap_min_val = tuple(gainmap_min_val.tolist())
+    gainmap_max_val = tuple(gainmap_max_val.tolist())
+
+    metadata = GainmapMetadata(
+        minimum_version=0,
+        writer_version=0,
+        baseline_hdr_headroom=1.0,
+        alternate_hdr_headroom=float(alt_headroom),
+        is_multichannel=True,
+        use_base_colour_space=True,
+        gainmap_min=gainmap_min_val,
+        gainmap_max=gainmap_max_val,
+        gainmap_gamma=(gamma, gamma, gamma),
+        baseline_offset=(base_offset, base_offset, base_offset),
+        alternate_offset=(alt_offset, alt_offset, alt_offset),
+    )
+
+    return GainmapImage(
+        baseline=baseline_uint8,
+        gainmap=gainmap_uint8,
+        metadata=metadata,
+        baseline_icc=icc_profile,
+        gainmap_icc=icc_profile,
+    )

hdrconv/convert/transfer.py

@@ -0,0 +1,84 @@
+"""Transfer function utilities for HDR encoding.
+
+This module provides functions for applying and inverting transfer functions
+used in HDR content delivery, particularly PQ (Perceptual Quantizer).
+
+Supported transfer functions:
+    - PQ (SMPTE ST 2084): Used in HDR10, Dolby Vision
+    - HLG (Hybrid Log-Gamma): Used in broadcast HDR
+
+Public APIs:
+    - `apply_pq`: Encode linear light to PQ
+    - `inverse_pq`: Decode PQ to linear light
+
+Note:
+    PQ uses 203 nits as reference white (1.0 in linear scale).
+    Values above 1.0 represent HDR highlights up to 10000 nits.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore")
+    import colour
+
+
+def apply_pq(linear_rgb: np.ndarray) -> np.ndarray:
+    """Apply PQ (Perceptual Quantizer) transfer function.
+
+        Encodes linear light RGB values to PQ (SMPTE ST 2084) transfer function
+        as specified in ITU-R BT.2100 for HDR content.
+
+        Args:
+            linear_rgb: Linear RGB data, float32, shape (H, W, 3).
+                Values should be normalized where 1.0 = 203 nits (reference white).
+                Values above 1.0 represent HDR highlights up to ~49x (10000 nits).
+
+        Returns:
+            PQ-encoded data, float32, shape (H, W, 3), range [0, 1].
+            Output is clipped to valid PQ range.
+
+        Note:
+            Uses 203 nits as reference white (PQ specification).
+            Linear value of 1.0 maps to ~58% in PQ code values.
+
+        See Also:
+            - `inverse_pq`: Decode PQ back to linear light.
+            - `write_22028_pq`: Write PQ-encoded data to AVIF file.
+    """
+    # Normalize to reference white (203 nits in PQ)
+    pq_encoded = colour.models.eotf_inverse_BT2100_PQ(linear_rgb * 203.0)
+    pq_encoded = np.clip(pq_encoded, 0.0, 1.0)
+    return pq_encoded
+
+
+def inverse_pq(pq_encoded: np.ndarray) -> np.ndarray:
+    """Decode PQ-encoded values to linear light RGB.
+
+        Applies the inverse PQ (SMPTE ST 2084) EOTF to convert PQ-encoded
+        values back to linear light as specified in ITU-R BT.2100.
+
+        Args:
+            pq_encoded: PQ-encoded data, float32, shape (H, W, 3), range [0, 1].
+                Values represent 0-10000 nits in PQ perceptual scale.
+
+        Returns:
+            Linear RGB data, float32, shape (H, W, 3).
+            Normalized where 1.0 = 203 nits (reference white).
+            HDR highlights may exceed 1.0 up to ~49x.
+
+        Note:
+            Uses 203 nits as reference white (PQ specification).
+            PQ code value of ~0.58 maps to linear 1.0.
+
+        See Also:
+            - `apply_pq`: Encode linear light to PQ.
+            - `read_22028_pq`: Read PQ-encoded AVIF file.
+    """
+    linear_normalized = colour.models.eotf_BT2100_PQ(pq_encoded)
+    linear_rgb = linear_normalized / 203.0
+    return linear_rgb