Skip to content

Core Types

hdrconv.core

Core data types for HDR conversion.

This module contains the TypedDict-based structures shared across the library for representing HDR images, gainmaps, and associated metadata.

Public Types
  • GainmapImage: ISO 21496-1 gainmap container
  • GainmapMetadata: Gainmap transformation parameters
  • HDRImage: Linear or transfer-encoded HDR image
  • AppleHeicData: Apple HEIC gainmap container

AppleHeicData

Bases: TypedDict

Apple HEIC HDR image data structure.

Contains the base (SDR) image, single-channel gainmap, and headroom value used by Apple's proprietary HDR gain map format in iPhone photos.

The HDR reconstruction formula is

hdr_rgb = sdr_rgb * (1.0 + (headroom - 1.0) * gainmap)

Attributes:

Name Type Description
base ndarray

numpy image array, uint8, shape (H, W, 3), range [0, 255].
gainmap ndarray

numpy array, uint8, shape (H, W, 1), range [0, 255].
headroom float

Peak luminance headroom value, typically 2.0-8.0. Represents the maximum brightness multiplier for HDR highlights.
See Also
  • read_apple_heic: Read AppleHeicData from HEIC file.
  • apple_heic_to_hdr: Convert AppleHeicData to linear HDRImage.
Source code in src/hdrconv/core/types.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
class AppleHeicData(TypedDict):
    """Apple HEIC HDR image data structure.

    Contains the base (SDR) image, single-channel gainmap, and headroom value
    used by Apple's proprietary HDR gain map format in iPhone photos.

    The HDR reconstruction formula is:
        hdr_rgb = sdr_rgb * (1.0 + (headroom - 1.0) * gainmap)

    Attributes:
        base: numpy image array, uint8, shape (H, W, 3), range [0, 255].
        gainmap: numpy array, uint8, shape (H, W, 1), range [0, 255].
        headroom: Peak luminance headroom value, typically 2.0-8.0.
            Represents the maximum brightness multiplier for HDR highlights.

    See Also:
        - `read_apple_heic`: Read AppleHeicData from HEIC file.
        - `apple_heic_to_hdr`: Convert AppleHeicData to linear HDRImage.
    """

    base: np.ndarray
    gainmap: np.ndarray
    headroom: float

base instance-attribute

gainmap instance-attribute

headroom instance-attribute

GainmapImage

Bases: TypedDict

ISO 21496-1 Gainmap image structure.

Contains the baseline image, gainmap, and metadata.

Attributes:

Name Type Description
baseline ndarray

numpy array, uint8, shape (H, W, 3), range [0, 255].
gainmap ndarray

numpy array, uint8, shape (H, W, 3) or (H, W, 1), range [0, 255].
metadata GainmapMetadata

GainmapMetadata dict containing transformation parameters.
baseline_icc Optional[bytes]

Optional ICC profile bytes for baseline image color space.
gainmap_icc Optional[bytes]

Optional ICC profile bytes for gainmap color space.
Source code in src/hdrconv/core/types.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
class GainmapImage(TypedDict):
    """ISO 21496-1 Gainmap image structure.

    Contains the baseline image, gainmap, and metadata.

    Attributes:
        baseline: numpy array, uint8, shape (H, W, 3), range [0, 255].
        gainmap: numpy array, uint8, shape (H, W, 3) or (H, W, 1), range [0, 255].
        metadata: GainmapMetadata dict containing transformation parameters.
        baseline_icc: Optional ICC profile bytes for baseline image color space.
        gainmap_icc: Optional ICC profile bytes for gainmap color space.
    """

    baseline: np.ndarray
    gainmap: np.ndarray
    metadata: GainmapMetadata
    baseline_icc: Optional[bytes]
    gainmap_icc: Optional[bytes]

baseline instance-attribute

gainmap instance-attribute

metadata instance-attribute

baseline_icc instance-attribute

gainmap_icc instance-attribute

GainmapMetadata

Bases: TypedDict

ISO 21496-1 Gainmap metadata structure.

Contains transformation parameters for converting between baseline and alternate representations as defined in ISO 21496-1.

Attributes:

Name Type Description
minimum_version int

Minimum decoder version required. Should be 0.
writer_version int

Version of the encoder that created the metadata.
baseline_hdr_headroom float

HDR headroom of baseline image, typically 1.0.
alternate_hdr_headroom float

HDR headroom of alternate image (e.g., 4.5).
is_multichannel bool

True if gainmap has separate RGB channels, False for single channel.
use_base_colour_space bool

True to compute in baseline color space, False for alternate.
gainmap_min Tuple[float, float, float]

Minimum gainmap values per channel, tuple of 3 floats.
gainmap_max Tuple[float, float, float]

