I/O

hdrconv.io

HDR format I/O operations.

This module provides functions for reading and writing various HDR formats:

• ISO 21496-1 (Adaptive Gainmap): read_21496, write_21496
• ISO 22028-5 (PQ/HLG AVIF): read_22028_pq, write_22028_pq
• Apple HEIC with gainmap: read_apple_heic
• iOS HDR screenshot: read_ios_hdr_screenshot

read_21496(filepath)

Read an ISO 21496-1 Gainmap image.

Routes JPEG files to the MPF parser and HEIF/AVIF files to the ISOBMFF parser.

Source code in src/hdrconv/io/iso21496.py

def read_21496(filepath: str) -> GainmapImage:
    """Read an ISO 21496-1 Gainmap image.

    Routes JPEG files to the MPF parser and HEIF/AVIF files to the ISOBMFF
    parser.
    """
    container = _detect_21496_container(filepath)
    if container == "jpeg":
        return _read_21496_jpeg(filepath)
    if container == "isobmff":
        return _read_21496_isobmff(filepath)

    raise ValueError(f"Unsupported ISO 21496-1 container format: {filepath}")

write_21496(data, filepath, baseline_quality=95, gainmap_quality=95)

Write ISO 21496-1 Gainmap JPEG file.

Creates a JPEG file with ISO 21496-1 compliant gainmap structure using Multi-Picture Format (MPF) container.

Parameters:

Name	Type	Description	Default
data	GainmapImage	GainmapImage dict containing: - baseline: SDR image, uint8, shape (H, W, 3). - gainmap: Gain map, uint8, shape (H, W, 3) or (H, W, 1). - metadata: GainmapMetadata with transformation parameters. - baseline_icc: Optional ICC profile for baseline. - gainmap_icc: Optional ICC profile for gainmap.	required
filepath	str	Output path for the JPEG file.	required
baseline_quality	int	JPEG quality for baseline image (1-100, default 95).	95
gainmap_quality	int	JPEG quality for gainmap image (1-100, default 95).	95

Raises:

Type	Description
RuntimeError	If file writing fails.

Note

The output file structure places the baseline image first with an MPF index, followed by the gainmap with ISO 21496-1 metadata. JPEG quality is set to 95 with 4:4:4 chroma subsampling.

See Also

• read_21496: Read ISO 21496-1 Gainmap JPEG.
• hdr_to_gainmap: Convert HDR image to GainmapImage.

Source code in src/hdrconv/io/iso21496.py

