Crate ultrahdr_core

Expand description

Core gain map math for Ultra HDR.

This crate provides the pure computational components for Ultra HDR:

Pixel math for applying/computing gain maps
Tone mapping (HDR → SDR)
Color space conversions and transfer functions

JPEG-container metadata (MPF, XMP, ISO 21496-1 APP2 envelope) previously lived here in ultrahdr_core::metadata; it has moved to zenjpeg::container (JPEG-specific parsing) and zencodec::gainmap (codec-agnostic payload). See issue #8.

This crate has no JPEG codec dependency. For full Ultra HDR encode/decode, use the ultrahdr crate which provides codec integration.

§no_std Support

This crate is no_std compatible with alloc. Disable default features:

ultrahdr-core = { version = "0.1", default-features = false }

§Cooperative Cancellation

Long-running operations accept an impl Stop parameter from the enough crate for cooperative cancellation. Use Unstoppable when cancellation is not needed.

§Example — compute a gain map from an HDR/SDR pair

use ultrahdr_core::{
    ColorPrimaries, TransferFunction, PixelFormat, new_pixel_buffer, Unstoppable,
    gainmap::{apply_gainmap, compute_gainmap, GainMapConfig, HdrOutputFormat},
};

// Minimal 8x8 matching HDR + SDR surfaces. In practice these come from
// your image decoder — this example just shows the call shape.
let hdr = new_pixel_buffer(
    8, 8, PixelFormat::Rgba8, ColorPrimaries::Bt709, TransferFunction::Srgb,
)?;
let sdr = new_pixel_buffer(
    8, 8, PixelFormat::Rgba8, ColorPrimaries::Bt709, TransferFunction::Srgb,
)?;

// Derive gain map + metadata.
let config = GainMapConfig::default();
let (gainmap, metadata) = compute_gainmap(&hdr, &sdr, &config, Unstoppable)?;

// For XMP / ISO 21496-1 APP2 serialization, use `zenjpeg::container::xmp`
// and `zencodec::gainmap`.

// Reconstruct HDR at 4× boost.
let _hdr_out = apply_gainmap(
    &sdr, &gainmap, &metadata,
    4.0, HdrOutputFormat::LinearFloat, Unstoppable,
)?;

Re-exports§

pub use gainmap::apply::HdrOutputFormat;
pub use gainmap::compute::GainMapConfig;
pub use gainmap::compute::compute_gain_row;

Modules§

color: Color space handling: transfer functions, gamut matrices, HDR→SDR tone mapping.
gainmap: Gain map computation and application.
limits: Safety limits for parsing and allocation.
luminance: Reference display luminance values (in nits).

Structs§

Bt2408Yrgb: Newtype guaranteeing a Bt2408Tonemapper is in Yrgb (luma) mode.
ExtendedReinhardLuma: Wraps a ToneMapCurve::ExtendedReinhard for use as a luma curve.
GainMap: A gain map image (8-bit grayscale or per-channel).
GainMapChannel: Per-channel gain map parameters.
GainMapParams: ISO 21496-1 gain map parameters. Canonical cross-codec representation.
HableFilmic: John Hable’s filmic curve from GDC 2010 (“Uncharted 2”). Identical math to libultrahdr’s reference implementation and the original GDC 2010 paper.
LumaFn: Adapt a closure as a LumaToneMap. Caller is responsible for monotonicity and [0, 1] output range.
LumaGainMapSplitter: Splits HDR rows into (SDR, log2-gain) pairs around a LumaToneMap.
PixelBuffer: Owning pixel container. Re-exported from zenpixels::PixelBuffer.
PixelSlice: Borrowed pixel view. Re-exported from zenpixels::PixelSlice. Borrowed view of pixel data.
PixelSliceMut: Mutably borrowed pixel view. Re-exported from zenpixels::PixelSliceMut. Mutable borrowed view of pixel data.
SplitConfig: Splitter configuration.
SplitStats: Per-row statistics. Accumulate across rows; pass into GainMapParams metadata or use to tighten min_log2/max_log2 on a second pass.
Unstoppable: A Stop implementation that never stops (no cooperative cancellation).

Enums§

ColorPrimaries: Color primaries. Re-exported from zenpixels::ColorPrimaries. Color primaries (CIE xy chromaticities of R, G, B) and white point.
Error: Errors that can occur during Ultra HDR operations.
GainMapEncodingFormat: Controls which metadata format(s) to embed in Ultra HDR output.
Iso21496Format: Wire format variant for ISO 21496-1 gain map metadata serialization.
PixelFormat: Pixel format for raw images. Re-exported from zenpixels::PixelFormat.
StopReason: Why an operation was stopped.
TransferFunction: Electro-optical transfer function. Re-exported from zenpixels::TransferFunction. Encoding transfer function (OETF).

Traits§

LumaToneMap: A scalar luma tone curve: Y_HDR (linear, ≥0) → Y_SDR (linear).
Stop: Cooperative cancellation check.

Functions§

clone_pixel_buffer: Deep-copy a PixelBuffer. zenpixels::PixelBuffer intentionally does not implement Clone to discourage silent large-pixel copies; this helper gives ultrahdr-core callers a single owned duplicate (tightly packed, same descriptor) when they genuinely need one.
descriptor_for: Build a zenpixels::PixelDescriptor with the given format, primaries, and transfer function. Convenience for the common pattern used by ultrahdr-core’s tests and examples.
new_pixel_buffer: Allocate a PixelBuffer for ultrahdr-core’s kernels.
parse_iso21496_fmt: Parse ISO 21496-1 binary gain map metadata with explicit format selection.
pixel_buffer_from_vec: Wrap an existing Vec<u8> as a PixelBuffer, validating ultrahdr-core’s dimension caps and format subset.
require_supported_format: Reject pixel formats the kernels don’t understand.
serialize_iso21496_fmt: Serialize GainMapParams to ISO 21496-1 binary format with explicit format selection.
validate_gainmap_metadata: Validate gain map metadata with ultrahdr-core’s stricter checks.
validate_ultrahdr_dimensions: Validate image dimensions against ultrahdr-core’s stricter caps.
validate_ultrahdr_image: Validate a PixelBuffer against ultrahdr-core’s dimension caps and the kernels’ format subset. Used at public entry points.
validate_ultrahdr_slice: Validate a PixelSlice against ultrahdr-core’s dimension caps and the kernels’ format subset.

Type Aliases§

Fraction: Signed fraction for ISO 21496-1 metadata encoding.
GainMapMetadata: ISO 21496-1 gain map metadata.
Result: Result type for Ultra HDR operations.
UnsignedFraction: Unsigned fraction for ISO 21496-1 metadata encoding.