f67d38b35cc5
dpx.rs
//! DPX (`.dpx`) stills: craft-dpx (SMPTE ST 268) reads the header and the code values; FilmCraft
//! turns them into RGBA8 for the still pipeline.
//!
//! The first image element is decoded: luma, RGB, RGBA, ABGR, or Y'CbCr (CbYCrY 4:2:2, CbYACrYA
//! 4:2:2:4, CbYCr 4:4:4, CbYCrA 4:4:4:4), 8, 10, 12 or 16 bits per component, big-endian (`SDPX`) or
//! little-endian (`XPDS`) files, every packing craft-dpx reads. Orientations 0–3 (either scan
//! direction, either line order) are honoured. RGB and luma code values map linearly onto 8 bits
//! (full range); a logarithmic (printing density) transfer is shown as stored, without a film-log
//! conversion. Y'CbCr is converted with the matrix the colorimetric field names (BT.709, or BT.601
//! for the 601 and composite video codes; by picture size when unspecified), in video range unless
//! the reference low / high data codes span the whole code range; 4:2:2 chroma is shared by the two
//! pixels of a pair.
//!
//! Not decoded (an "unsupported" error): run-length encoded elements, signed, 1-bit and
//! floating-point components, transposed orientations. Cineon files are not routed here.
use craft_dpx::{Error, Layout, Limits};
use filmcraft_color::{Matrix, Range, normalize_c, normalize_y, ycbcr_to_rgb};
use crate::{MediaError, Result, still::Raster};
fn err(name: &str, what: &str) -> MediaError {
MediaError::Decode(format!("{name}: DPX: {what}"))
}
fn unsupported(name: &str, what: String) -> MediaError {
MediaError::Unsupported(format!("{name}: DPX {what}"))
}
fn map_error(name: &str, e: Error) -> MediaError {
match e {
Error::Unsupported(what) => unsupported(name, what),
Error::NotDpx => err(name, "not a DPX file"),
Error::Malformed(what) => err(name, &what),
Error::LimitExceeded(_) => err(name, "picture too large"),
Error::Encode(what) => err(name, &what),
}
}
/// Whether `bytes` starts with the DPX magic number in either byte order.
pub fn sniff(bytes: &[u8]) -> bool {
craft_dpx::sniff(bytes) == Some(craft_dpx::Kind::Dpx)
}
/// What the stored components of a pixel are.
#[derive(Clone, Copy)]
enum Components {
/// `n` components per pixel; the indices of R, G, B and A among them (alpha `None`: opaque).
Rgb { n: usize, map: [Option<usize>; 4] },
/// `n` components per pixel: Cb (4:2:2: Cb on even pixels, Cr on odd ones), Y', then Cr (4:4:4
/// only), then alpha when `alpha`.
YCbCr { n: usize, sub: bool, alpha: bool, matrix: Matrix, range: Range },
}
impl Components {
fn has_alpha(self) -> bool {
match self {
Components::Rgb { map, .. } => map[3].is_some(),
Components::YCbCr { alpha, .. } => alpha,
}
}
/// RGBA8 of pixel `x` from the component values of its scan line (`bits` per value).
fn pixel(self, line: &[u16], x: usize, bits: u32) -> [u8; 4] {
let max = (1u32 << bits) - 1;
let to8 = |v: u32| ((v.min(max) * 255 + max / 2) / max) as u8;
let get = |i: usize| line.get(i).map(|&v| u32::from(v));
match self {
Components::Rgb { n, map } => map.map(|slot| match slot {
Some(i) => get(x * n + i).map_or(0, to8),
None => 255,
}),
Components::YCbCr { n, sub, alpha, matrix, range } => {
let base = x * n;
let (cb, cr) = if sub {
let pair = (x & !1) * n;
(get(pair), get(pair + n))
} else {
(get(base), get(base + 2))
};
// a missing Cr (odd width, 4:2:2) is neutral
let mid = 1u32 << (bits - 1);
let y = normalize_y(get(base + 1).unwrap_or(0), bits, range);
let rgb = ycbcr_to_rgb(y, normalize_c(cb.unwrap_or(mid), bits, range), normalize_c(cr.unwrap_or(mid), bits, range), matrix);
let c = |v: f32| (v.clamp(0.0, 1.0) * 255.0).round() as u8;
let a = if alpha { get(base + n - 1).map_or(0, to8) } else { 255 };
[c(rgb[0]), c(rgb[1]), c(rgb[2]), a]
}
}
}
}
/// Decode the first image element of a DPX file to straight-alpha RGBA8, top row first.
pub fn decode(name: &str, bytes: &[u8]) -> Result<Raster> {
if !sniff(bytes) {
return Err(err(name, "not a DPX file"));
}
let frame = craft_dpx::decode(bytes, &Limits::default()).map_err(|e| map_error(name, e))?;
let info = &frame.info;
let (w, h) = (info.width as usize, info.height as usize);
let (flip_x, flip_y) = info.flips().ok_or_else(|| unsupported(name, format!("orientation {}", info.orientation)))?;
let max = u32::from(info.max_code());
// video range unless the reference codes span every code value
let range = if info.reference_low_code == 0 && info.reference_high_code == max { Range::Full } else { Range::Limited };
let matrix = match info.colorimetric {
Some(5 | 6) => Matrix::Bt709,
Some(7..=10) => Matrix::Bt601,
_ => filmcraft_frame::default_matrix(info.width, info.height),
};
let ycbcr = |n, sub, alpha| Components::YCbCr { n, sub, alpha, matrix, range };
let components = match info.layout {
Layout::Luma => Components::Rgb { n: 1, map: [Some(0), Some(0), Some(0), None] },
Layout::Rgb => Components::Rgb { n: 3, map: [Some(0), Some(1), Some(2), None] },
// craft-dpx returns ABGR (descriptor 52) reordered to RGBA
Layout::Rgba => Components::Rgb { n: 4, map: [Some(0), Some(1), Some(2), Some(3)] },
Layout::CbYCrY422 => ycbcr(2, true, false),
Layout::CbYACrYA4224 => ycbcr(3, true, true),
Layout::CbYCr444 => ycbcr(3, false, false),
Layout::CbYCrA4444 => ycbcr(4, false, true),
};
let per_line = w * info.layout.components();
let bits = u32::from(info.bits);
let pixels = w.checked_mul(h).ok_or_else(|| err(name, "picture too large"))?;
let mut rgba = vec![0u8; pixels * 4];
for (y, line) in frame.codes.chunks_exact(per_line.max(1)).take(h).enumerate() {
let dy = if flip_y { h - 1 - y } else { y };
for x in 0..w {
let dx = if flip_x { w - 1 - x } else { x };
let o = (dy * w + dx) * 4;
if let Some(px) = rgba.get_mut(o..o + 4) {
px.copy_from_slice(&components.pixel(line, x, bits));
}
}
}
let has_alpha = components.has_alpha() && rgba.as_chunks::<4>().0.iter().any(|p| p[3] != 255);
Ok(Raster { width: info.width, height: info.height, rgba, has_alpha })
}
#[cfg(test)]
mod tests {
use super::*;
/// First image element of the image information header.
const ELEMENT: usize = 780;
/// "Undefined" value of numeric header fields.
const UNDEFINED: u32 = u32::MAX;
/// A minimal DPX file (header + `data`) in the given byte order.
/// Image element fields of a test DPX header.
struct Element {
descriptor: u8,
bits: u8,
packing: u16,
}
fn file(big: bool, w: u32, h: u32, element: Element, orientation: u16, data: &[u8]) -> Vec<u8> {
let Element { descriptor, bits, packing } = element;
let mut f = vec![0u8; 2048];
let p32 = |f: &mut Vec<u8>, at: usize, v: u32| f[at..at + 4].copy_from_slice(&if big { v.to_be_bytes() } else { v.to_le_bytes() });
let p16 = |f: &mut Vec<u8>, at: usize, v: u16| f[at..at + 2].copy_from_slice(&if big { v.to_be_bytes() } else { v.to_le_bytes() });
f[0..4].copy_from_slice(if big { b"SDPX" } else { b"XPDS" });
p32(&mut f, 4, 2048);
p16(&mut f, 768, orientation);
p16(&mut f, 770, 1);
p32(&mut f, 772, w);
p32(&mut f, 776, h);
f[ELEMENT + 20] = descriptor;
f[ELEMENT + 23] = bits;
p16(&mut f, ELEMENT + 24, packing);
p32(&mut f, ELEMENT + 28, UNDEFINED);
p32(&mut f, ELEMENT + 32, UNDEFINED);
f.extend_from_slice(data);
f
}
#[test]
fn ten_bit_method_a_and_b() {
let word = |r: u32, g: u32, b: u32, pad: u32| ((r << (20 + pad)) | (g << (10 + pad)) | (b << pad)).to_be_bytes();
let mut data = Vec::new();
data.extend_from_slice(&word(1023, 0, 512, 2));
data.extend_from_slice(&word(4, 1019, 0, 2));
let r = decode("a.dpx", &file(true, 2, 1, Element { descriptor: 50, bits: 10, packing: 1 }, 0, &data)).unwrap();
assert_eq!(r.rgba, [255, 0, 128, 255, 1, 254, 0, 255]);
assert!(!r.has_alpha);
let mut data = Vec::new();
data.extend_from_slice(&word(1023, 0, 512, 0));
data.extend_from_slice(&word(4, 1019, 0, 0));
let r = decode("a.dpx", &file(true, 2, 1, Element { descriptor: 50, bits: 10, packing: 2 }, 0, &data)).unwrap();
assert_eq!(r.rgba, [255, 0, 128, 255, 1, 254, 0, 255]);
}
#[test]
fn rgba_components_roll_across_ten_bit_words() {
// 2 RGBA pixels = 8 components = 3 words; the last word is half empty
let comps = [1023u32, 0, 0, 1023, 0, 1023, 0, 0];
let mut data = Vec::new();
for c in comps.chunks(3) {
let get = |i: usize| c.get(i).copied().unwrap_or(0);
data.extend_from_slice(&((get(0) << 22) | (get(1) << 12) | (get(2) << 2)).to_le_bytes());
}
let r = decode("a.dpx", &file(false, 2, 1, Element { descriptor: 51, bits: 10, packing: 1 }, 0, &data)).unwrap();
assert_eq!(r.rgba, [255, 0, 0, 255, 0, 255, 0, 0]);
assert!(r.has_alpha);
}
#[test]
fn eight_bit_lines_pad_to_words_and_orientation_flips() {
// 1 × 2 RGB: each 3-byte line padded to 4; bottom-to-top, right-to-left orientation 3
let r = decode("a.dpx", &file(false, 1, 2, Element { descriptor: 50, bits: 8, packing: 0 }, 3, &[1, 2, 3, 0, 4, 5, 6, 0])).unwrap();
assert_eq!(r.rgba, [4, 5, 6, 255, 1, 2, 3, 255]);
// 2 × 1 luma, 16-bit big-endian; ABGR, 12-bit method A
let r = decode("a.dpx", &file(true, 2, 1, Element { descriptor: 6, bits: 16, packing: 0 }, 0, &[0xFF, 0xFF, 0x80, 0x00])).unwrap();
assert_eq!(r.rgba, [255, 255, 255, 255, 128, 128, 128, 255]);
let r =
decode("a.dpx", &file(true, 1, 1, Element { descriptor: 52, bits: 12, packing: 1 }, 0, &[0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xF0])).unwrap();
assert_eq!(r.rgba, [255, 0, 0, 128]);
}
/// Packing 0: components back to back, low bits first, each line on a 32-bit boundary.
fn packed(lines: &[&[u32]], bits: u32, big: bool) -> Vec<u8> {
let mut out = Vec::new();
for line in lines {
let (mut acc, mut n) = (0u64, 0u32);
for &v in *line {
acc |= u64::from(v) << n;
n += bits;
while n >= 32 {
let w = acc as u32;
out.extend_from_slice(&if big { w.to_be_bytes() } else { w.to_le_bytes() });
acc >>= 32;
n -= 32;
}
}
if n > 0 {
let w = acc as u32;
out.extend_from_slice(&if big { w.to_be_bytes() } else { w.to_le_bytes() });
}
}
out
}
#[test]
fn packed_ten_and_twelve_bit_components_cross_words() {
// 2 × 2 RGB 10-bit: 6 components (60 bits) per line, the fourth straddles two words
let lines: [&[u32]; 2] = [&[1023, 0, 512, 4, 1019, 1023], &[0, 1023, 0, 1023, 1023, 1023]];
for big in [true, false] {
let r = decode("a.dpx", &file(big, 2, 2, Element { descriptor: 50, bits: 10, packing: 0 }, 0, &packed(&lines, 10, big))).unwrap();
assert_eq!(r.rgba, [255, 0, 128, 255, 1, 254, 255, 255, 0, 255, 0, 255, 255, 255, 255, 255]);
}
// 3 × 1 RGB 12-bit: 9 components, 108 bits in 4 words
let line: [&[u32]; 1] = [&[4095, 0, 2048, 16, 4079, 0, 0, 0, 4095]];
let r = decode("a.dpx", &file(true, 3, 1, Element { descriptor: 50, bits: 12, packing: 0 }, 0, &packed(&line, 12, true))).unwrap();
assert_eq!(r.rgba, [255, 0, 128, 255, 1, 254, 0, 255, 0, 0, 255, 255]);
}
#[test]
fn ycbcr_descriptors_convert_to_rgb() {
// 8-bit CbYCrY, video range, BT.709 (colorimetric 6): black, white, then a red pixel pair
// (the 709 code triple of red is rounded, hence green 1)
let mut f = file(true, 4, 1, Element { descriptor: 100, bits: 8, packing: 0 }, 0, &[128, 16, 128, 235, 102, 63, 240, 63]);
f[ELEMENT + 22] = 6;
let r = decode("a.dpx", &f).unwrap();
assert_eq!(r.rgba, [0, 0, 0, 255, 255, 255, 255, 255, 255, 1, 0, 255, 255, 1, 0, 255]);
assert!(!r.has_alpha);
// red in BT.601 (colorimetric 7): the 601 code triple, rounded
let mut f = file(true, 2, 1, Element { descriptor: 100, bits: 8, packing: 0 }, 0, &[90, 81, 240, 81]);
f[ELEMENT + 22] = 7;
assert_eq!(decode("a.dpx", &f).unwrap().rgba, [254, 0, 0, 255, 254, 0, 0, 255]);
// 10-bit CbYCr filled (method A), full range from the reference codes: mid grey
let word = |a: u32, b: u32, c: u32| ((a << 22) | (b << 12) | (c << 2)).to_be_bytes();
let mut f = file(true, 1, 1, Element { descriptor: 102, bits: 10, packing: 1 }, 0, &word(512, 512, 512));
f[ELEMENT + 4..ELEMENT + 8].copy_from_slice(&0u32.to_be_bytes());
f[ELEMENT + 12..ELEMENT + 16].copy_from_slice(&1023u32.to_be_bytes());
assert_eq!(decode("a.dpx", &f).unwrap().rgba, [128, 128, 128, 255]);
// 16-bit CbYCrA: white at half opacity
let v = |x: u16| x.to_be_bytes();
let data: Vec<u8> = [v(32768), v(60160), v(32768), v(32768)].concat();
let r = decode("a.dpx", &file(true, 1, 1, Element { descriptor: 103, bits: 16, packing: 0 }, 0, &data)).unwrap();
assert_eq!(r.rgba, [255, 255, 255, 128]);
assert!(r.has_alpha);
// 8-bit CbYACrYA, 3 pixels: the last pixel has no Cr and is neutral
let r = decode("a.dpx", &file(true, 3, 1, Element { descriptor: 101, bits: 8, packing: 0 }, 0, &[128, 235, 255, 128, 16, 0, 128, 235, 255, 0, 0, 0]))
.unwrap();
assert_eq!(r.rgba, [255, 255, 255, 255, 0, 0, 0, 0, 255, 255, 255, 255]);
assert!(r.has_alpha);
}
#[test]
fn hostile_headers_fail_cleanly() {
// huge dimensions with no data, truncated data, unsupported layouts
assert!(decode("a.dpx", &file(true, u32::MAX, u32::MAX, Element { descriptor: 50, bits: 10, packing: 1 }, 0, &[])).is_err());
assert!(decode("a.dpx", &file(true, 4096, 4096, Element { descriptor: 50, bits: 10, packing: 1 }, 0, &[0; 64])).is_err());
assert!(decode("a.dpx", &file(true, 2, 2, Element { descriptor: 50, bits: 10, packing: 1 }, 0, &[0; 12])).is_err());
assert!(decode("a.dpx", &file(true, 1, 1, Element { descriptor: 150, bits: 8, packing: 0 }, 0, &[0; 4])).is_err());
assert!(decode("a.dpx", &file(true, 1, 1, Element { descriptor: 50, bits: 10, packing: 3 }, 0, &[0; 4])).is_err());
assert!(decode("a.dpx", &file(true, 1, 1, Element { descriptor: 50, bits: 16, packing: 0 }, 0, &[0; 4])).is_err());
assert!(decode("a.dpx", &file(true, 3, 3, Element { descriptor: 100, bits: 12, packing: 0 }, 0, &[0; 20])).is_err());
assert!(decode("a.dpx", &file(true, 1, 1, Element { descriptor: 50, bits: 32, packing: 0 }, 0, &[0; 16])).is_err());
assert!(decode("a.dpx", &file(true, 1, 1, Element { descriptor: 50, bits: 8, packing: 0 }, 5, &[0; 4])).is_err());
assert!(decode("a.dpx", &file(true, 0, 1, Element { descriptor: 50, bits: 8, packing: 0 }, 0, &[0; 4])).is_err());
assert!(decode("a.dpx", b"SDPX").is_err());
let mut f = file(true, 1, 1, Element { descriptor: 50, bits: 8, packing: 0 }, 0, &[0; 4]);
f[4..8].copy_from_slice(&u32::MAX.to_be_bytes());
assert!(decode("a.dpx", &f).is_err());
let mut f = file(true, 1, 1, Element { descriptor: 50, bits: 8, packing: 0 }, 0, &[0; 4]);
f[ELEMENT + 32..ELEMENT + 36].copy_from_slice(&(u32::MAX - 1).to_be_bytes());
assert!(decode("a.dpx", &file(true, 1, 2, Element { descriptor: 50, bits: 8, packing: 0 }, 0, &[0; 4])).is_err());
assert!(decode("a.dpx", &f).is_ok());
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.