def write_21496(
    data: GainmapImage,
    filepath: str,
    baseline_quality: int = 95,
    gainmap_quality: int = 95,
) -> None:
    """Write ISO 21496-1 Gainmap JPEG file.

    Creates a JPEG file with ISO 21496-1 compliant gainmap structure using
    Multi-Picture Format (MPF) container.

    Args:
        data: GainmapImage dict containing:
            - ``baseline``: SDR image, uint8, shape (H, W, 3).
            - ``gainmap``: Gain map, uint8, shape (H, W, 3) or (H, W, 1).
            - ``metadata``: GainmapMetadata with transformation parameters.
            - ``baseline_icc``: Optional ICC profile for baseline.
            - ``gainmap_icc``: Optional ICC profile for gainmap.
        filepath: Output path for the JPEG file.
        baseline_quality: JPEG quality for baseline image (1-100, default 95).
        gainmap_quality: JPEG quality for gainmap image (1-100, default 95).

    Raises:
        RuntimeError: If file writing fails.

    Note:
        The output file structure places the baseline image first with an
        MPF index, followed by the gainmap with ISO 21496-1 metadata.
        JPEG quality is set to 95 with 4:4:4 chroma subsampling.

    See Also:
        - `read_21496`: Read ISO 21496-1 Gainmap JPEG.
        - `hdr_to_gainmap`: Convert HDR image to GainmapImage.
    """
    try:
        # Step 1: Encode gainmap image
        gainmap_bytes_raw = _create_jpeg_bytes(
            data["gainmap"], data.get("gainmap_icc"), gainmap_quality
        )

        # Step 1.1: Insert minimal MPF APP2 in gainmap stream for compatibility
        gainmap_mpf_segment = _build_app2_segment(_build_mpf_minimal_payload(2))

        # Step 2: Build ISO 21496-1 metadata segment (APP2)
        iso_payload = _encode_iso21496_metadata(data["metadata"])
        iso_segment = _build_app2_segment(iso_payload)

        # Insert ISO segment after SOI (0xFFD8) in gainmap
        gainmap_final = (
            gainmap_bytes_raw[:2]
            + gainmap_mpf_segment
            + iso_segment
            + gainmap_bytes_raw[2:]
        )

        # Step 3: Encode baseline image
        primary_bytes_raw = _create_jpeg_bytes(
            data["baseline"], data.get("baseline_icc"), baseline_quality
        )

        # Step 3.1: Insert URN stub APP2 in primary stream for compatibility
        primary_stub_segment = _build_app2_segment(ISO21496_URN + b"\x00\x00\x00\x00")

        # Step 4: Build MPF index segment (APP2)
        # MPF points to gainmap at end of file

        # Step 4.1: Generate MPF payload with placeholder offset for length calculation
        mpf_payload_temp = _build_mpf_payload(
            primary_size=len(primary_bytes_raw),
            gainmap_size=len(gainmap_final),
            gainmap_offset=0,  # Placeholder
        )
        mpf_segment_temp = _build_app2_segment(mpf_payload_temp)

        # Step 4.2: Calculate MPF-related file offsets
        _, gainmap_relative_offset, total_primary_len = _calculate_mpf_offsets(
            primary_bytes_raw,
            primary_stub_segment,
            mpf_segment_temp,
        )

        # Step 4.3: Regenerate MPF with correct primary size and gainmap offset
        mpf_payload_final = _build_mpf_payload(
            primary_size=total_primary_len,
            gainmap_size=len(gainmap_final),
            gainmap_offset=gainmap_relative_offset,
        )
        mpf_segment_final = _build_app2_segment(mpf_payload_final)

        # Step 5: Assemble baseline stream with MPF
        primary_final = (
            primary_bytes_raw[:2]
            + primary_stub_segment
            + mpf_segment_final
            + primary_bytes_raw[2:]
        )

        # Step 6: Write file (baseline + gainmap)
        with open(filepath, "wb") as f:
            f.write(primary_final)
            f.write(gainmap_final)

    except Exception as e:
        raise RuntimeError(f"Failed to write ISO 21496-1 file: {filepath}") from e

read_22028_pq(filepath)

Read ISO 22028-5 PQ AVIF file.

Decodes an AVIF file encoded with Perceptual Quantizer (PQ) transfer function as specified in ISO 22028-5 and SMPTE ST 2084.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the PQ AVIF file.	required

Returns:

Type	Description
HDRImage	HDRImage dict containing:
HDRImage	data (np.ndarray): PQ-encoded array, float32, shape (H, W, 3), range [0, 1] representing 0-10000 nits.
HDRImage	color_space (str): Color primaries, typically 'bt2020'.
HDRImage	transfer_function (str): Always 'pq'.
HDRImage	icc_profile (bytes | None): Currently None (not extracted).

Note

Currently assumes BT.2020 color primaries and 10-bit decode range. Future versions may extract actual color metadata from AVIF.

See Also

• write_22028_pq: Write HDR image to PQ AVIF format.
• inverse_pq: Convert PQ-encoded data to linear light.

Source code in src/hdrconv/io/iso22028.py