Maximum gainmap values per channel, tuple of 3 floats.
gainmap_gamma Tuple[float, float, float]

Gamma values per channel for gainmap decoding, tuple of 3 floats.
baseline_offset Tuple[float, float, float]

Offset added to baseline before multiplication, tuple of 3 floats.
alternate_offset Tuple[float, float, float]

Offset subtracted from result, tuple of 3 floats.
Source code in src/hdrconv/core/types.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class GainmapMetadata(TypedDict, total=False):
    """ISO 21496-1 Gainmap metadata structure.

    Contains transformation parameters for converting between baseline
    and alternate representations as defined in ISO 21496-1.

    Attributes:
        minimum_version: Minimum decoder version required. Should be 0.
        writer_version: Version of the encoder that created the metadata.
        baseline_hdr_headroom: HDR headroom of baseline image, typically 1.0.
        alternate_hdr_headroom: HDR headroom of alternate image (e.g., 4.5).
        is_multichannel: True if gainmap has separate RGB channels, False for single channel.
        use_base_colour_space: True to compute in baseline color space, False for alternate.
        gainmap_min: Minimum gainmap values per channel, tuple of 3 floats.
        gainmap_max: Maximum gainmap values per channel, tuple of 3 floats.
        gainmap_gamma: Gamma values per channel for gainmap decoding, tuple of 3 floats.
        baseline_offset: Offset added to baseline before multiplication, tuple of 3 floats.
        alternate_offset: Offset subtracted from result, tuple of 3 floats.

    """

    # Version information
    minimum_version: int
    writer_version: int

    # HDR headroom values
    baseline_hdr_headroom: float
    alternate_hdr_headroom: float

    # Channel configuration
    is_multichannel: bool
    use_base_colour_space: bool

    # Gainmap transformation parameters
    gainmap_min: Tuple[float, float, float]
    gainmap_max: Tuple[float, float, float]
    gainmap_gamma: Tuple[float, float, float]

    # Offset parameters
    baseline_offset: Tuple[float, float, float]
    alternate_offset: Tuple[float, float, float]

minimum_version instance-attribute

writer_version instance-attribute

baseline_hdr_headroom instance-attribute

alternate_hdr_headroom instance-attribute

is_multichannel instance-attribute

use_base_colour_space instance-attribute

gainmap_min instance-attribute

gainmap_max instance-attribute

gainmap_gamma instance-attribute

baseline_offset instance-attribute

alternate_offset instance-attribute

HDRImage

Bases: TypedDict

HDR image representation with color metadata.

Contains linear or transfer-encoded RGB data with associated color space and transfer function information for proper display and conversion.

Required Attributes

data: Image data array, float32, shape (H, W, 3). For linear transfer: values in linear light, range [0, peak_luminance/reference_white]. For PQ transfer: values in range [0, 1] representing 0-10000 nits. For HLG transfer: values in range [0, 1] representing scene-referred light. transfer_function: Transfer function applied to the data. Options: 'linear', 'pq' (SMPTE ST 2084), 'hlg' (ITU-R BT.2100), 'srgb'.

Optional Attributes

color_space: Color primaries identifier. Options: 'bt709' (Rec. 709), 'p3' (Display P3), 'bt2020' (Rec. 2020). icc_profile: ICC profile bytes for custom color space definition.

See Also
  • gainmap_to_hdr: Create HDRImage from GainmapImage.
Source code in src/hdrconv/core/types.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
class HDRImage(TypedDict):
    """HDR image representation with color metadata.

    Contains linear or transfer-encoded RGB data with associated color space
    and transfer function information for proper display and conversion.

    Required Attributes:
        data: Image data array, float32, shape (H, W, 3).
            For linear transfer: values in linear light, range [0, peak_luminance/reference_white].
            For PQ transfer: values in range [0, 1] representing 0-10000 nits.
            For HLG transfer: values in range [0, 1] representing scene-referred light.
        transfer_function: Transfer function applied to the data.
            Options: 'linear', 'pq' (SMPTE ST 2084), 'hlg' (ITU-R BT.2100), 'srgb'.

    Optional Attributes:
        color_space: Color primaries identifier.
            Options: 'bt709' (Rec. 709), 'p3' (Display P3), 'bt2020' (Rec. 2020).
        icc_profile: ICC profile bytes for custom color space definition.

    See Also:
        - `gainmap_to_hdr`: Create HDRImage from GainmapImage.
    """

    data: Required[np.ndarray]
    transfer_function: Required[str]
    color_space: NotRequired[str]
    icc_profile: NotRequired[Optional[bytes]]

data instance-attribute

transfer_function instance-attribute

color_space instance-attribute

icc_profile instance-attribute