ultrahdr_rs/lib.rs
1//! Ultra HDR - Pure Rust encoder/decoder for HDR images with gain maps.
2//!
3//! Ultra HDR is an image format that stores HDR (High Dynamic Range) content
4//! in a backwards-compatible JPEG file. Legacy viewers see the SDR (Standard
5//! Dynamic Range) base image, while HDR-capable displays can reconstruct the
6//! full HDR content using an embedded gain map.
7//!
8//! # Crate Structure
9//!
10//! - [`ultrahdr_core`] - Core gain map math and metadata (no codec dependency)
11//! - `ultrahdr` (this crate) - Full encoder/decoder with jpegli integration
12//!
13//! # Format Overview
14//!
15//! An Ultra HDR JPEG contains:
16//! - Primary JPEG: SDR base image (8-bit, sRGB)
17//! - Gain map JPEG: Compressed ratio of HDR/SDR luminance
18//! - XMP metadata: Describes how to apply the gain map
19//! - MPF header: Multi-Picture Format container
20//!
21//! # Example
22//!
23//! ```ignore
24//! use ultrahdr::{Encoder, Decoder, RawImage, PixelFormat, ColorTransfer};
25//!
26//! // Encoding HDR to Ultra HDR JPEG
27//! let hdr_image = RawImage::from_data(
28//! 1920, 1080,
29//! PixelFormat::Rgba16F,
30//! ColorGamut::Bt2100,
31//! ColorTransfer::Pq,
32//! hdr_pixels,
33//! )?;
34//!
35//! let ultrahdr_jpeg = Encoder::new()
36//! .set_hdr_image(hdr_image)
37//! .set_quality(90, 85)
38//! .encode()?;
39//!
40//! // Decoding Ultra HDR JPEG
41//! let decoder = Decoder::new(&ultrahdr_jpeg)?;
42//! let hdr_output = decoder.decode_hdr(4.0)?; // 4x SDR brightness
43//! ```
44//!
45//! # Standards
46//!
47//! This implementation follows:
48//! - [Ultra HDR Image Format v1.1](https://developer.android.com/media/platform/hdr-image-format)
49//! - ISO 21496-1 (gain map metadata)
50//! - Adobe XMP (hdrgm namespace)
51
52#![warn(missing_docs)]
53#![warn(clippy::all)]
54
55// Re-export everything from ultrahdr-core
56pub use ultrahdr_core::color;
57pub use ultrahdr_core::gainmap;
58pub use ultrahdr_core::metadata;
59
60// Re-export core types at crate root
61pub use ultrahdr_core::{
62 limits, luminance, ColorGamut, ColorTransfer, Error, Fraction, GainMap, GainMapConfig,
63 GainMapMetadata, HdrOutputFormat, PixelFormat, RawImage, Result, Stop, StopReason, Unstoppable,
64};
65
66// This crate's additional modules
67pub mod container;
68pub mod jpeg;
69
70mod decode;
71mod encode;
72
73// Re-export encoder/decoder
74pub use decode::Decoder;
75pub use encode::Encoder;