def read_22028_pq(filepath: str) -> HDRImage:
    """Read ISO 22028-5 PQ AVIF file.

    Decodes an AVIF file encoded with Perceptual Quantizer (PQ) transfer
    function as specified in ISO 22028-5 and SMPTE ST 2084.

    Args:
        filepath: Path to the PQ AVIF file.

    Returns:
        HDRImage dict containing:
        - ``data`` (np.ndarray): PQ-encoded array, float32, shape (H, W, 3),
            range [0, 1] representing 0-10000 nits.
        - ``color_space`` (str): Color primaries, typically 'bt2020'.
        - ``transfer_function`` (str): Always 'pq'.
        - ``icc_profile`` (bytes | None): Currently None (not extracted).

    Note:
        Currently assumes BT.2020 color primaries and 10-bit decode range.
        Future versions may extract actual color metadata from AVIF.

    See Also:
        - `write_22028_pq`: Write HDR image to PQ AVIF format.
        - `inverse_pq`: Convert PQ-encoded data to linear light.
    """
    with open(filepath, "rb") as f:
        avif_bytes = f.read()
    image_array = avif_decode(avif_bytes, numthreads=-1)
    # Extract PQ-encoded array (normalized to [0, 1])
    # Currently hard-coded to 10-bit decode range.
    image_array = image_array / 1023.0
    # BT.2020 PQ is the most common format for HDR AVIF files
    return HDRImage(
        data=image_array,
        color_space="bt2020",
        transfer_function="pq",
        icc_profile=None,
    )

write_22028_pq(data, filepath)

Write ISO 22028-5 PQ AVIF file.

Encodes an HDR image to AVIF format with Perceptual Quantizer (PQ) transfer function as specified in ISO 22028-5 and SMPTE ST 2084.

Parameters:

Name	Type	Description	Default
data	HDRImage	HDRImage dict with PQ-encoded data. Must contain: - data: float32 array, shape (H, W, 3), range [0, 1]. - color_space: Color primaries ('bt709', 'p3', 'bt2020'). - transfer_function: Transfer function ('pq', 'hlg', etc.).	required
filepath	str	Output path for the AVIF file.	required

Note

Output is encoded at 10-bit depth with quality level 90. Color primaries and transfer characteristics are embedded in AVIF metadata.

See Also

• read_22028_pq: Read PQ AVIF file.
• apply_pq: Convert linear HDR to PQ-encoded values.

Source code in src/hdrconv/io/iso22028.py

def write_22028_pq(data: HDRImage, filepath: str) -> None:
    """Write ISO 22028-5 PQ AVIF file.

    Encodes an HDR image to AVIF format with Perceptual Quantizer (PQ)
    transfer function as specified in ISO 22028-5 and SMPTE ST 2084.

    Args:
        data: HDRImage dict with PQ-encoded data. Must contain:
            - ``data``: float32 array, shape (H, W, 3), range [0, 1].
            - ``color_space``: Color primaries ('bt709', 'p3', 'bt2020').
            - ``transfer_function``: Transfer function ('pq', 'hlg', etc.).
        filepath: Output path for the AVIF file.

    Note:
        Output is encoded at 10-bit depth with quality level 90.
        Color primaries and transfer characteristics are embedded in AVIF metadata.

    See Also:
        - `read_22028_pq`: Read PQ AVIF file.
        - `apply_pq`: Convert linear HDR to PQ-encoded values.
    """
    # Map color primaries to numeric codes
    primaries_map = {"bt709": 1, "bt2020": 9, "p3": 12}

    # Map transfer characteristics to numeric codes
    transfer_map = {"bt709": 1, "linear": 8, "pq": 16, "hlg": 18}

    primaries_code = primaries_map.get(data["color_space"], 9)
    transfer_code = transfer_map.get(data["transfer_function"], 16)

    np_array = np.clip(data["data"], 0, 1)
    # scale to [0, 1023]
    np_array = np_array * 1023.0
    np_array = np_array.astype(np.uint16)

    avif_bytes: bytes = avif_encode(
        np_array,
        level=90,
        speed=8,
        bitspersample=10,
        primaries=primaries_code,
        transfer=transfer_code,
        numthreads=-1,
    )

    # Write the AVIF bytes to the output file
    with open(filepath, "wb") as f:
        f.write(avif_bytes)

read_apple_heic(filepath)

Read Apple HEIC HDR file with gain map.

Extracts the base SDR image, HDR gain map, and headroom metadata from iPhone HEIC photos containing Apple's proprietary HDR format.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the Apple HEIC file.	required

Returns:

Type	Description
AppleHeicData	AppleHeicData dict containing:
AppleHeicData	base (np.ndarray): SDR image, uint8, shape (H, W, 3), Display P3.
AppleHeicData	gainmap (np.ndarray): Gain map, uint8, shape (H, W, 1), 1/4 resolution.
AppleHeicData	headroom (float): Peak luminance headroom, typically 2.0-8.0.

