LR-HDR-EXPORT: HDR PNG export as 16-bit Rec. 2020 PQ (cICP, cLLI)

With HDR output on, a photo edited in HDR exports as a 16-bit PNG with the PQ
curve in Rec. 2020 (SDR white at HDR_REFERENCE_WHITE_NITS), described by a
`cICP` chunk (PNG third edition: BT.2020 primaries, PQ, RGB, full range) and
a `cLLI` content light level chunk (the levels the HDR AVIF records). EXIF,
XMP and print resolution are kept; no ICC profile next to cICP. Photos without
an HDR edit, and HDR edits with HDR output off, export as before.

`codecs::encode_png_pq` sits next to `encode_avif_pq` and takes the same
input. Follow-up to #646, ported from #466.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

crates/codecs/src/encode.rs

@@ -498,6 +498,59 @@ pub fn encode_avif_pq(width: u32, height: u32, rgb: &[f32], quality: u8, speed:
     }
 }
 
+/// Encode an HDR PNG: `rgb` is linear light in **Rec. 2020** primaries with SDR white at 1.0
+/// (`width × height × 3`), as for [`encode_avif_pq`]. Written as 16-bit RGB with the PQ curve
+/// (SDR white at [`HDR_REFERENCE_WHITE_NITS`]), described by a `cICP` chunk (PNG third edition:
+/// BT.2020 primaries, PQ, RGB, full range) and a `cLLI` content light level chunk (the same
+/// levels the HDR AVIF records). EXIF and XMP are embedded; an ICC profile is not (`cICP`
+/// describes the colour, and readers prefer it).
+pub fn encode_png_pq(width: u32, height: u32, rgb: &[f32], meta: &EncodeMeta) -> Result<Vec<u8>> {
+    let (w, h) = (width as usize, height as usize);
+    let n = w.checked_mul(h).ok_or_else(|| Error::Encode("image too large".into()))?;
+    if n == 0 || n.checked_mul(3).is_none_or(|need| rgb.len() < need) {
+        return Err(Error::Encode("HDR PNG: sample buffer too short".into()));
+    }
+    const K: [f32; 3] = [0.2627, 0.6780, 0.0593]; // BT.2020 luminance
+    let mut max_nits = 0f32;
+    let mut sum_nits = 0f64;
+    let mut bytes = Vec::with_capacity(n * 6);
+    for c in rgb.as_chunks::<3>().0.iter().take(n) {
+        let nits = c.map(|v| (if v.is_finite() { v.max(0.0) } else { 0.0 }) * HDR_REFERENCE_WHITE_NITS);
+        max_nits = max_nits.max(nits[0].max(nits[1]).max(nits[2]));
+        sum_nits += (K[0] * nits[0] + K[1] * nits[1] + K[2] * nits[2]) as f64;
+        for v in nits {
+            bytes.extend_from_slice(&((pq_encode(v) * 65535.0).round().clamp(0.0, 65535.0) as u16).to_be_bytes());
+        }
+    }
+    let cll = (max_nits.ceil().clamp(1.0, 10_000.0) as u32, ((sum_nits / n as f64).ceil().clamp(1.0, 10_000.0)) as u32);
+    let mut info = png::Info::with_size(width, height);
+    info.color_type = png::ColorType::Rgb;
+    info.bit_depth = png::BitDepth::Sixteen;
+    info.exif_metadata = meta.exif.map(|b| b.to_vec().into());
+    info.pixel_dims = meta.ppi.filter(|p| *p > 0).map(|p| {
+        let ppm = (p as f64 / 0.0254).round() as u32;
+        png::PixelDimensions { xppu: ppm, yppu: ppm, unit: png::Unit::Meter }
+    });
+    let mut out = Vec::new();
+    let e = |e: png::EncodingError| Error::Encode(e.to_string());
+    {
+        let mut enc = png::Encoder::with_info(&mut out, info).map_err(e)?;
+        enc.set_compression(png::Compression::Fast);
+        if let Some(xmp) = meta.xmp {
+            enc.add_itxt_chunk("XML:com.adobe.xmp".into(), xmp.into()).map_err(e)?;
+        }
+        let mut wr = enc.write_header().map_err(e)?;
+        // BT.2020 primaries (9), PQ (16), RGB (0), full range (1)
+        wr.write_chunk(png::chunk::ChunkType(*b"cICP"), &[9, 16, 0, 1]).map_err(e)?;
+        // MaxCLL and MaxFALL in units of 0.0001 cd/m²
+        let clli = [(cll.0 * 10_000).to_be_bytes(), (cll.1 * 10_000).to_be_bytes()].concat();
+        wr.write_chunk(png::chunk::ChunkType(*b"cLLI"), &clli).map_err(e)?;
+        wr.write_image_data(&bytes).map_err(e)?;
+        wr.finish().map_err(e)?;
+    }
+    Ok(out)
+}
+
 /// 16-bit RGB(A) → 10-bit BT.601 full-range YCbCr planes (the matrix `ravif` uses for 8-bit input).
 #[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
 fn avif_10bit(enc: &ravif::Encoder, img: &EncodeImage, s: &[u16]) -> Result<Vec<u8>> {

crates/codecs/src/lib.rs

@@ -37,7 +37,7 @@ mod webp;
 
 pub use encode::{
     ChromaSubsampling, EncodeImage, EncodeMeta, HDR_REFERENCE_WHITE_NITS, Samples, TiffCompression, encode_avif, encode_avif_pq, encode_jpeg,
-    encode_png, encode_tiff, encode_webp_lossless,
+    encode_png, encode_png_pq, encode_tiff, encode_webp_lossless,
 };
 pub use sniff::{Format, sniff};
 pub use space::{NamedSpace, SourceSpace, SpaceOrigin, Trc};

crates/codecs/tests/roundtrip.rs

@@ -635,3 +635,49 @@ fn print_resolution_is_written() {
     let j = encode_jpeg(&img, 90, ChromaSubsampling::S444, &EncodeMeta::default()).unwrap();
     assert_eq!(&j[13..18], &[0, 0, 1, 0, 1]);
 }
+
+#[test]
+fn pq_png_is_16_bit_rec2020_pq_with_cicp_and_content_light() {
+    // linear Rec. 2020, SDR white at 1.0, up to 8x SDR white along x
+    let (w, h) = (64u32, 4u32);
+    let rgb: Vec<f32> = (0..w * h)
+        .flat_map(|i| {
+            let v = 0.01 * 1.11f32.powi((i % w) as i32);
+            [v, v * 0.5, v * 0.25]
+        })
+        .collect();
+    let xmp = r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"/>"#;
+    let bytes = encode_png_pq(w, h, &rgb, &EncodeMeta { xmp: Some(xmp), ppi: Some(240), ..Default::default() }).unwrap();
+    let mut r = png::Decoder::new(std::io::Cursor::new(bytes.as_slice())).read_info().unwrap();
+    let cicp = r.info().coding_independent_code_points.expect("cICP");
+    assert_eq!((cicp.color_primaries, cicp.transfer_function), (9, 16), "BT.2020, PQ");
+    let mut buf = vec![0; r.output_buffer_size().unwrap()];
+    let f = r.next_frame(&mut buf).unwrap();
+    assert_eq!((f.bit_depth, f.color_type, f.width, f.height), (png::BitDepth::Sixteen, png::ColorType::Rgb, w, h));
+    // every sample decodes back to its luminance
+    for x in [0usize, 20, 63] {
+        for c in 0..3 {
+            let o = (x * 3 + c) * 2;
+            let e = u16::from_be_bytes([buf[o], buf[o + 1]]) as f32 / 65535.0;
+            let want = rgb[x * 3 + c] * HDR_REFERENCE_WHITE_NITS;
+            assert!((encode::pq_decode(e) - want).abs() <= want * 0.01 + 0.01, "x {x} c {c}: {} vs {want}", encode::pq_decode(e));
+        }
+    }
+    // cLLI: MaxCLL is the brightest channel, in 0.0001 cd/m²
+    let at = bytes.windows(4).position(|w| w == b"cLLI").expect("cLLI");
+    let max_cll = u32::from_be_bytes(bytes[at + 4..at + 8].try_into().unwrap()) as f32 / 10_000.0;
+    let brightest = rgb.iter().copied().fold(0.0f32, f32::max) * HDR_REFERENCE_WHITE_NITS;
+    assert!((max_cll - brightest.ceil()).abs() <= 1.0, "{max_cll} vs {brightest}");
+    assert!(bytes.windows(17).any(|w| w == b"XML:com.adobe.xmp"), "XMP kept");
+    assert!(bytes.windows(4).any(|w| w == b"pHYs"), "print resolution kept");
+    assert!(!bytes.windows(4).any(|w| w == b"iCCP"), "no ICC profile next to cICP");
+}
+
+#[test]
+fn pq_png_rejects_short_buffers_and_survives_hostile_samples() {
+    assert!(encode_png_pq(4, 4, &[1.0; 3], &EncodeMeta::default()).is_err());
+    assert!(encode_png_pq(0, 4, &[], &EncodeMeta::default()).is_err());
+    assert!(encode_png_pq(u32::MAX, u32::MAX, &[], &EncodeMeta::default()).is_err());
+    let hostile = [f32::NAN, f32::INFINITY, -5.0, 1e30, 0.5, 2.0];
+    assert!(encode_png_pq(2, 1, &hostile, &EncodeMeta::default()).is_ok());
+}