Color & Gain Map API¶

Color management, NCLX parameters, ICC profile synthesis, and ISO 21496-1 / Apple HDR Gain Map processing.

NCLX Color Profile¶

pylibheif.HeifColorProfileNclx ¶

HeifColorProfileNclx()

init(self, color_primaries: pylibheif._pylibheif.HeifColorPrimaries, transfer_characteristics: pylibheif._pylibheif.HeifTransferCharacteristics, matrix_coefficients: pylibheif._pylibheif.HeifMatrixCoefficients, full_range_flag: bool) -> None

module `class-attribute` ¶

__module__ = 'pylibheif._pylibheif'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

color_primaries `property` ¶

color_primaries

(self) -> pylibheif._pylibheif.HeifColorPrimaries

color_primary_blue_x `property` ¶

color_primary_blue_x

(self) -> float

color_primary_blue_y `property` ¶

color_primary_blue_y

(self) -> float

color_primary_green_x `property` ¶

color_primary_green_x

(self) -> float

color_primary_green_y `property` ¶

color_primary_green_y

(self) -> float

color_primary_red_x `property` ¶

color_primary_red_x

(self) -> float

color_primary_red_y `property` ¶

color_primary_red_y

(self) -> float

color_primary_white_x `property` ¶

color_primary_white_x

(self) -> float

color_primary_white_y `property` ¶

color_primary_white_y

(self) -> float

full_range_flag `property` ¶

full_range_flag

(self) -> bool

matrix_coefficients `property` ¶

matrix_coefficients

(self) -> pylibheif._pylibheif.HeifMatrixCoefficients

transfer_characteristics `property` ¶

transfer_characteristics

(self) -> pylibheif._pylibheif.HeifTransferCharacteristics

new `builtin` ¶

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

repr `method descriptor` ¶

__repr__()

repr(self) -> str

Gain Map Metadata¶

pylibheif.gain_map.GainMapMetadata ¶

GainMapMetadata(gain_map_min: Tuple[float, float, float] = <factory>, gain_map_max: Tuple[float, float, float] = <factory>, gamma: Tuple[float, float, float] = <factory>, offset_sdr: Tuple[float, float, float] = <factory>, offset_hdr: Tuple[float, float, float] = <factory>, hdr_capacity_min: float = 0.0, hdr_capacity_max: float = 2.0, base_rendition_is_hdr: bool = False, standard: str = 'dual')

Gain Map metadata according to ISO 21496-1 & Apple HDRGainMap standards.

Attributes:

Name	Type	Description
`gain_map_min`		Minimum boost in log2 scale (stops), per channel (R, G, B).
`gain_map_max`		Maximum boost in log2 scale (stops), per channel (R, G, B). For example, 2.0 corresponds to 4x (2^2) maximum brightness boost.
`gamma`		Exponent applied to the normalized gain map value, per channel (R, G, B).
`offset_sdr`		SDR offset to avoid division by zero and handle dark levels, per channel.
`offset_hdr`		HDR offset to avoid negative values and handle dark levels, per channel.
`hdr_capacity_min`		Minimum HDR capacity required to start applying gain map (usually 1.0).
`hdr_capacity_max`		HDR capacity at which maximum gain is applied (e.g. 4.0 for 2 stops).
`base_rendition_is_hdr`		True if the base image is HDR and gain map maps down to SDR; False if base image is SDR and gain map maps up to HDR (standard).
`standard`		Metadata standard format ("iso_21496_1", "apple", or "dual").

annotations `class-attribute` ¶

__annotations__ = {'gain_map_min': 'Tuple[float, float, float]', 'gain_map_max': 'Tuple[float, float, float]', 'gamma': 'Tuple[float, float, float]', 'offset_sdr': 'Tuple[float, float, float]', 'offset_hdr': 'Tuple[float, float, float]', 'hdr_capacity_min': 'float', 'hdr_capacity_max': 'float', 'base_rendition_is_hdr': 'bool', 'standard': 'str'}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