Raises:

Type	Description
ValueError	If base image, gainmap, or headroom cannot be extracted.

Note

Requires exiftool to be installed and accessible in PATH for headroom extraction from EXIF/MakerNotes metadata.

See Also

• apple_heic_to_hdr: Convert AppleHeicData to linear HDR.
• has_gain_map: Check if HEIC file contains gain map.

Source code in src/hdrconv/io/apple_heic.py

def read_apple_heic(filepath: str) -> AppleHeicData:
    """Read Apple HEIC HDR file with gain map.

    Extracts the base SDR image, HDR gain map, and headroom metadata from
    iPhone HEIC photos containing Apple's proprietary HDR format.

    Args:
        filepath: Path to the Apple HEIC file.

    Returns:
        AppleHeicData dict containing:
        - ``base`` (np.ndarray): SDR image, uint8, shape (H, W, 3), Display P3.
        - ``gainmap`` (np.ndarray): Gain map, uint8, shape (H, W, 1), 1/4 resolution.
        - ``headroom`` (float): Peak luminance headroom, typically 2.0-8.0.

    Raises:
        ValueError: If base image, gainmap, or headroom cannot be extracted.

    Note:
        Requires exiftool to be installed and accessible in PATH for
        headroom extraction from EXIF/MakerNotes metadata.

    See Also:
        - `apple_heic_to_hdr`: Convert AppleHeicData to linear HDR.
        - `has_gain_map`: Check if HEIC file contains gain map.
    """

    base, gainmap = read_base_and_gain_map(filepath)
    headroom = get_headroom(filepath)

    if base is None or gainmap is None or headroom is None:
        raise ValueError(f"Failed to read Apple HEIC data from {filepath}")

    return AppleHeicData(base=base, gainmap=gainmap, headroom=headroom)

read_ios_hdr_screenshot(filepath, grid_cols=None, grid_rows=None, tile_size=512, real_width=None, real_height=None)

Read iOS HDR screenshot HEIC file.

Extracts the main image, gainmap, and metadata from iOS HDR screenshots and returns a standard GainmapImage structure suitable for use with gainmap_to_hdr.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the iOS HDR screenshot HEIC file.	required
grid_cols	Optional[int]	Number of tile columns (auto-detected if None).	None
grid_rows	Optional[int]	Number of tile rows (auto-detected if None).	None
tile_size	int	Size of each square tile in pixels. Default: 512.	512
real_width	Optional[int]	Actual image width (auto-detected if None).	None
real_height	Optional[int]	Actual image height (auto-detected if None).	None

Returns:

Type	Description
GainmapImage	GainmapImage dict containing:
GainmapImage	baseline (np.ndarray): Main image, uint8, shape (H, W, 3), Display P3.
GainmapImage	gainmap (np.ndarray): Gain map, uint8, shape (H, W, 3), three-channel.
GainmapImage	metadata (GainmapMetadata): Contains gainmap_max, offset values.
GainmapImage	baseline_icc (bytes | None): None.
GainmapImage	gainmap_icc (bytes | None): None.

Raises:

Type	Description
RuntimeError	If external tools (MP4Box, ffmpeg) are not available.
ValueError	If the file cannot be parsed or is not a valid iOS HDR screenshot.
FileNotFoundError	If the input file does not exist.

Note

Requires MP4Box (from GPAC) and ffmpeg to be installed and available in PATH.

The gainmap_min is always 0 and gainmap_gamma is always 1 for iOS HDR screenshots. Both baseline_offset and alternate_offset are set to the same value extracted from the tmap metadata.

See Also

• gainmap_to_hdr: Convert the returned GainmapImage to linear HDR.

Source code in src/hdrconv/io/ios_hdr_screenshot.py

