Skip to main content

Crate ultrahdr_rs

Crate ultrahdr_rs 

Source
Expand description

Ultra HDR - Pure Rust encoder/decoder for HDR images with gain maps.

Ultra HDR is an image format that stores HDR (High Dynamic Range) content in a backwards-compatible JPEG file. Legacy viewers see the SDR (Standard Dynamic Range) base image, while HDR-capable displays can reconstruct the full HDR content using an embedded gain map.

§Crate Structure

  • ultrahdr_core - Core gain map math and metadata (no codec dependency)
  • ultrahdr (this crate) - Full encoder/decoder (bring your own JPEG codec)

§Format Overview

An Ultra HDR JPEG contains:

  • Primary JPEG: SDR base image (8-bit, sRGB)
  • Gain map JPEG: Compressed ratio of HDR/SDR luminance
  • XMP metadata: Describes how to apply the gain map
  • MPF header: Multi-Picture Format container

§Example

ⓘ
use ultrahdr::{encode_ultrahdr, Decoder, GainMapMetadata, ColorGamut};
use ultrahdr::gainmap::compute::{compute_gainmap, GainMapConfig};

// 1. Prepare your images (using your own JPEG codec)
let sdr_jpeg = my_encoder.encode_rgb(&sdr_pixels)?;

// 2. Compute gain map from HDR and SDR
let config = GainMapConfig::default();
let (gainmap, metadata) = compute_gainmap(&hdr, &sdr, &config, Unstoppable)?;
let gainmap_jpeg = my_encoder.encode_grayscale(&gainmap.data)?;

// 3. Assemble Ultra HDR file
let ultrahdr = encode_ultrahdr(&sdr_jpeg, &gainmap_jpeg, &metadata, ColorGamut::Bt709)?;

// 4. Decode: get raw JPEG bytes and decode with your codec
let decoder = Decoder::new(&ultrahdr)?;
let sdr_jpeg = decoder.primary_jpeg().unwrap();
let gainmap_jpeg = decoder.gainmap_jpeg().unwrap();
let metadata = decoder.metadata().unwrap();

§Standards

This implementation follows:

Modules§

color
Color space handling: transfer functions, gamut matrices, conversions.
container
JPEG container utilities for codec-agnostic Ultra HDR support.
gainmap
Gain map computation and application.
jpeg
JPEG handling utilities.
limits
Safety limits for parsing and allocation.
luminance
Reference display luminance values (in nits).
metadata
Metadata handling for Ultra HDR and multi-image JPEG formats.

Structs§

Decoder
Ultra HDR decoder.
Encoder
Ultra HDR encoder.
Fraction
A fraction for ISO 21496-1 metadata encoding.
GainMap
A gain map image (8-bit grayscale or per-channel).
GainMapConfig
Configuration for gain map computation.
GainMapMetadata
ISO 21496-1 gain map metadata.
RawImage
A raw (uncompressed) image.
Unstoppable
A Stop implementation that never stops (no cooperative cancellation).

Enums§

ColorGamut
Color gamut / color space primaries.
ColorTransfer
Electro-optical transfer function (EOTF/OETF).
Error
Errors that can occur during Ultra HDR operations.
GainMapEncodingFormat
Controls which metadata format(s) to embed in Ultra HDR output.
HdrOutputFormat
Output format for HDR reconstruction.
PixelFormat
Pixel format for raw images.
StopReason
Why an operation was stopped.

Traits§

Stop
Cooperative cancellation check.

Functions§

encode_ultrahdr
Assemble an Ultra HDR JPEG from pre-encoded components.
encode_ultrahdr_with_format
Assemble an Ultra HDR JPEG from pre-encoded components with format control.

Type Aliases§

Result
Result type for Ultra HDR operations.