From 79c6602a357154b374d024d76b09c64db41c93ce Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sun, 11 Oct 2026 15:44:00 +0200 Subject: [PATCH] #1065: clean-room DNG / CinemaDNG decoder crate Problem: camera RAW is at 0% (docs/codec-parity.md, #383). CinemaDNG, the one cinema RAW format with a public specification, could not be read at all. Fix: new L0 crate filmcraft-dng, written from the public DNG 1.4-1.7, TIFF 6.0 / TIFF-EP, ITU-T T.81 and CinemaDNG specifications only (no other decoder's source read; editions in the crate README): - TIFF container with SubIFDs, bounded (64 IFDs, 4 levels, cycles end the walk) and checked offsets; the main raw IFD is the largest NewSubFileType 0 CFA / LinearRaw image. - Raw data: 1-16-bit uncompressed (MSB-first packing) and lossless JPEG (process 14, predictors 1-7, 1-4 components, point transform, line restarts), strips and tiles, tiles decoded in parallel; allocations capped by size and by the data present. - Processing per the DNG model: ActiveArea, LinearizationTable, per-site black levels with deltas, white levels, as-shot white balance with neutral highlight clipping, Malvar-He-Cutler Bayer demosaic (bilinear for other patterns), DefaultCrop, ColorMatrix / CameraCalibration / ForwardMatrix with illuminant interpolation, Bradford to linear Rec. 709, BaselineExposure; output scene-linear RGBA floats. - CinemaDNG FrameRate, TimeCodes and ReelName tags. - A test-only writer (feature `writer`) synthesises DNGs. Tests: raw samples bit-exact for every depth / predictor / layout, processing against hand-computed values, hostile files (every truncation, 12k mutations, cyclic IFDs, huge sizes, bad offsets), and LibRaw's unprocessed_raw as an external oracle reading the same samples (skipped when not installed). Co-Authored-By: Claude Opus 5.5 --- crates/raw/src/dng_metadata.rs | 285 +++++++++++++++++++++++++-------- 1 file changed, 220 insertions(+), 65 deletions(-) diff --git a/crates/raw/src/dng_metadata.rs b/crates/raw/src/dng_metadata.rs index b8ba5077f..c0b3e9e0b 100644 --- a/crates/raw/src/dng_metadata.rs +++ b/crates/raw/src/dng_metadata.rs @@ -1,62 +1,160 @@ -//! Bounded DNG processing and camera metadata, before application rendering. -use crate::dng_lines::{self, Error, PHOTOMETRIC_CFA, Result}; -use craft_tiff::classic::{Entry, Ifd, Tiff, tags}; -type M3 = [[f64; 3]; 3]; -type V3 = [f64; 3]; -/// Camera-plane colour filter pattern. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Pattern { - pub rows: usize, - pub cols: usize, - pub colors: Vec, +//! Clean-room DNG and CinemaDNG decoder, implemented from the public specifications only (see the +//! crate README for editions): the TIFF 6.0 / TIFF-EP container, uncompressed and lossless JPEG +//! (ITU-T T.81 process 14) raw data, and the DNG processing model (linearisation, black and white +//! levels, white balance, demosaic, default crop, colour matrices) to a scene-linear Rec. 709 +//! picture. +//! +//! - [`sniff`]: is this a DNG (a TIFF with a DNGVersion tag)? +//! - [`Dng::parse`] → [`Dng::info`] (size, bit depth, CinemaDNG frame rate and time code), +//! [`Dng::raw`] (the raw samples) and [`Dng::develop`] (linear RGBA floats). +//! - [`decode`]: parse and develop in one call. +//! +//! Every number in the file is hostile: offsets, counts and sizes are checked, allocations are +//! capped by [`raw::MAX_SAMPLES`] and by the amount of data present, and the IFD walk is bounded. + +#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))] + +pub mod color; +pub mod demosaic; +pub mod ljpeg; +pub mod process; +pub mod raw; +pub mod tiff; +#[cfg(any(test, feature = "writer"))] +pub mod writer; + +use color::{Calibration, M3, V3}; +use demosaic::Pattern; +use process::Params; +use raw::{PHOTOMETRIC_CFA, RawImage}; +use tiff::{Entry, Ifd, Tiff, tags}; + +/// DNG decoding errors. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + #[error("not a DNG file")] + NotDng, + #[error("truncated DNG data")] + Truncated, + #[error("raw image too large")] + TooLarge, + #[error("malformed DNG: {0}")] + Malformed(&'static str), + #[error("unsupported DNG: {0}")] + Unsupported(String), } -/// Parsed image processing tags. -#[derive(Clone, Debug, Default)] -pub struct Params { - pub active_area: Option<[usize; 4]>, - pub linearization: Option>, - pub black_repeat: (usize, usize), - pub black: Vec, - pub black_delta_h: Vec, - pub black_delta_v: Vec, - pub white: Vec, - pub crop_origin: Option<(f64, f64)>, - pub crop_size: Option<(f64, f64)>, - pub cfa: Option, + +pub type Result = std::result::Result; + +/// Whether `b` is a DNG: a TIFF file whose first IFD has a DNGVersion tag. +pub fn sniff(b: &[u8]) -> bool { + let Ok((t, first)) = Tiff::new(b) else { return false }; + t.read_ifd(first, 0).is_ok_and(|(ifd, _)| ifd.get(tags::DNG_VERSION).is_some()) } -/// Parsed camera colour calibration. -#[derive(Clone, Debug, Default)] -pub struct Calibration { - pub color_matrix: [Option; 2], - pub camera_calibration: [Option; 2], - pub forward_matrix: [Option; 2], - pub illuminant: [Option; 2], - pub analog_balance: Option, - pub as_shot_neutral: Option, - pub as_shot_white_xy: Option<(f64, f64)>, - pub baseline_exposure: f64, + +/// SMPTE ST 12-1 time code of a CinemaDNG frame. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Timecode { + pub hours: u8, + pub minutes: u8, + pub seconds: u8, + pub frames: u8, + pub drop_frame: bool, } -/// Metadata reader with the file's main and raw IFDs. -pub struct Metadata<'a, 'i> { - pub tiff: Tiff<'a>, - pub main: &'i Ifd, - pub raw: &'i Ifd, + +impl Timecode { + /// The first time code of a CinemaDNG TimeCodes tag (SMPTE ST 331 / 12-1 packing: BCD frames, + /// seconds, minutes, hours in bytes 0–3, the drop-frame flag in bit 6 of byte 0). + pub fn from_bytes(b: &[u8]) -> Option { + let bcd = |v: u8, tens_mask: u8| { + let (u, t) = (v & 0x0F, (v >> 4) & tens_mask); + (u <= 9).then_some(t * 10 + u) + }; + let [f, s, m, h, ..] = *b else { return None }; + let tc = Timecode { frames: bcd(f, 0x3)?, seconds: bcd(s, 0x7)?, minutes: bcd(m, 0x7)?, hours: bcd(h, 0x3)?, drop_frame: f & 0x40 != 0 }; + (tc.seconds < 60 && tc.minutes < 60 && tc.hours < 24).then_some(tc) + } } -impl Metadata<'_, '_> { + +/// What a DNG holds, without decoding the pixels. +#[derive(Clone, Debug, PartialEq)] +pub struct Info { + /// Size of the developed picture (the default crop). + pub width: usize, + pub height: usize, + /// Size of the stored raw image. + pub raw_width: usize, + pub raw_height: usize, + pub bits: u32, + pub samples_per_pixel: usize, + /// Colour filter array data (else LinearRaw). + pub cfa: bool, + /// "uncompressed" or "lossless JPEG". + pub compression: &'static str, + pub dng_version: [u8; 4], + /// CinemaDNG FrameRate (numerator, denominator). + pub frame_rate: Option<(i64, i64)>, + /// CinemaDNG time code of this frame. + pub timecode: Option, + /// UniqueCameraModel, else Make and Model. + pub camera: Option, + /// CinemaDNG ReelName. + pub reel: Option, +} + +/// A developed DNG: premultiplied, scene-linear Rec. 709 RGBA floats (alpha 1), top row first. +/// A white surface the sensor saw at its clipping level is 1.0 times 2^BaselineExposure. +pub struct Image { + pub info: Info, + pub width: usize, + pub height: usize, + pub rgba: Vec, +} + +/// A parsed DNG file. +pub struct Dng<'a> { + tiff: Tiff<'a>, + ifds: Vec, + /// Index of the main raw IFD in `ifds` (the first is IFD 0). + raw: usize, +} + +impl<'a> Dng<'a> { + /// Parse the container and find the main raw image. + pub fn parse(bytes: &'a [u8]) -> Result> { + let (tiff, first) = Tiff::new(bytes)?; + let ifds = tiff.all_ifds(first)?; + if ifds.first().and_then(|i| i.get(tags::DNG_VERSION)).is_none() { + return Err(Error::NotDng); + } + let main = raw::find_raw_ifd(&tiff, &ifds)?; + let raw = ifds.iter().position(|i| i.offset == main.offset).ok_or(Error::Malformed("raw IFD"))?; + Ok(Dng { tiff, ifds, raw }) + } + + fn ifd0(&self) -> &Ifd { + static EMPTY: Ifd = Ifd { offset: 0, entries: Vec::new(), depth: 0 }; + self.ifds.first().unwrap_or(&EMPTY) + } + + fn raw_ifd(&self) -> &Ifd { + self.ifds.get(self.raw).unwrap_or(self.ifd0()) + } + /// A raw-image tag: from the raw IFD, else IFD 0. fn raw_tag(&self, tag: u16) -> Option<&Entry> { - self.raw.get(tag).or_else(|| self.main.get(tag)) + self.raw_ifd().get(tag).or_else(|| self.ifd0().get(tag)) } /// A camera-wide tag: from IFD 0, else the raw IFD. fn main_tag(&self, tag: u16) -> Option<&Entry> { - self.main.get(tag).or_else(|| self.raw.get(tag)) + self.ifd0().get(tag).or_else(|| self.raw_ifd().get(tag)) } /// A numeric tag's values; a value outside the file (or a zero denominator) is an error, so a /// damaged file does not silently lose its white balance. fn floats(&self, e: Option<&Entry>) -> Result>> { - Ok(e.map(|e| self.tiff.floats(e)).transpose()?) + e.map(|e| self.tiff.floats(e)).transpose() } /// A 3 × 3 matrix tag (`None` when absent or not 3 × 3, e.g. for other colour counts). @@ -70,9 +168,13 @@ impl Metadata<'_, '_> { Ok(self.floats(self.main_tag(tag))?.and_then(|v| <[f64; 3]>::try_from(v.as_slice()).ok())) } + fn text(&self, tag: u16) -> Option { + self.main_tag(tag).and_then(|e| self.tiff.ascii(e).ok()).filter(|s| !s.is_empty()) + } + /// The CFA pattern in camera planes (`None` for LinearRaw). - pub fn cfa(&self) -> Result> { - let l = dng_lines::layout(&self.tiff, self.raw)?; + fn cfa(&self) -> Result> { + let l = raw::layout(&self.tiff, self.raw_ifd())?; if l.photometric != PHOTOMETRIC_CFA { return Ok(None); } @@ -109,6 +211,7 @@ impl Metadata<'_, '_> { Ok(Some(Pattern { rows, cols, colors })) } + /// The processing tags of the raw image. pub fn params(&self) -> Result { let uint_pair = |tag| -> Result> { match self.raw_tag(tag) { @@ -145,7 +248,7 @@ impl Metadata<'_, '_> { None => Ok(None), } }; - let list = |tag| -> Result> { Ok(self.raw_tag(tag).map(|e| self.tiff.floats(e)).transpose()?.unwrap_or_default()) }; + let list = |tag| -> Result> { self.raw_tag(tag).map(|e| self.tiff.floats(e)).transpose().map(Option::unwrap_or_default) }; Ok(Params { active_area, linearization, @@ -178,26 +281,78 @@ impl Metadata<'_, '_> { baseline_exposure: self.floats(self.main_tag(tags::BASELINE_EXPOSURE))?.and_then(|v| v.first().copied()).unwrap_or(0.0), }) } -} -#[cfg(test)] -mod tests { - use super::*; + /// Size, depth and CinemaDNG metadata. + pub fn info(&self) -> Result { + let l = raw::layout(&self.tiff, self.raw_ifd())?; + let p = self.params()?; + let (_, _, aw, ah) = process::active_rect(&p, l.width, l.height)?; + let (_, _, width, height) = process::crop_rect(&p, aw, ah); + let dng_version = self + .main_tag(tags::DNG_VERSION) + .and_then(|e| self.tiff.uints(e).ok()) + .and_then(|v| v.get(..4).map(|v| [0, 1, 2, 3].map(|i| v[i] as u8))) + .unwrap_or_default(); + let frame_rate = self.main_tag(tags::FRAME_RATE).and_then(|e| { + let b = self.tiff.value_bytes(e).ok()?; + if !matches!(e.ty, tiff::Type::SRational | tiff::Type::Rational) { + return None; + } + let n = i64::from(self.tiff.u32_of(b.get(0..4)?.try_into().ok()?) as i32); + let d = i64::from(self.tiff.u32_of(b.get(4..8)?.try_into().ok()?) as i32); + (n > 0 && d > 0 && n <= 1000 * d && n * 1000 >= d).then_some((n, d)) + }); + let timecode = self.main_tag(tags::TIME_CODES).and_then(|e| self.tiff.value_bytes(e).ok()).and_then(Timecode::from_bytes); + let camera = self.text(tags::UNIQUE_CAMERA_MODEL).or_else(|| { + let mm = [self.text(tags::MAKE), self.text(tags::MODEL)].into_iter().flatten().collect::>().join(" "); + (!mm.is_empty()).then_some(mm) + }); + Ok(Info { + width, + height, + raw_width: l.width, + raw_height: l.height, + bits: l.bits, + samples_per_pixel: l.samples_per_pixel, + cfa: p.cfa.is_some(), + compression: if l.compression == 7 { "lossless JPEG" } else { "uncompressed" }, + dng_version, + frame_rate, + timecode, + camera, + reel: self.text(tags::REEL_NAME), + }) + } - #[test] - fn calibration_defaults_and_rejects_bad_rational() -> Result<()> { - let empty = Ifd::default(); - let tiff = Tiff { data: &[], big_endian: false }; - let metadata = Metadata { tiff, main: &empty, raw: &empty }; - let calibration = metadata.calibration()?; - assert_eq!(calibration.baseline_exposure, 0.0); - assert_eq!(calibration.color_matrix, [None, None]); + /// The raw samples of the main image, as stored (before any processing). + pub fn raw(&self) -> Result { + raw::read(&self.tiff, self.raw_ifd()) + } - // IFD with one BaselineExposure SRational pointing past the end of the file. - let data = [b'I', b'I', 42, 0, 8, 0, 0, 0, 1, 0, 42, 198, 10, 0, 1, 0, 0, 0, 200, 0, 0, 0, 0, 0, 0, 0]; - let (tiff, first) = Tiff::new(&data)?; - let (ifd, _) = tiff.read_ifd(first, 0)?; - assert!(Metadata { tiff, main: &ifd, raw: &ifd }.calibration().is_err()); - Ok(()) + /// Develop the main image to scene-linear Rec. 709. + pub fn develop(&self) -> Result { + let info = self.info()?; + let p = self.params()?; + let raw = self.raw()?; + let calibration = self.calibration()?; + let solved = if p.cfa.is_none() && raw.samples_per_pixel == 1 { + // monochrome: no colour, only the exposure + let e = 2f64.powf(calibration.baseline_exposure.clamp(-16.0, 16.0)); + color::Solved { neutral: [1.0; 3], matrix: color::scale(&color::IDENTITY, e), white_xy: color::D65 } + } else { + calibration.solve()? + }; + let d = process::develop(&raw, &p, &solved.neutral, &solved.matrix)?; + Ok(Image { info, width: d.width, height: d.height, rgba: d.rgba }) } } + +/// Parse and develop a DNG file. +pub fn decode(bytes: &[u8]) -> Result { + Dng::parse(bytes)?.develop() +} + +/// Parse a DNG file's metadata. +pub fn probe(bytes: &[u8]) -> Result { + Dng::parse(bytes)?.info() +}