def read_ios_hdr_screenshot(
    filepath: str,
    grid_cols: Optional[int] = None,
    grid_rows: Optional[int] = None,
    tile_size: int = 512,
    real_width: Optional[int] = None,
    real_height: Optional[int] = None,
) -> GainmapImage:
    """Read iOS HDR screenshot HEIC file.

    Extracts the main image, gainmap, and metadata from iOS HDR screenshots
    and returns a standard GainmapImage structure suitable for use with
    `gainmap_to_hdr`.

    Args:
        filepath: Path to the iOS HDR screenshot HEIC file.
        grid_cols: Number of tile columns (auto-detected if None).
        grid_rows: Number of tile rows (auto-detected if None).
        tile_size: Size of each square tile in pixels. Default: 512.
        real_width: Actual image width (auto-detected if None).
        real_height: Actual image height (auto-detected if None).

    Returns:
        GainmapImage dict containing:
        - ``baseline`` (np.ndarray): Main image, uint8, shape (H, W, 3), Display P3.
        - ``gainmap`` (np.ndarray): Gain map, uint8, shape (H, W, 3), three-channel.
        - ``metadata`` (GainmapMetadata): Contains gainmap_max, offset values.
        - ``baseline_icc`` (bytes | None): None.
        - ``gainmap_icc`` (bytes | None): None.

    Raises:
        RuntimeError: If external tools (MP4Box, ffmpeg) are not available.
        ValueError: If the file cannot be parsed or is not a valid iOS HDR screenshot.
        FileNotFoundError: If the input file does not exist.

    Note:
        Requires MP4Box (from GPAC) and ffmpeg to be installed and available in PATH.

        The gainmap_min is always 0 and gainmap_gamma is always 1 for iOS HDR screenshots.
        Both baseline_offset and alternate_offset are set to the same value extracted
        from the tmap metadata.

    See Also:
        - `gainmap_to_hdr`: Convert the returned GainmapImage to linear HDR.
    """
    # Check dependencies
    available, missing = _check_dependencies()
    if not available:
        raise RuntimeError(
            f"Missing required external tools: {', '.join(missing)}. "
            "Please install them and ensure they are in PATH."
        )

    if not os.path.exists(filepath):
        raise FileNotFoundError(f"File not found: {filepath}")

    # Create temp directory for processing
    temp_dir = tempfile.mkdtemp(prefix="ios_hdr_")

    try:
        # Get all hvc1 IDs
        all_ids = _get_hvc1_ids(filepath)
        if not all_ids:
            raise ValueError("No hvc1 streams found in file")

        # Split into groups (main image and gainmap)
        groups = _split_ids_into_groups(all_ids)
        if len(groups) < 2:
            raise ValueError(
                "Expected at least 2 image groups (main + gainmap), "
                f"found {len(groups)}"
            )

        main_ids = groups[0]
        gainmap_ids = groups[1]

        # Get original resolution from HEIC metadata if not provided.
        if real_width is None or real_height is None:
            orig_width, orig_height = _get_original_resolution(filepath)
            real_width = real_width or orig_width
            real_height = real_height or orig_height

        # Auto-detect grid parameters after original resolution is known.
        if grid_cols is None or grid_rows is None:
            # Extract first tile to detect size
            first_id = main_ids[0]
            raw_path = os.path.join(temp_dir, f"{first_id}.hvc")
            jpg_path = os.path.join(temp_dir, "first_tile.jpg")

            param = f"{first_id}:path={raw_path}"
            subprocess.run(
                ["MP4Box", "-dump-item", param, filepath],
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
            )
            subprocess.run(
                ["ffmpeg", "-y", "-i", raw_path, "-q:v", "2", jpg_path],
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
            )

            detected_cols, detected_rows, detected_tile_size = _detect_grid_parameters(
                len(main_ids),
                jpg_path,
                real_width=real_width,
                real_height=real_height,
            )
            grid_cols = grid_cols or detected_cols
            grid_rows = grid_rows or detected_rows
            tile_size = detected_tile_size

            # Clean up detection files
            if os.path.exists(raw_path):
                os.remove(raw_path)
            if os.path.exists(jpg_path):
                os.remove(jpg_path)

        # Process main image
        main_temp = os.path.join(temp_dir, "main")
        os.makedirs(main_temp, exist_ok=True)
        main_image = _process_tile_group(
            main_ids,
            filepath,
            main_temp,
            grid_cols,
            grid_rows,
            tile_size,
            real_width,
            real_height,
        )

        # Process gainmap
        gainmap_temp = os.path.join(temp_dir, "gainmap")
        os.makedirs(gainmap_temp, exist_ok=True)
        gainmap_image = _process_tile_group(
            gainmap_ids,
            filepath,
            gainmap_temp,
            grid_cols,
            grid_rows,
            tile_size,
            real_width,
            real_height,
        )

        # Parse tmap metadata
        tmap_data = _dump_tmap_bytes(filepath, temp_dir)
        if tmap_data is None:
            raise ValueError("No tmap metadata found in file")

        gainmapmax, offset = _parse_gainmapmax_offset_from_tmap(tmap_data)

        # Construct GainmapMetadata
        # iOS HDR screenshots use: gainmap_min=0, gamma=1, both offsets equal
        metadata = GainmapMetadata(
            minimum_version=0,
            writer_version=0,
            baseline_hdr_headroom=0.0,
            alternate_hdr_headroom=float(gainmapmax),
            is_multichannel=True,
            use_base_colour_space=True,
            gainmap_min=(0.0, 0.0, 0.0),
            gainmap_max=(gainmapmax, gainmapmax, gainmapmax),
            gainmap_gamma=(1.0, 1.0, 1.0),
            baseline_offset=(offset, offset, offset),
            alternate_offset=(offset, offset, offset),
        )

        # Ensure arrays are uint8
        if main_image.dtype != np.uint8:
            main_image = main_image.astype(np.uint8)
        if gainmap_image.dtype != np.uint8:
            gainmap_image = gainmap_image.astype(np.uint8)

        return GainmapImage(
            baseline=main_image,
            gainmap=gainmap_image,
            metadata=metadata,
            baseline_icc=None,
            gainmap_icc=None,
            baseline_bit_depth=10,
            gainmap_bit_depth=10,
        )

    finally:
        # Clean up temp directory
        shutil.rmtree(temp_dir, ignore_errors=True)

