#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] //! DPX (SMPTE ST 268 Digital Picture Exchange) and Kodak Cineon (`.cin`) frames, read and written //! from the published layouts. The crate goes from bytes to code values and header fields and //! back; colour (log conversion, Y'CbCr matrices) and turning the picture upright stay with the //! caller, who gets the fields those need. //! //! Reading ([`probe`], [`decode`]): //! //! * DPX in both byte orders (`SDPX` big-endian, `XPDS` little-endian), Cineon in both. //! * The first image element: luma (descriptor 6), RGB (50), RGBA (51), ABGR (52, returned as //! RGBA) and Y'CbCr (100 CbYCrY 4:2:2, 101 CbYACrYA 4:2:2:4, 102 CbYCr 4:4:4, 103 CbYCrA //! 4:4:4:4, returned in stored component order); Cineon with one or three channels. //! * Unsigned samples without run-length encoding at 8, 10, 12 or 16 bits. 10-bit samples sit //! three to a 32-bit word with the padding bits at the bottom (packing 1, method A; Cineon //! packing 5) or the top (packing 2, method B; Cineon packing 6), the first sample in the high //! bits, except that a DPX luma element fills each word from its low end; 12-bit samples sit //! one to a 16-bit word the same two ways. Packed 10- and 12-bit samples (packing 0) follow each other //! through the line's 32-bit words, the first in the low bits. Lines start on a 32-bit boundary //! and may carry end-of-line padding; 8- and 16-bit files whose lines are not padded to a word //! are read too. //! * [`Frame::codes`] holds the code values as stored, line by line. [`widen`] maps a code to 16 //! bits and [`narrow`] back, exactly. //! * [`Info`] carries what a pipeline needs: orientation, transfer and colorimetric codes, the //! reference low and high codes, pixel aspect ratio, creator, project, copyright, creation //! time, frame position, frame rate and time code. //! //! Writing ([`encode`], [`encode_cineon`]): one element, big-endian, unencoded; DPX luma, RGB or //! RGBA at 8 and 16 bits (packing 0) or 10 and 12 bits (packing 1, method A); Cineon luma or RGB //! at 10 bits. //! //! Not read (an [`Error::Unsupported`]): run-length encoded elements, signed, 1-bit and //! floating-point samples, Cineon with line or channel interleave. //! //! Input is treated as hostile: every header read is bounds-checked, the picture size is capped //! by [`Limits`] and the image data must be present in full before anything is allocated. #[cfg(test)] mod tests; /// Generic plus industry header of a DPX file: where written image data starts. const HEADER_LEN: usize = 2048; const GENERIC_LEN: u32 = 1664; const INDUSTRY_LEN: u32 = 384; /// "Undefined" for 32-bit fields (also the bit pattern of an undefined float). const UNDEF32: u32 = u32::MAX; const UNDEF8: u8 = u8::MAX; /// Offset of the first image element and the size of one. const ELEMENT0: usize = 780; const ELEMENT_LEN: usize = 72; const MAX_ELEMENTS: u16 = 8; // Header field offsets (generic file header, image information, orientation, film and TV headers). const CREATION_TIME: (usize, usize) = (136, 24); const CREATOR: (usize, usize) = (160, 100); const PROJECT: (usize, usize) = (260, 200); const COPYRIGHT: (usize, usize) = (460, 200); const ORIENTATION: usize = 768; const PIXEL_ASPECT: usize = 1628; const FRAME_POSITION: usize = 1712; const FRAME_RATE: usize = 1724; const TIME_CODE: usize = 1920; const CINEON_MAGIC: [u8; 4] = [0x80, 0x2A, 0x5F, 0xD7]; /// Cineon's generic plus film header: where written image data starts. const CINEON_HEADER_LEN: usize = 2048; const CINEON_GENERIC_LEN: u32 = 1024; /// Offset of the first of the eight 28-byte channel descriptors. const CINEON_CHANNEL0: usize = 196; /// Why a file could not be read or written. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] pub enum Error { /// The bytes start with neither a DPX nor a Cineon magic number. #[error("not a DPX or Cineon file")] NotDpx, /// The header or the image data is damaged or cut short. #[error("DPX: {0}")] Malformed(String), /// A valid file this reader does not cover. #[error("unsupported DPX: {0}")] Unsupported(String), /// The file declares more than [`Limits`] allow. #[error("DPX exceeds a limit: {0}")] LimitExceeded(&'static str), /// The picture handed to the writer cannot be stored. #[error("DPX: cannot write: {0}")] Encode(String), } /// Result of this crate's functions. pub type Result = std::result::Result; /// Caps on what a header may ask the reader to allocate, checked before anything is allocated. /// `#[non_exhaustive]`: start from [`Limits::default`] and set the fields you change. #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[non_exhaustive] pub struct Limits { /// Most pixels (width × height) a picture may have. Default 2^28 (16384 × 16384). pub max_pixels: u64, } impl Default for Limits { fn default() -> Self { Self { max_pixels: 1 << 28 } } } /// Which of the two formats a file is. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Kind { Dpx, Cineon, } /// What the components of a pixel are, in the order [`Frame::codes`] holds them. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Layout { /// One component. Luma, /// Red, green, blue. Rgb, /// Red, green, blue, alpha (descriptor 51, and descriptor 52 ABGR reordered). Rgba, /// 4:2:2: two components a pixel, Cb then Y' on even pixels and Cr then Y' on odd ones. CbYCrY422, /// 4:2:2:4: three components a pixel, Cb, Y', A on even pixels and Cr, Y', A on odd ones. CbYACrYA4224, /// 4:4:4: Cb, Y', Cr. CbYCr444, /// 4:4:4:4: Cb, Y', Cr, A. CbYCrA4444, } impl Layout { /// Components stored for each pixel. pub fn components(self) -> usize { match self { Layout::Luma => 1, Layout::CbYCrY422 => 2, Layout::Rgb | Layout::CbYACrYA4224 | Layout::CbYCr444 => 3, Layout::Rgba | Layout::CbYCrA4444 => 4, } } /// Whether the last component of a pixel is alpha. pub fn has_alpha(self) -> bool { matches!(self, Layout::Rgba | Layout::CbYACrYA4224 | Layout::CbYCrA4444) } /// Whether the components are Y'CbCr, which the caller converts with its own matrices. pub fn is_ycbcr(self) -> bool { matches!(self, Layout::CbYCrY422 | Layout::CbYACrYA4224 | Layout::CbYCr444 | Layout::CbYCrA4444) } } /// What the header says about the first image element and the frame. #[derive(Debug, Clone, PartialEq)] pub struct Info { pub kind: Kind, pub big_endian: bool, pub width: u32, pub height: u32, /// Image elements the file declares; only the first is read. Always 1 for Cineon. pub elements: u16, /// The element's descriptor as stored (DPX; 52 for ABGR although [`Info::layout`] is RGBA). 0 for Cineon. pub descriptor: u8, pub layout: Layout, /// Bits per component: 8, 10, 12 or 16. pub bits: u8, /// The image orientation as the DPX code 0–7 (Cineon's codes are translated); other values, /// undefined included, are kept as stored and read as 0. See [`Info::exif_orientation`]. pub orientation: u16, /// Transfer characteristic code (DPX), `None` when undefined. pub transfer: Option, /// Colorimetric specification code (DPX), `None` when undefined. pub colorimetric: Option, /// Reference low data code value as stored (DPX; undefined is `u32::MAX`). pub reference_low_code: u32, /// Reference high data code value as stored (DPX; undefined is `u32::MAX`). pub reference_high_code: u32, /// Pixel aspect ratio as horizontal and vertical parts, both non-zero, when stated. pub pixel_aspect: Option<(u32, u32)>, pub creator: Option, pub project: Option, pub copyright: Option, /// Creation time as written (`yyyy:mm:dd:hh:mm:ss:LTZ` by the standard). pub creation_time: Option, /// Frame position in the sequence (film header), when the industry header is present. pub frame_position: Option, /// Frame rate of the original (film header), when the industry header is present. pub frame_rate: Option, /// SMPTE time code as BCD `HHMMSSFF` (television header). See [`format_time_code`]. pub time_code: Option, } impl Info { /// The EXIF orientation (1–8) that turns the stored lines upright. Anything outside the /// codes 0–7 is taken as the default (1). pub fn exif_orientation(&self) -> u16 { match self.orientation { 1 => 2, 2 => 4, 3 => 3, 4 => 5, 5 => 6, 6 => 8, 7 => 7, _ => 1, } } /// For the four orientations that keep lines horizontal: whether pixels run right to left and /// whether lines run bottom to top. `None` for the transposed orientations (4–7). pub fn flips(&self) -> Option<(bool, bool)> { match self.orientation { 1 => Some((true, false)), 2 => Some((false, true)), 3 => Some((true, true)), 4..=7 => None, _ => Some((false, false)), } } /// The largest code value: `2^bits − 1`. pub fn max_code(&self) -> u16 { max_code(self.bits) } } /// A decoded frame. #[derive(Debug, Clone, PartialEq)] pub struct Frame { pub info: Info, /// Code values as stored: `height` lines of `width × layout.components()` values, each in /// `0..=info.max_code()`, first stored line first (see [`Info::orientation`]). pub codes: Vec, } impl Frame { /// The code values as 16-bit samples ([`widen`]); 16-bit codes are returned unchanged. pub fn samples_u16(&self) -> Vec { if self.info.bits == 16 { self.codes.clone() } else { self.codes.iter().map(|&c| widen(c, self.info.bits)).collect() } } } fn malformed(msg: impl Into) -> Error { Error::Malformed(msg.into()) } fn unsupported(msg: impl Into) -> Error { Error::Unsupported(msg.into()) } /// Bounds-checked reads in the file's byte order. #[derive(Clone, Copy)] struct Reader<'a> { b: &'a [u8], big: bool, } impl Reader<'_> { fn u8(&self, at: usize) -> Option { self.b.get(at).copied() } fn u16(&self, at: usize) -> Option { let s: [u8; 2] = self.b.get(at..at.checked_add(2)?)?.try_into().ok()?; Some(if self.big { u16::from_be_bytes(s) } else { u16::from_le_bytes(s) }) } fn u32(&self, at: usize) -> Option { let s: [u8; 4] = self.b.get(at..at.checked_add(4)?)?.try_into().ok()?; Some(if self.big { u32::from_be_bytes(s) } else { u32::from_le_bytes(s) }) } /// A 32-bit field that may be undefined (all ones). fn defined_u32(&self, at: usize) -> Option { self.u32(at).filter(|&v| v != UNDEF32) } fn f32(&self, at: usize) -> Option { self.defined_u32(at).map(f32::from_bits).filter(|v| v.is_finite()) } /// An ASCII header string: up to the first NUL, printable characters only, trimmed. `None` /// when empty or undefined (all ones). fn string(&self, (at, len): (usize, usize)) -> Option { let raw = self.b.get(at..at.checked_add(len)?)?; let end = raw.iter().position(|&c| c == 0).unwrap_or(raw.len()); let s: String = raw.get(..end)?.iter().filter(|c| (32..=126).contains(*c)).map(|&c| c as char).collect(); Some(s.trim().to_string()).filter(|s| !s.is_empty()) } } /// The format and byte order from the magic number, `None` when the bytes are neither. fn magic(bytes: &[u8]) -> Option<(Kind, bool)> { match bytes.get(..4)? { b"SDPX" => Some((Kind::Dpx, true)), b"XPDS" => Some((Kind::Dpx, false)), [0x80, 0x2A, 0x5F, 0xD7] => Some((Kind::Cineon, true)), [0xD7, 0x5F, 0x2A, 0x80] => Some((Kind::Cineon, false)), _ => None, } } /// Whether `bytes` starts with a DPX or Cineon magic number (either byte order), and which. pub fn sniff(bytes: &[u8]) -> Option { magic(bytes).map(|(kind, _)| kind) } /// How samples are stored in a line. #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum Packing { /// One byte per sample. Bytes, /// One 16-bit word per sample; the value is `(word >> shift) & mask`. Words { shift: u32, mask: u16 }, /// Three 10-bit samples per 32-bit word above `pad` bits: the first in the high bits, or in /// the low bits when `low_first` (a DPX element of one component). Ten { pad: u32, low_first: bool }, /// `bits`-bit samples back to back through 32-bit words, low bits first (packing 0). Packed { bits: u32 }, } impl Packing { /// Bytes of a line of `samples` samples, padded to a 32-bit word. fn line_bytes(self, samples: usize) -> Option { let raw = match self { Packing::Bytes => samples, Packing::Words { .. } => samples.checked_mul(2)?, Packing::Ten { .. } => samples.div_ceil(3).checked_mul(4)?, Packing::Packed { bits } => samples.checked_mul(bits as usize)?.div_ceil(32).checked_mul(4)?, }; raw.checked_next_multiple_of(4) } /// Bytes of a line that is not padded to a word (some writers' 8- and 16-bit lines). fn tight_line_bytes(self, samples: usize) -> Option { match self { Packing::Bytes => Some(samples), Packing::Words { shift: 0, mask: u16::MAX } => samples.checked_mul(2), _ => None, } } /// The code values of one stored line. fn unpack(self, line: &[u8], big: bool, out: &mut [u16]) -> Result<()> { let short = || malformed("truncated image data"); let r = Reader { b: line, big }; match self { Packing::Bytes => { let src = line.get(..out.len()).ok_or_else(short)?; for (v, &c) in out.iter_mut().zip(src) { *v = u16::from(c); } } Packing::Words { shift, mask } => { for (i, v) in out.iter_mut().enumerate() { *v = (r.u16(i * 2).ok_or_else(short)? >> shift) & mask; } } Packing::Ten { pad, low_first } => { for (i, v) in out.iter_mut().enumerate() { let word = r.u32(i / 3 * 4).ok_or_else(short)?; let slot = (i % 3) as u32; *v = ((word >> (pad + 10 * if low_first { slot } else { 2 - slot })) & 0x3FF) as u16; } } Packing::Packed { bits } => { let mask = (1u64 << bits) - 1; let (mut acc, mut have, mut word) = (0u64, 0u32, 0usize); for v in out.iter_mut() { if have < bits { acc |= u64::from(r.u32(word * 4).ok_or_else(short)?) << have; word += 1; have += 32; } *v = (acc & mask) as u16; acc >>= bits; have -= bits; } } } Ok(()) } } /// A parsed header: the public description plus where and how the samples are stored. struct Parsed { info: Info, packing: Packing, data_offset: usize, eol_padding: usize, /// Descriptor 52: the stored component order is A, B, G, R. abgr: bool, } fn parse(bytes: &[u8]) -> Result { let (kind, big) = magic(bytes).ok_or(Error::NotDpx)?; let r = Reader { b: bytes, big }; match kind { Kind::Dpx => parse_dpx(r), Kind::Cineon => parse_cineon(r), } } fn parse_dpx(r: Reader) -> Result { let missing = |what: &str| malformed(format!("the header ends before {what}")); let image_offset = r.u32(4).ok_or_else(|| missing("the image data offset"))?; let orientation = r.u16(ORIENTATION).ok_or_else(|| missing("the orientation"))?; let elements = r.u16(ORIENTATION + 2).ok_or_else(|| missing("the element count"))?; if !(1..=MAX_ELEMENTS).contains(&elements) { return Err(malformed(format!("invalid number of image elements {elements}"))); } let width = r.u32(772).ok_or_else(|| missing("the line length"))?; let height = r.u32(776).ok_or_else(|| missing("the line count"))?; let e = ELEMENT0; let field = |at: usize| r.u32(e + at).ok_or_else(|| missing("image element 1")); let byte = |at: usize| r.u8(e + at).ok_or_else(|| missing("image element 1")); let half = |at: usize| r.u16(e + at).ok_or_else(|| missing("image element 1")); let signed = field(0)? == 1; let (descriptor, transfer, colorimetric, bits) = (byte(20)?, byte(21)?, byte(22)?, byte(23)?); let (packing, encoding) = (half(24)?, half(26)?); let data_offset = match field(28)? { 0 | UNDEF32 => image_offset, v => v, }; let eol_padding = match field(32)? { UNDEF32 => 0, v => v, }; let layout = match descriptor { 6 => Layout::Luma, 50 => Layout::Rgb, 51 | 52 => Layout::Rgba, 100 => Layout::CbYCrY422, 101 => Layout::CbYACrYA4224, 102 => Layout::CbYCr444, 103 => Layout::CbYCrA4444, d => return Err(unsupported(format!("descriptor {d} (luma, RGB, RGBA, ABGR and Y'CbCr are read)"))), }; if signed { return Err(unsupported("data sign 1 (signed samples)")); } if encoding != 0 { return Err(unsupported(format!("encoding {encoding} (run-length encoded data)"))); } let packing = match (bits, packing) { (8, _) => Packing::Bytes, (16, _) => Packing::Words { shift: 0, mask: u16::MAX }, // A one-component element fills each word from its low end; RGB keeps red on top. (10, 1) => Packing::Ten { pad: 2, low_first: layout == Layout::Luma }, (10, 2) => Packing::Ten { pad: 0, low_first: layout == Layout::Luma }, (12, 1) => Packing::Words { shift: 4, mask: 0xFFF }, (12, 2) => Packing::Words { shift: 0, mask: 0xFFF }, (10 | 12, 0) => Packing::Packed { bits: u32::from(bits) }, (10 | 12, p) => return Err(unsupported(format!("packing {p} at {bits} bits"))), (b, _) => return Err(unsupported(format!("bit size {b} (8, 10, 12 and 16 are read)"))), }; // The industry header is there when the generic header says so and the file holds it. let industry = r.u32(28).is_some_and(|l| l != 0 && l != UNDEF32) && r.b.len() >= HEADER_LEN; let pixel_aspect = match (r.defined_u32(PIXEL_ASPECT), r.defined_u32(PIXEL_ASPECT + 4)) { (Some(h), Some(v)) if h != 0 && v != 0 => Some((h, v)), _ => None, }; let info = Info { kind: Kind::Dpx, big_endian: r.big, width, height, elements, descriptor, layout, bits, orientation, transfer: Some(transfer).filter(|&t| t != UNDEF8), colorimetric: Some(colorimetric).filter(|&c| c != UNDEF8), reference_low_code: field(4)?, reference_high_code: field(12)?, pixel_aspect, creator: r.string(CREATOR), project: r.string(PROJECT), copyright: r.string(COPYRIGHT), creation_time: r.string(CREATION_TIME), frame_position: if industry { r.defined_u32(FRAME_POSITION) } else { None }, frame_rate: if industry { r.f32(FRAME_RATE) } else { None }, time_code: if industry { r.defined_u32(TIME_CODE) } else { None }, }; Ok(Parsed { info, packing, data_offset: usize::try_from(data_offset).map_err(|_| malformed("image data offset out of range"))?, eol_padding: usize::try_from(eol_padding).map_err(|_| malformed("line padding out of range"))?, abgr: descriptor == 52, }) } // Cineon is the film-scan format DPX grew from (same header family). The generic header is 1024 // bytes: the file information fields, then at offset 192 the image orientation (1 byte), the // channel count (1 byte) and up to eight 28-byte channel descriptors (each carries its bits per // pixel and the line and image dimensions), and at 680 the interleave, packing, sign and // end-of-line padding. 10-bit data is three samples to a 32-bit word, lines on a word boundary: // the same layout as DPX's filled 10-bit methods, so the unpacking and packing are shared. fn parse_cineon(r: Reader) -> Result { let missing = |what: &str| malformed(format!("the Cineon header ends before {what}")); let image_offset = r.u32(4).ok_or_else(|| missing("the image data offset"))?; let orientation = r.u8(192).ok_or_else(|| missing("the orientation"))?; let channels = r.u8(193).ok_or_else(|| missing("the channel count"))?; let bits = r.u8(198).ok_or_else(|| missing("the bits per pixel"))?; let width = r.u32(200).ok_or_else(|| missing("the pixels per line"))?; let height = r.u32(204).ok_or_else(|| missing("the lines per image"))?; let layout = match channels { 1 => Layout::Luma, 3 => Layout::Rgb, n => return Err(unsupported(format!("Cineon with {n} channels (1 and 3 are read)"))), }; // Channel 0 describes the picture; every other channel must match it. for c in 1..usize::from(channels) { let base = CINEON_CHANNEL0 + 28 * c; if r.u8(base + 2) != Some(bits) || r.u32(base + 4) != Some(width) || r.u32(base + 8) != Some(height) { return Err(unsupported("Cineon channels of different sizes or depths")); } } let interleave = r.u8(680).ok_or_else(|| missing("the data format"))?; let packing = r.u8(681).ok_or_else(|| missing("the data format"))?; let signed = r.u8(682).ok_or_else(|| missing("the data format"))?; let eol_padding = r.u32(684).ok_or_else(|| missing("the data format"))?; let eol_padding = if eol_padding == UNDEF32 { 0 } else { eol_padding }; if interleave != 0 && channels != 1 { return Err(unsupported("Cineon with line or channel interleave")); } if signed == 1 { return Err(unsupported("Cineon with signed samples")); } let packing = match (bits, packing) { (8, _) => Packing::Bytes, (16, _) => Packing::Words { shift: 0, mask: u16::MAX }, (10, 6) => Packing::Ten { pad: 0, low_first: false }, // 5 is the usual "32-bit left justified"; 0 and undefined come from writers that leave the field unset. (10, 0 | 5 | UNDEF8) => Packing::Ten { pad: 2, low_first: false }, (10, p) => return Err(unsupported(format!("Cineon with 10-bit packing {p} (32-bit words are read)"))), (b, _) => return Err(unsupported(format!("Cineon with {b}-bit samples (8, 10 and 16 are read)"))), }; // Cineon numbers "left to right, bottom to top" 1 and "right to left, top to bottom" 2: the // reverse of DPX. 0 and 3–7 mean the same in both. let orientation = match orientation { 1 => 2, 2 => 1, o => u16::from(o), }; let info = Info { kind: Kind::Cineon, big_endian: r.big, width, height, elements: 1, descriptor: 0, layout, bits, orientation, transfer: None, colorimetric: None, reference_low_code: UNDEF32, reference_high_code: UNDEF32, pixel_aspect: None, creator: None, project: None, copyright: None, creation_time: None, frame_position: None, frame_rate: None, time_code: None, }; Ok(Parsed { info, packing, data_offset: usize::try_from(image_offset).map_err(|_| malformed("image data offset out of range"))?, eol_padding: usize::try_from(eol_padding).map_err(|_| malformed("line padding out of range"))?, abgr: false, }) } /// Where the lines of a validated file are. struct Lines<'a> { data: &'a [u8], /// Samples in a line. per_line: usize, /// Bytes from one line's start to the next. stride: usize, } /// Checks the picture size against `limits` and that the file holds every line. fn locate<'a>(bytes: &'a [u8], p: &Parsed, limits: &Limits) -> Result> { let (width, height) = (p.info.width, p.info.height); if width == 0 || height == 0 { return Err(malformed("empty picture")); } if u64::from(width) * u64::from(height) > limits.max_pixels { return Err(Error::LimitExceeded("pixel count")); } let too_large = || Error::LimitExceeded("image size"); let per_line = usize::try_from(width).ok().and_then(|w| w.checked_mul(p.info.layout.components())).ok_or_else(too_large)?; let height = usize::try_from(height).map_err(|_| too_large())?; let data = bytes.get(p.data_offset..).ok_or_else(|| malformed("the image data offset is past the end of the file"))?; let mut line_len = p.packing.line_bytes(per_line).ok_or_else(too_large)?; let mut stride = line_len.checked_add(p.eol_padding).ok_or_else(too_large)?; // Lines run `stride` apart; the last one needs no padding after it. let span = |stride: usize, line_len: usize| stride.checked_mul(height - 1)?.checked_add(line_len); // Some writers store 8- and 16-bit lines without padding them to a word; take that layout // when the file is too short for padded lines but holds the unpadded ones. if let Some(tight) = p.packing.tight_line_bytes(per_line) && p.eol_padding == 0 && line_len != tight && span(stride, line_len).is_none_or(|need| data.len() < need) { (line_len, stride) = (tight, tight); } if span(stride, line_len).ok_or_else(too_large)? > data.len() { return Err(malformed("truncated image data")); } Ok(Lines { data, per_line, stride }) } /// Reads the header and checks that the frame can be decoded within `limits` (supported layout, /// size, image data present) without decoding it. pub fn probe(bytes: &[u8], limits: &Limits) -> Result { let p = parse(bytes)?; locate(bytes, &p, limits)?; Ok(p.info) } /// Decodes the first image element to code values. pub fn decode(bytes: &[u8], limits: &Limits) -> Result { let p = parse(bytes)?; let lines = locate(bytes, &p, limits)?; // `locate` proved the file holds at least a byte per sample, so this is bounded by its size. let total = lines.per_line.checked_mul(p.info.height as usize).ok_or(Error::LimitExceeded("image size"))?; let mut codes = vec![0u16; total]; for (y, row) in codes.chunks_exact_mut(lines.per_line).enumerate() { let line = y.checked_mul(lines.stride).and_then(|start| lines.data.get(start..)).ok_or_else(|| malformed("truncated image data"))?; p.packing.unpack(line, p.info.big_endian, row)?; if p.abgr { for px in row.as_chunks_mut::<4>().0 { px.reverse(); } } } Ok(Frame { info: p.info, codes }) } /// The largest code value at `bits` bits (`bits` above 16 is taken as 16, 0 as 1). fn max_code(bits: u8) -> u16 { u16::MAX >> (16 - u32::from(bits.clamp(1, 16))) } /// A `bits`-bit code value as a 16-bit sample: `round(c × 65535 / (2^bits − 1))`. A code written /// back with [`narrow`] at the same depth comes back exactly. pub fn widen(code: u16, bits: u8) -> u16 { let max = u64::from(max_code(bits)); ((u64::from(code) * 2 * 65535 + max) / (2 * max)).min(65535) as u16 } /// The inverse of [`widen`]: `round(v × (2^bits − 1) / 65535)`. pub fn narrow(sample: u16, bits: u8) -> u16 { let max = u64::from(max_code(bits)); ((u64::from(sample) * 2 * max + 65535) / (2 * 65535)) as u16 } /// A SMPTE time code (BCD `HHMMSSFF`) as `HH:MM:SS:FF`, or `0x…` when it is not valid BCD. pub fn format_time_code(v: u32) -> String { let d: [u32; 8] = std::array::from_fn(|i| (v >> ((7 - i) * 4)) & 0xF); if d.iter().all(|&d| d <= 9) { format!("{}{}:{}{}:{}{}:{}{}", d[0], d[1], d[2], d[3], d[4], d[5], d[6], d[7]) } else { format!("{v:#010x}") } } /// The inverse of [`format_time_code`]; `None` for anything else. pub fn parse_time_code(s: &str) -> Option { if let Some(hex) = s.strip_prefix("0x") { return u32::from_str_radix(hex, 16).ok(); } let parts: Vec<&str> = s.split(':').collect(); if parts.len() != 4 || parts.iter().any(|p| p.len() != 2 || !p.bytes().all(|c| c.is_ascii_digit())) { return None; } parts.iter().flat_map(|p| p.bytes()).try_fold(0u32, |acc, c| Some((acc << 4) | u32::from(c - b'0'))) } /// A picture to write: `height` lines of `width × layout.components()` code values, top line first. #[derive(Debug, Clone, Copy)] pub struct Picture<'a> { pub width: u32, pub height: u32, /// [`Layout::Luma`], [`Layout::Rgb`] or [`Layout::Rgba`] (Cineon: luma or RGB). pub layout: Layout, /// Bits per component: 8, 10, 12 or 16 (Cineon: 10). Codes above the depth's largest are masked. pub bits: u8, pub codes: &'a [u16], } /// Header fields a DPX writer fills in; everything left `None` is written as undefined or empty. #[derive(Debug, Clone, Copy, Default, PartialEq)] pub struct Metadata<'a> { pub creator: Option<&'a str>, pub project: Option<&'a str>, pub copyright: Option<&'a str>, pub creation_time: Option<&'a str>, /// Transfer characteristic code. No claim about the encoding is made when `None`. pub transfer: Option, /// Colorimetric specification code. pub colorimetric: Option, pub frame_position: Option, pub frame_rate: Option, /// SMPTE time code as BCD `HHMMSSFF` (see [`parse_time_code`]). pub time_code: Option, } /// A fixed-size big-endian header under construction. struct Writer { h: Vec, } impl Writer { fn bytes(&mut self, at: usize, v: &[u8]) { if let Some(s) = at.checked_add(v.len()).and_then(|end| self.h.get_mut(at..end)) { s.copy_from_slice(v); } } fn u8(&mut self, at: usize, v: u8) { self.bytes(at, &[v]); } fn u16(&mut self, at: usize, v: u16) { self.bytes(at, &v.to_be_bytes()); } fn u32(&mut self, at: usize, v: u32) { self.bytes(at, &v.to_be_bytes()); } /// Marks a run of numeric fields undefined (all ones). fn undefined(&mut self, from: usize, to: usize) { if let Some(s) = self.h.get_mut(from..to) { s.fill(0xFF); } } /// An ASCII string field, cut to leave room for a terminating NUL. fn string(&mut self, (at, len): (usize, usize), v: &str) { let ascii: Vec = v.chars().map(|c| if (' '..='~').contains(&c) { c as u8 } else { b'?' }).take(len.saturating_sub(1)).collect(); self.bytes(at, &ascii); } } /// Appends one line's code values, padded to a 32-bit word. `low_first`: 10-bit samples fill each /// word from its low end (a DPX element of one component). fn pack_line(out: &mut Vec, codes: &[u16], bits: u8, low_first: bool) { let start = out.len(); match bits { 8 => out.extend(codes.iter().map(|&c| c as u8)), 10 => { for chunk in codes.chunks(3) { let word = chunk .iter() .enumerate() .fold(0u32, |w, (i, &c)| w | (u32::from(c & 0x3FF) << (2 + 10 * if low_first { i as u32 } else { 2 - i as u32 }))); out.extend_from_slice(&word.to_be_bytes()); } } 12 => out.extend(codes.iter().flat_map(|&c| ((c & 0xFFF) << 4).to_be_bytes())), _ => out.extend(codes.iter().flat_map(|&c| c.to_be_bytes())), } let written = out.len() - start; out.resize(start + written.div_ceil(4) * 4, 0); } /// Samples in a line and bytes of image data for `pic`, after checking its sample count. fn layout_of(pic: &Picture, header_len: usize, what: &str) -> Result<(usize, usize, u32)> { let enc = |msg: &str| Error::Encode(msg.into()); if pic.width == 0 || pic.height == 0 { return Err(enc("empty picture")); } let (w, h) = (pic.width as usize, pic.height as usize); let per_line = w.checked_mul(pic.layout.components()).ok_or_else(|| enc("image too large"))?; if per_line.checked_mul(h) != Some(pic.codes.len()) { return Err(enc("the picture has the wrong number of samples")); } let line = match pic.bits { 8 => Packing::Bytes, 10 => Packing::Ten { pad: 2, low_first: false }, _ => Packing::Words { shift: 0, mask: u16::MAX }, } .line_bytes(per_line); let data_len = line.and_then(|l| l.checked_mul(h)).ok_or_else(|| enc("image too large"))?; let total = header_len .checked_add(data_len) .and_then(|t| u32::try_from(t).ok()) .ok_or_else(|| Error::Encode(format!("image too large for a {what} file (4 GiB)")))?; Ok((per_line, data_len, total)) } /// Writes a DPX 2.0 file: one element, big-endian, unencoded, default orientation. pub fn encode(pic: &Picture, meta: &Metadata) -> Result> { let descriptor = match pic.layout { Layout::Luma => 6u8, Layout::Rgb => 50, Layout::Rgba => 51, l => return Err(Error::Encode(format!("{l:?} is not written (luma, RGB and RGBA are)"))), }; let bits = pic.bits; if !matches!(bits, 8 | 10 | 12 | 16) { return Err(Error::Encode(format!("{bits} bits is not written (8, 10, 12 and 16 are)"))); } let (per_line, data_len, total) = layout_of(pic, HEADER_LEN, "DPX")?; let mut wr = Writer { h: vec![0; HEADER_LEN] }; // Generic file header. wr.bytes(0, b"SDPX"); wr.u32(4, HEADER_LEN as u32); wr.string((8, 8), "V2.0"); wr.u32(16, total); wr.u32(20, 1); wr.u32(24, GENERIC_LEN); wr.u32(28, INDUSTRY_LEN); wr.u32(32, 0); wr.string(CREATION_TIME, meta.creation_time.unwrap_or("")); wr.string(CREATOR, meta.creator.unwrap_or("")); wr.string(PROJECT, meta.project.unwrap_or("")); wr.string(COPYRIGHT, meta.copyright.unwrap_or("")); wr.u32(660, UNDEF32); // Image information: default orientation, one element. wr.u16(ORIENTATION, 0); wr.u16(ORIENTATION + 2, 1); wr.u32(772, pic.width); wr.u32(776, pic.height); let e = ELEMENT0; wr.u32(e, 0); wr.u32(e + 4, 0); wr.u32(e + 8, UNDEF32); wr.u32(e + 12, u32::from(max_code(bits))); wr.u32(e + 16, UNDEF32); wr.u8(e + 20, descriptor); wr.u8(e + 21, meta.transfer.unwrap_or(UNDEF8)); wr.u8(e + 22, meta.colorimetric.unwrap_or(UNDEF8)); wr.u8(e + 23, bits); wr.u16(e + 24, if matches!(bits, 10 | 12) { 1 } else { 0 }); wr.u16(e + 26, 0); wr.u32(e + 28, HEADER_LEN as u32); wr.u32(e + 32, 0); wr.u32(e + 36, 0); // The seven unused elements, the image source header's numbers and the industry header's // numbers are undefined; their strings stay empty. wr.undefined(e + ELEMENT_LEN, e + ELEMENT_LEN * usize::from(MAX_ELEMENTS)); wr.undefined(1408, 1432); wr.undefined(1620, 1644); wr.undefined(FRAME_POSITION, 1732); wr.undefined(TIME_CODE, 1972); if let Some(v) = meta.frame_position { wr.u32(FRAME_POSITION, v); } if let Some(v) = meta.frame_rate.filter(|v| v.is_finite()) { wr.u32(FRAME_RATE, v.to_bits()); } if let Some(v) = meta.time_code { wr.u32(TIME_CODE, v); } let mut out = wr.h; out.try_reserve_exact(data_len).map_err(|_| Error::Encode("out of memory".into()))?; for row in pic.codes.chunks_exact(per_line) { pack_line(&mut out, row, bits, pic.layout == Layout::Luma); } Ok(out) } /// Writes a Cineon 4.5 frame: the generic header, an undefined film header, then 10-bit code /// values three to a big-endian word, left justified (packing 5), lines on a word boundary. pub fn encode_cineon(pic: &Picture) -> Result> { // Channel designators: 0 for black and white, 1–3 for red, green and blue. let designators: &[u8] = match pic.layout { Layout::Luma => &[0], Layout::Rgb => &[1, 2, 3], l => return Err(Error::Encode(format!("Cineon cannot store {l:?}"))), }; if pic.bits != 10 { return Err(Error::Encode(format!("Cineon is written at 10 bits, not {}", pic.bits))); } let (per_line, data_len, total) = layout_of(pic, CINEON_HEADER_LEN, "Cineon")?; let mut wr = Writer { h: vec![0; CINEON_HEADER_LEN] }; // File information. wr.bytes(0, &CINEON_MAGIC); wr.u32(4, CINEON_HEADER_LEN as u32); wr.u32(8, CINEON_GENERIC_LEN); wr.u32(12, CINEON_HEADER_LEN as u32 - CINEON_GENERIC_LEN); wr.u32(16, 0); wr.u32(20, total); wr.string((24, 8), "V4.5"); // Image information: default orientation, then each channel's descriptor; the unused ones, // the white point and the primaries are undefined. wr.u8(192, 0); wr.u8(193, designators.len() as u8); wr.undefined(CINEON_CHANNEL0, 420); for (i, &designator) in designators.iter().enumerate() { let c = CINEON_CHANNEL0 + 28 * i; wr.u8(c, 0); wr.u8(c + 1, designator); wr.u8(c + 2, 10); wr.u8(c + 3, 0); wr.u32(c + 4, pic.width); wr.u32(c + 8, pic.height); // Code values 0–1023 stand for printing densities 0–2.048, the Cineon convention. All // four are 32-bit floats here (DPX stores the data values as integers). wr.u32(c + 12, 0f32.to_bits()); wr.u32(c + 16, 0f32.to_bits()); wr.u32(c + 20, 1023f32.to_bits()); wr.u32(c + 24, 2.048f32.to_bits()); } // Pixel-interleaved, unsigned, positive, no line or channel padding. wr.u8(681, 5); // Image origination: pixel pitches and gamma unknown. wr.undefined(972, 984); // Film header: manufacturer, type, perforation offset, prefix, count, frame position and rate // unknown; its strings stay empty. wr.undefined(1024, 1036); wr.undefined(1068, 1076); let mut out = wr.h; out.try_reserve_exact(data_len).map_err(|_| Error::Encode("out of memory".into()))?; for row in pic.codes.chunks_exact(per_line) { pack_line(&mut out, row, 10, false); } Ok(out) }