Files
craft-libs/crates/image-codecs/src/cicp.rs
T
FredApps 59b4f1e8c2 image-codecs: decode AVIF pixels with the pure-Rust AV1 decoder (#778) (#1601)
* image-codecs: decode AVIF pixels with craft-video's pure-Rust AV1 decoder

New optional `avif-decode` feature (native targets) reads still AVIF
files: the HEIF/ISOBMFF item graph, grids, clap/irot/imir, alpha
auxiliary images (including premultiplied), 8/10/12-bit 4:0:0, 4:2:0,
4:2:2 and 4:4:4, nclx/ICC colour, Exif and XMP, and PQ/HLG to linear
F32 through cicp::linearize as the HEIF path does.

The container walk follows LightCraft #3017 by @emmertex. Every size is
checked against the caller's Limits before the AV1 decoder runs, the
decoder's memory budget is capped by max_alloc, and the decode is
wrapped in catch_unwind so a decoder panic becomes an error.

Fixtures are tiny ffmpeg/libaom files; the 4:2:0 planes match libdav1d
bit for bit. Adds a decode_avif fuzz target.

Part of storytold/craft-libs#778.

* image-codecs, video: address review on the AVIF decoder

- clap: width and height are unsigned fractions, the offsets have signed
  numerators, so 0x80000000/0x40000000 is a width of 2, not -2.
- An item with clap, irot or imir more than once (repeated ipma records)
  is refused before any canvas work, instead of rotating 261120 times.
- Matrix coefficients 10 (BT.2020 constant luminance) is refused rather
  than converted with the non-constant-luminance equations.
- An alpha plane whose own transforms differ from the colour's is refused
  rather than composed in the wrong place; none, or the colour's, still
  decode.
- craft-video: Decoder::set_shown_budget lowers the per-chunk byte cap on
  shown pictures (never above 1 GiB), and the AVIF decoder sets it to
  max_alloc, so a payload of many shown pictures is refused before they
  are built.
2026-11-15 23:25:25 +01:00

218 lines
9.3 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! ITU-T H.273 colour descriptions (CICP: coding-independent code points), as HEIF `colr`
//! `nclx` boxes and video streams declare them, and the HDR transfer functions of ITU-R BT.2100.
//!
//! PQ and HLG can't be written as an ICC tone curve, so an image using them is decoded here to
//! linear light (32-bit float) instead: diffuse white (BT.2408's 203 cd/m²) becomes 1.0 and the
//! highlights above it are kept as values over 1.0, as Photoshop holds HDR in a 32-bit document.
//! The caller tags the result with a linear profile on the declared primaries.
use crate::error::CodecError;
use crate::image::{Image, SampleType};
/// A colour description: the four H.273 code points as written in the file.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Cicp {
/// Colour primaries: 1 BT.709, 9 BT.2020, 12 P3-D65…
pub primaries: u16,
/// Transfer characteristics: 13 sRGB, 1/6/14/15 BT.709, 8 linear, 16 PQ, 18 HLG…
pub transfer: u16,
/// Matrix coefficients.
pub matrix: u16,
/// Full-range samples rather than studio swing.
pub full_range: bool,
}
impl Cicp {
/// SMPTE ST 2084 / BT.2100 perceptual quantizer.
pub const TRANSFER_PQ: u16 = 16;
/// ARIB STD-B67 / BT.2100 hybrid log-gamma.
pub const TRANSFER_HLG: u16 = 18;
/// Linear light.
pub const TRANSFER_LINEAR: u16 = 8;
/// PQ or HLG: samples that [`linearize`] decodes to linear light.
pub fn is_hdr(self) -> bool {
matches!(self.transfer, Cicp::TRANSFER_PQ | Cicp::TRANSFER_HLG)
}
}
/// The luminance that becomes 1.0: BT.2408's HDR reference (diffuse) white.
pub const REFERENCE_WHITE_NITS: f32 = 203.0;
/// The nominal display peak HLG is rendered for (BT.2100's reference display).
pub const HLG_PEAK_NITS: f32 = 1000.0;
/// PQ's absolute peak.
pub const PQ_PEAK_NITS: f32 = 10_000.0;
/// HDR content light levels in the units used by PNG `cLLI` (0.0001 cd/m² per unit).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ContentLightLevel {
/// Maximum content light level in 0.0001 cd/m² units.
pub max_content_light_level: u32,
/// Maximum frame-average light level in 0.0001 cd/m² units.
pub max_frame_average_light_level: u32,
}
/// BT.2100 HLG inverse OETF: non-linear signal `E'` (0..1) to normalised scene light `E` (0..1).
pub fn hlg_inverse_oetf(e: f32) -> f32 {
const A: f32 = 0.178_832_77;
const B: f32 = 1.0 - 4.0 * A;
const C: f32 = 0.559_910_7;
let e = if e.is_finite() { e.clamp(0.0, 1.0) } else { 0.0 };
if e <= 0.5 { e * e / 3.0 } else { (((e - C) / A).exp() + B) / 12.0 }
}
/// BT.2100 HLG signal to display light relative to [`REFERENCE_WHITE_NITS`]: the inverse OETF,
/// then the OOTF for a [`HLG_PEAK_NITS`] display (system gamma 1.2, zero black level), whose
/// luminance uses the weights of the `luma` primaries.
pub fn hlg_to_linear(rgb: [f32; 3], luma: [f32; 3]) -> [f32; 3] {
let s = rgb.map(hlg_inverse_oetf);
let ys = luma[0] * s[0] + luma[1] * s[1] + luma[2] * s[2];
// γ = 1.2 + 0.42·log10(Lw / 1000) is exactly 1.2 at 1000 cd/m².
let gain = if ys > 0.0 { HLG_PEAK_NITS * ys.powf(0.2) / REFERENCE_WHITE_NITS } else { 0.0 };
s.map(|v| v * gain)
}
/// SMPTE ST 2084 (PQ) signal `E'` (0..1) to display light relative to [`REFERENCE_WHITE_NITS`].
pub fn pq_to_linear(e: f32) -> f32 {
const M1: f32 = 2610.0 / 16384.0;
const M2: f32 = 2523.0 / 4096.0 * 128.0;
const C1: f32 = 3424.0 / 4096.0;
const C2: f32 = 2413.0 / 4096.0 * 32.0;
const C3: f32 = 2392.0 / 4096.0 * 32.0;
let e = if e.is_finite() { e.clamp(0.0, 1.0) } else { 0.0 };
let p = e.powf(1.0 / M2);
let y = ((p - C1).max(0.0) / (C2 - C3 * p)).powf(1.0 / M1);
y * PQ_PEAK_NITS / REFERENCE_WHITE_NITS
}
/// BT.2100 PQ signal for linear light relative to [`REFERENCE_WHITE_NITS`].
pub fn linear_to_pq(linear: f32) -> f32 {
const M1: f32 = 2610.0 / 16384.0;
const M2: f32 = 2523.0 / 4096.0 * 128.0;
const C1: f32 = 3424.0 / 4096.0;
const C2: f32 = 2413.0 / 4096.0 * 32.0;
const C3: f32 = 2392.0 / 4096.0 * 32.0;
let nits = if linear.is_finite() { linear.max(0.0) * REFERENCE_WHITE_NITS } else { 0.0 };
let y = (nits / PQ_PEAK_NITS).clamp(0.0, 1.0).powf(M1);
((C1 + C2 * y) / (1.0 + C3 * y)).powf(M2)
}
/// Relative luminance weights of the RGB primaries `code` (BT.2020's for anything else, the
/// space BT.2100 defines HLG in).
pub(crate) fn luma_weights(code: u16) -> [f32; 3] {
match code {
1 => [0.2126, 0.7152, 0.0722],
12 => [0.2290, 0.6917, 0.0793],
_ => [0.2627, 0.6780, 0.0593],
}
}
/// `img` (RGB or RGBA, decoded with `cicp`'s PQ or HLG transfer) as linear light in 32-bit float,
/// alpha unchanged. Its ICC profile is dropped: whatever it said described the encoded samples,
/// not linear light. Anything else comes back unchanged.
pub fn linearize(img: Image, cicp: Cicp) -> Result<Image, CodecError> {
let layout = img.layout();
if !cicp.is_hdr() || !layout.is_rgb() {
return Ok(img);
}
let (w, h) = img.dimensions();
let ch = layout.channels();
let mut v = img.to_normalized();
let luma = luma_weights(cicp.primaries);
for px in v.chunks_exact_mut(ch) {
let [r, g, b, ..] = *px else { continue };
let out = if cicp.transfer == Cicp::TRANSFER_HLG { hlg_to_linear([r, g, b], luma) } else { [r, g, b].map(pq_to_linear) };
px[..3].copy_from_slice(&out);
}
let mut out = Image::from_raw(w, h, layout, SampleType::F32, v.iter().flat_map(|x| x.to_ne_bytes()).collect())?;
out.meta = img.meta;
out.warnings = img.warnings;
// CICP describes the samples, not their source encoding. These samples are now linear.
out.cicp = Some(Cicp { transfer: Cicp::TRANSFER_LINEAR, matrix: 0, full_range: true, ..cicp });
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::image::ChannelLayout;
const BT2020: [f32; 3] = [0.2627, 0.6780, 0.0593];
fn close(a: f32, b: f32, tol: f32) -> bool {
(a - b).abs() <= tol
}
#[test]
fn hlg_inverse_oetf_matches_bt2100() {
assert_eq!(hlg_inverse_oetf(0.0), 0.0);
// The two segments meet at E' = 0.5, E = 1/12.
assert!(close(hlg_inverse_oetf(0.5), 1.0 / 12.0, 1e-6));
assert!(close(hlg_inverse_oetf(0.500_001), 1.0 / 12.0, 1e-5));
assert!(close(hlg_inverse_oetf(1.0), 1.0, 1e-4));
// BT.2408's HLG reference white, 75 % signal, is E ≈ 0.265.
assert!(close(hlg_inverse_oetf(0.75), 0.2650, 1e-3));
for bad in [f32::NAN, f32::INFINITY, -1.0] {
assert!(hlg_inverse_oetf(bad).is_finite());
}
}
#[test]
fn hlg_reference_white_is_one_and_highlights_are_kept() {
// BT.2408: a 75 % HLG grey on a 1000 cd/m² display is 203 cd/m², our 1.0.
let white = hlg_to_linear([0.75; 3], BT2020);
assert!(white.iter().all(|&v| close(v, 1.0, 0.005)), "{white:?}");
// Peak signal is the display peak: 1000 / 203.
let peak = hlg_to_linear([1.0; 3], BT2020);
assert!(peak.iter().all(|&v| close(v, 1000.0 / 203.0, 0.01)), "{peak:?}");
// 50 % grey: 1000 · (1/12)^1.2 ≈ 50.7 cd/m².
let mid = hlg_to_linear([0.5; 3], BT2020);
assert!(mid.iter().all(|&v| close(v * 203.0, 50.71, 0.1)), "{mid:?}");
assert_eq!(hlg_to_linear([0.0; 3], BT2020), [0.0; 3]);
// A saturated colour keeps its hue: only red lit stays only red.
let red = hlg_to_linear([0.75, 0.0, 0.0], BT2020);
assert!(red[0] > 0.0 && red[1] == 0.0 && red[2] == 0.0, "{red:?}");
}
#[test]
fn pq_matches_st2084() {
assert_eq!(pq_to_linear(0.0), 0.0);
assert!(close(pq_to_linear(1.0), 10_000.0 / 203.0, 0.05));
// 203 cd/m² is PQ signal ≈ 0.5807 (BT.2408).
assert!(close(pq_to_linear(0.5807), 1.0, 0.005), "{}", pq_to_linear(0.5807));
assert!(close(linear_to_pq(1.0), 0.5807, 0.0001));
assert!(close(pq_to_linear(linear_to_pq(4.0)), 4.0, 0.001));
assert!(pq_to_linear(f32::NAN).is_finite());
assert!(linear_to_pq(f32::NAN).is_finite());
}
#[test]
fn linearize_decodes_hlg_to_float_and_keeps_alpha() {
let hlg = Cicp { primaries: 9, transfer: Cicp::TRANSFER_HLG, matrix: 9, full_range: true };
let three_quarters = (0.75f32 * 65535.0).round() as u16;
let img = Image::from_u16(2, 1, ChannelLayout::Rgba, &[three_quarters, three_quarters, three_quarters, 65535, 0, 0, 0, 32768])
.unwrap()
.with_icc(Some(b"encoded-profile".to_vec()));
let out = linearize(img, hlg).unwrap();
assert_eq!(
(out.sample_type(), out.layout(), out.icc.as_deref(), out.cicp),
(
SampleType::F32,
ChannelLayout::Rgba,
None,
Some(Cicp { primaries: hlg.primaries, transfer: Cicp::TRANSFER_LINEAR, matrix: 0, full_range: true })
)
);
let v = out.to_normalized();
assert!(v[..3].iter().all(|&x| close(x, 1.0, 0.005)), "{v:?}");
assert!(close(v[3], 1.0, 1e-6) && v[4..7] == [0.0; 3] && close(v[7], 0.5, 1e-3), "{v:?}");
}
#[test]
fn linearize_leaves_sdr_untouched() {
let srgb = Cicp { primaries: 1, transfer: 13, matrix: 6, full_range: false };
let img = Image::from_u16(1, 1, ChannelLayout::Rgb, &[1, 2, 3]).unwrap();
assert_eq!(linearize(img.clone(), srgb).unwrap(), img);
}
}