read_ultrahdr(filepath)

Read UltraHDR JPEG file.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the UltraHDR JPEG file.	required

Returns:

Type	Description
GainmapImage	GainmapImage dict containing baseline, gainmap, metadata, and ICC data.

Raises:

Type	Description
ValueError	If gainmap stream or HDR gainmap metadata is missing.

Source code in src/hdrconv/io/ultrahdr.py

def read_ultrahdr(filepath: str) -> GainmapImage:
    """Read UltraHDR JPEG file.

    Args:
        filepath: Path to the UltraHDR JPEG file.

    Returns:
        GainmapImage dict containing baseline, gainmap, metadata, and ICC data.

    Raises:
        ValueError: If gainmap stream or HDR gainmap metadata is missing.
    """
    with open(filepath, "rb") as f:
        raw_data = f.read()

    primary_data, gainmap_data = _split_mpf_container(raw_data)

    # Fallback: split by EOI+SOI if MPF is missing
    if not gainmap_data:
        separator = b"\xff\xd9\xff\xd8"
        split_pos = raw_data.find(separator)
        if split_pos != -1:
            primary_data = raw_data[: split_pos + 2]
            gainmap_data = raw_data[split_pos + 2 :]

    if not gainmap_data:
        raise ValueError("No gainmap found in container (MPF missing or invalid).")

    with warnings.catch_warnings():
        warnings.filterwarnings(
            "ignore",
            message="Image appears to be a malformed MPO file",
            category=UserWarning,
        )
        base_img = Image.open(io.BytesIO(primary_data)).convert("RGB")
        gain_img = Image.open(io.BytesIO(gainmap_data))
        if gain_img.mode not in ("L", "RGB"):
            gain_img = gain_img.convert("RGB")

    base_arr = np.array(base_img)
    gain_arr = np.array(gain_img)
    if gain_arr.ndim == 2:
        gain_arr = gain_arr[:, :, np.newaxis]
    elif gain_arr.ndim == 3 and gain_arr.shape[2] == 4:
        gain_arr = gain_arr[:, :, :3]

    base_segments = list(_yield_jpeg_segments(primary_data))
    gain_segments = list(_yield_jpeg_segments(gainmap_data))

    base_icc = _extract_icc(base_segments)
    gain_icc = _extract_icc(gain_segments)

    hdrgm_meta = None

    # Prefer gainmap stream
    for segments in [gain_segments, base_segments]:
        for code, payload in segments:
            if code == APP1:
                xmp_xml = _extract_xmp_payload(payload)
                if not xmp_xml:
                    continue
                parsed = _parse_hdrgm_metadata(xmp_xml)
                if parsed and ("GainMapMin" in parsed or "Version" in parsed):
                    hdrgm_meta = parsed
                    break
        if hdrgm_meta:
            break

    if not hdrgm_meta:
        raise ValueError("UltraHDR gainmap metadata (XMP) not found.")

    metadata = _hdrgm_to_gainmap_metadata(hdrgm_meta, gain_arr)

    return GainmapImage(
        baseline=base_arr,
        gainmap=gain_arr,
        metadata=metadata,
        baseline_icc=base_icc,
        gainmap_icc=gain_icc,
        baseline_bit_depth=8,
        gainmap_bit_depth=8,
    )

