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 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
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, shape (H, W, 3).
gainmap ndarray

numpy array, shape (H, W, 3) or (H, W, 1).
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.
baseline_bit_depth NotRequired[int]

Optional integer sample bit depth read from the source file.
gainmap_bit_depth NotRequired[int]

Optional integer sample bit depth read from the source file.
Source code in src/hdrconv/core/types.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
class GainmapImage(TypedDict):
    """ISO 21496-1 Gainmap image structure.

    Contains the baseline image, gainmap, and metadata.

    Attributes:
        baseline: numpy array, shape (H, W, 3).
        gainmap: numpy array, shape (H, W, 3) or (H, W, 1).
        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_bit_depth: Optional integer sample bit depth read from the source file.
        gainmap_bit_depth: Optional integer sample bit depth read from the source file.
    """

    baseline: np.ndarray
    gainmap: np.ndarray
    metadata: GainmapMetadata
    baseline_icc: Optional[bytes]
    gainmap_icc: Optional[bytes]
    baseline_bit_depth: NotRequired[int]
    gainmap_bit_depth: NotRequired[int]

baseline instance-attribute

gainmap instance-attribute

metadata instance-attribute

baseline_icc instance-attribute

gainmap_icc instance-attribute

baseline_bit_depth instance-attribute

gainmap_bit_depth 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 ChannelValues

Minimum gainmap values, tuple of 1 or 3 floats.
gainmap_max ChannelValues

Maximum gainmap values, tuple of 1 or 3 floats.
gainmap_gamma ChannelValues

Gamma values for gainmap decoding, tuple of 1 or 3 floats.
baseline_offset ChannelValues

Offset added to baseline before multiplication, tuple of 1 or 3 floats.
alternate_offset ChannelValues

Offset subtracted from result, tuple of 1 or 3 floats.
Source code in src/hdrconv/core/types.py 
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
54
55
56
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, tuple of 1 or 3 floats.
        gainmap_max: Maximum gainmap values, tuple of 1 or 3 floats.
        gainmap_gamma: Gamma values for gainmap decoding, tuple of 1 or 3 floats.
        baseline_offset: Offset added to baseline before multiplication, tuple of 1 or 3 floats.
        alternate_offset: Offset subtracted from result, tuple of 1 or 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: ChannelValues
    gainmap_max: ChannelValues
    gainmap_gamma: ChannelValues

    # Offset parameters
    baseline_offset: ChannelValues
    alternate_offset: ChannelValues

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 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
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