__dataclass_fields__ `class-attribute` ¶

__dataclass_fields__ = {'gain_map_min': Field(name='gain_map_min',type='Tuple[float, float, float]',default=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,default_factory=<function GainMapMetadata.<lambda> at 0x7fed61fc8e00>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'gain_map_max': Field(name='gain_map_max',type='Tuple[float, float, float]',default=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,default_factory=<function GainMapMetadata.<lambda> at 0x7fed61fc8ea0>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'gamma': Field(name='gamma',type='Tuple[float, float, float]',default=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,default_factory=<function GainMapMetadata.<lambda> at 0x7fed61fc8f40>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'offset_sdr': Field(name='offset_sdr',type='Tuple[float, float, float]',default=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,default_factory=<function GainMapMetadata.<lambda> at 0x7fed61fc8fe0>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'offset_hdr': Field(name='offset_hdr',type='Tuple[float, float, float]',default=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,default_factory=<function GainMapMetadata.<lambda> at 0x7fed61fc9080>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'hdr_capacity_min': Field(name='hdr_capacity_min',type='float',default=0.0,default_factory=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'hdr_capacity_max': Field(name='hdr_capacity_max',type='float',default=2.0,default_factory=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'base_rendition_is_hdr': Field(name='base_rendition_is_hdr',type='bool',default=False,default_factory=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'standard': Field(name='standard',type='str',default='dual',default_factory=<dataclasses._MISSING_TYPE object at 0x7fed6611dd00>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

doc `class-attribute` ¶

__doc__ = 'Gain Map metadata according to ISO 21496-1 & Apple HDRGainMap standards.\n\n    Attributes:\n        gain_map_min: Minimum boost in log2 scale (stops), per channel (R, G, B).\n        gain_map_max: Maximum boost in log2 scale (stops), per channel (R, G, B).\n                      For example, 2.0 corresponds to 4x (2^2) maximum brightness boost.\n        gamma: Exponent applied to the normalized gain map value, per channel (R, G, B).\n        offset_sdr: SDR offset to avoid division by zero and handle dark levels, per channel.\n        offset_hdr: HDR offset to avoid negative values and handle dark levels, per channel.\n        hdr_capacity_min: Minimum HDR capacity required to start applying gain map (usually 1.0).\n        hdr_capacity_max: HDR capacity at which maximum gain is applied (e.g. 4.0 for 2 stops).\n        base_rendition_is_hdr: True if the base image is HDR and gain map maps down to SDR;\n                               False if base image is SDR and gain map maps up to HDR (standard).\n        standard: Metadata standard format ("iso_21496_1", "apple", or "dual").\n    '

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__match_args__ `class-attribute` ¶

__match_args__ = ('gain_map_min', 'gain_map_max', 'gamma', 'offset_sdr', 'offset_hdr', 'hdr_capacity_min', 'hdr_capacity_max', 'base_rendition_is_hdr', 'standard')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

module `class-attribute` ¶

__module__ = 'pylibheif.gain_map'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

weakref `property` ¶

__weakref__

list of weak references to the object

base_rendition_is_hdr `class-attribute` ¶

base_rendition_is_hdr = False

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

format_type `property` ¶

format_type

Format identifier: 'Apple' or 'ISO'.

hdr_capacity_max `class-attribute` ¶

hdr_capacity_max = 2.0

Convert a string or number to a floating-point number, if possible.

hdr_capacity_min `class-attribute` ¶

hdr_capacity_min = 0.0

Convert a string or number to a floating-point number, if possible.

is_monochrome `property` ¶

is_monochrome

True if all parameters are identical across R, G, B channels.

max_content_boost `property` ¶

max_content_boost

Maximum luminance boost factor (linear scale).

standard `class-attribute` ¶

standard = 'dual'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

from_scalar `classmethod` ¶

from_scalar(max_boost_stops: float = 2.0, min_boost_stops: float = 0.0, gamma: float = 1.0, offset: float = 0.015625, hdr_capacity_max: Optional[float] = None, standard: str = 'dual') -> GainMapMetadata

Convenience constructor from single scalar values.

from_xmp `classmethod` ¶

from_xmp(xmp_data: Union[bytes, str]) -> Optional[GainMapMetadata]

Parse Gain Map metadata from XMP bytes or XML string.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary representation.

to_xmp ¶

to_xmp(format_type: Optional[str] = None) -> bytes

Serialize metadata into XMP bytes.

Color Management Functions¶

pylibheif.color.transform_colorspace ¶

transform_colorspace(image: Union[ndarray, Any], src_profile: Union[bytes, str], dst_profile: Union[bytes, str] = 'sRGB', intent: Union[RenderingIntent, int, str] = <RenderingIntent.PERCEPTUAL: 0>, bpc: bool = True, as_pillow: bool = False) -> Union[np.ndarray, Any]

Transform image pixels from src_profile to dst_profile with ICC accuracy.

Features: - Decouples and perfectly preserves Alpha transparency (RGBA -> RGB -> RGBA). - Preserves high bit-depth (10-bit / 12-bit / 16-bit). - Caches transform pipeline for high throughput. - Pure NumPy Bradford chromatic adaptation fallback if Pillow/ImageCms is absent.

Parameters:

Name	Type	Description	Default
`image`	`Union[ndarray, Any]`	Numpy array (H, W, 3) or (H, W, 4) or PIL Image.	required
`src_profile`	`Union[bytes, str]`	Source ICC bytes or standard name ("Display P3", "Adobe RGB", etc.).	required
`dst_profile`	`Union[bytes, str]`	Destination ICC bytes or standard name ("sRGB", "Display P3", etc.).	`'sRGB'`
`intent`	`Union[RenderingIntent, int, str]`	ICC rendering intent (PERCEPTUAL, RELATIVE_COLORIMETRIC, etc.).	`<RenderingIntent.PERCEPTUAL: 0>`
`bpc`	`bool`	Enable Black Point Compensation.	`True`
`as_pillow`	`bool`	Return a PIL Image instead of a NumPy array.	`False`

Returns:

Type	Description
`Union[ndarray, Any]`	Transformed image in destination color space.

pylibheif.color.nclx_to_icc_profile ¶

nclx_to_icc_profile(nclx: Any) -> bytes

Map NCLX/CICP parameters from HEIF/AVIF container to standard ICC profile bytes.

Parameters:

Name	Type	Description	Default
`nclx`	`Any`	HeifColorProfileNclx instance or object with color_primaries attribute.	required

Returns:

Type	Description
`bytes`	Canonical ICC profile bytes (Display P3, Rec.2020, or sRGB).

pylibheif.color.get_profile_info ¶

get_profile_info(profile: Union[bytes, str]) -> Dict[str, Any]

Inspect and extract human-readable metadata from an ICC profile.

HDR Reconstruction Functions¶

pylibheif.gain_map.reconstruct_hdr ¶

reconstruct_hdr(sdr_image: Any, gain_map: Any, metadata: Optional[GainMapMetadata] = None, target_headroom: Optional[float] = None, output_format: str = 'linear', dtype: Any = float32, display_boost: Optional[float] = None) -> np.ndarray

Reconstruct an HDR image from an SDR base image, Gain Map, and ISO 21496-1 metadata.

Parameters:

Name	Type	Description	Default
`sdr_image`	`Any`	8-bit SDR image (numpy array shape (H, W, 3) or (H, W, 4), or PIL.Image).	required
`gain_map`	`Any`	Gain Map image (1-channel monochrome or 3-channel RGB).	required
`metadata`	`Optional[GainMapMetadata]`	GainMapMetadata instance. If None, default 4x boost (2.0 stops) is used.	`None`
`target_headroom`	`Optional[float]`	Desired display headroom multiplier (e.g. 2.0 or 4.0). If None, uses metadata.hdr_capacity_max (full HDR capability).	`None`
`output_format`	`str`	Output image format: - "linear" / "linear_float32" / "linear_float16": Normalized linear RGB light. - "pq" / "pq_uint16": Rec.2100 PQ ST 2084 integer format (uint16 array 0..65535). - "srgb_clip" / "srgb_uint8" / "srgb": Tonemapped back to standard 8-bit sRGB (uint8 array 0..255).	`'linear'`
`dtype`	`Any`	Numerical data type for linear computations (np.float32 or np.float16).	`float32`
`display_boost`	`Optional[float]`	Alias for target_headroom.	`None`

Returns:

Type	Description
`ndarray`	Reconstructed HDR numpy array in the requested output_format.

pylibheif.gain_map.parse_gain_map_metadata ¶

parse_gain_map_metadata(xmp_data: Union[bytes, str]) -> Optional[GainMapMetadata]

Parse Gain Map metadata from XMP bytes, binary box payload, or XML string.

Supports: - ISO 21496-1 (urn:iso:std:iso:ts:21496-1 or http://iso.org/gainmap/1.0/) - Apple HDRGainMap (http://ns.apple.com/HDRGainMap/1.0/) - Adobe Ultra HDR (http://ns.adobe.com/hdr-gain-map/1.0/)

Color & Gain Map API¶

NCLX Color Profile¶

pylibheif.HeifColorProfileNclx ¶

__module__ class-attribute ¶

color_primaries property ¶

color_primary_blue_x property ¶

color_primary_blue_y property ¶

color_primary_green_x property ¶

color_primary_green_y property ¶

color_primary_red_x property ¶

color_primary_red_y property ¶

color_primary_white_x property ¶

color_primary_white_y property ¶

full_range_flag property ¶

matrix_coefficients property ¶

transfer_characteristics property ¶

__new__ builtin ¶

__repr__ method descriptor ¶

Gain Map Metadata¶

pylibheif.gain_map.GainMapMetadata ¶

__annotations__ class-attribute ¶

__dataclass_fields__ class-attribute ¶

__doc__ class-attribute ¶

__match_args__ class-attribute ¶

__module__ class-attribute ¶

__weakref__ property ¶

base_rendition_is_hdr class-attribute ¶

format_type property ¶

hdr_capacity_max class-attribute ¶

hdr_capacity_min class-attribute ¶

is_monochrome property ¶

max_content_boost property ¶

standard class-attribute ¶

from_scalar classmethod ¶

from_xmp classmethod ¶

to_dict ¶

to_xmp ¶

Color Management Functions¶

pylibheif.color.transform_colorspace ¶

pylibheif.color.nclx_to_icc_profile ¶

pylibheif.color.get_profile_info ¶

HDR Reconstruction Functions¶

pylibheif.gain_map.reconstruct_hdr ¶

pylibheif.gain_map.parse_gain_map_metadata ¶

module `class-attribute` ¶

color_primaries `property` ¶

color_primary_blue_x `property` ¶

color_primary_blue_y `property` ¶

color_primary_green_x `property` ¶

color_primary_green_y `property` ¶

color_primary_red_x `property` ¶

color_primary_red_y `property` ¶

color_primary_white_x `property` ¶

color_primary_white_y `property` ¶

full_range_flag `property` ¶

matrix_coefficients `property` ¶

transfer_characteristics `property` ¶

new `builtin` ¶

repr `method descriptor` ¶

annotations `class-attribute` ¶

__dataclass_fields__ `class-attribute` ¶

doc `class-attribute` ¶

__match_args__ `class-attribute` ¶

module `class-attribute` ¶

weakref `property` ¶

base_rendition_is_hdr `class-attribute` ¶

format_type `property` ¶

hdr_capacity_max `class-attribute` ¶

hdr_capacity_min `class-attribute` ¶

is_monochrome `property` ¶

max_content_boost `property` ¶

standard `class-attribute` ¶

from_scalar `classmethod` ¶

from_xmp `classmethod` ¶