write_ultrahdr(data, filepath, baseline_quality=95, gainmap_quality=95)

Write UltraHDR JPEG file.

Parameters:

Name	Type	Description	Default
data	GainmapImage	GainmapImage dict containing baseline, gainmap, and metadata.	required
filepath	str	Output path for the JPEG file.	required
baseline_quality	int	JPEG quality for baseline image (1-100, default 95).	95
gainmap_quality	int	JPEG quality for gainmap image (1-100, default 95).	95

Source code in src/hdrconv/io/ultrahdr.py

def write_ultrahdr(
    data: GainmapImage,
    filepath: str,
    baseline_quality: int = 95,
    gainmap_quality: int = 95,
) -> None:
    """Write UltraHDR JPEG file.

    Args:
        data: GainmapImage dict containing baseline, gainmap, and metadata.
        filepath: Output path for the JPEG file.
        baseline_quality: JPEG quality for baseline image (1-100, default 95).
        gainmap_quality: JPEG quality for gainmap image (1-100, default 95).
    """
    try:
        gainmap_bytes_raw = _create_jpeg_bytes(
            data["gainmap"], data.get("gainmap_icc"), gainmap_quality
        )

        # Insert minimal MPF APP2 in gainmap stream for compatibility
        gainmap_mpf_segment = _build_app2_segment(_build_mpf_minimal_payload(2))

        xmp_payload = _build_hdrgm_xmp(data["metadata"])
        xmp_segment = _build_app1_segment(xmp_payload)

        gainmap_final = (
            gainmap_bytes_raw[:2]
            + gainmap_mpf_segment
            + xmp_segment
            + gainmap_bytes_raw[2:]
        )

        primary_bytes_raw = _create_jpeg_bytes(
            data["baseline"], data.get("baseline_icc"), baseline_quality
        )

        gcontainer_payload = _build_gcontainer_xmp(len(gainmap_final))
        gcontainer_segment = _build_app1_segment(gcontainer_payload)

        mpf_payload_temp = _build_mpf_payload(
            primary_size=len(primary_bytes_raw),
            gainmap_size=len(gainmap_final),
            gainmap_offset=0,
        )
        mpf_segment_temp = _build_app2_segment(mpf_payload_temp)

        total_primary_len = (
            len(primary_bytes_raw) + len(gcontainer_segment) + len(mpf_segment_temp)
        )

        mpf_marker_offset = 2 + len(gcontainer_segment)
        mpf_base_file_offset = mpf_marker_offset + 8
        gainmap_relative_offset = total_primary_len - mpf_base_file_offset

        mpf_payload_final = _build_mpf_payload(
            primary_size=total_primary_len,
            gainmap_size=len(gainmap_final),
            gainmap_offset=gainmap_relative_offset,
        )
        mpf_segment_final = _build_app2_segment(mpf_payload_final)

        primary_final = (
            primary_bytes_raw[:2]
            + gcontainer_segment
            + mpf_segment_final
            + primary_bytes_raw[2:]
        )

        with open(filepath, "wb") as f:
            f.write(primary_final)
            f.write(gainmap_final)

    except Exception as e:
        raise RuntimeError(f"Failed to write UltraHDR file: {filepath}") from e