665bfac0b339
channels3d.rs
//! Auxiliary (3D) channels that travel with a layer's pixels: depth, object / material IDs,
//! surface normals, texture UVs, coverage and Cryptomatte ID/coverage pairs.
//!
//! They come from multi-layer OpenEXR footage (any channel by its full `layer.channel` name)
//! or from the compositor's own render passes for precomps of 3D comps. The 3D Channel effects
//! read them through `EffectHost::aux`.
//!
//! Conventions (shared by the EXR reader and the render pass):
//!
//! * channel planes are row-major `width × height` `f32`s covering the layer's source rectangle,
//! with `scale` aux pixels per layer pixel;
//! * depth is camera-space distance in pixels (`Z`), background `BACKGROUND_DEPTH`;
//! * `ObjectID` / `MaterialID` are small integers (0 = background);
//! * Cryptomatte layers follow the published Cryptomatte specification (Psyop, 2015): a layer
//! named `CryptoObject` stores rank pairs in `CryptoObject00.R/G/B/A`, `CryptoObject01.R/…`
//! (ID float, coverage, ID float, coverage, …), IDs are MurmurHash3 (x86, 32-bit, seed 0) of
//! the object name reinterpreted as a float with the exponent nudged off 0 and 255, and the
//! manifest maps names to hashes.
/// Depth written where nothing was rendered.
pub const BACKGROUND_DEPTH: f32 = 1.0e10;
#[derive(Clone, Debug, Default, PartialEq)]
pub struct AuxChannels {
pub width: u32,
pub height: u32,
/// Aux pixels per layer pixel.
pub scale: f64,
/// Named planes (`Z`, `ObjectID`, `CryptoObject00.R`, …).
pub channels: Vec<(String, Vec<f32>)>,
/// Cryptomatte manifests: (layer name, [(object name, hash)]).
pub manifests: Vec<(String, Vec<(String, u32)>)>,
}
impl AuxChannels {
pub fn new(width: u32, height: u32, scale: f64) -> AuxChannels {
AuxChannels { width, height, scale, channels: vec![], manifests: vec![] }
}
/// A channel by exact name (case-insensitive).
pub fn get(&self, name: &str) -> Option<&[f32]> {
self.channels.iter().find(|(n, _)| n.eq_ignore_ascii_case(name)).map(|(_, v)| v.as_slice())
}
/// The first channel present among `names` (also matching `*.name` suffixes, so `Z` finds
/// `depth.Z`).
pub fn find(&self, names: &[&str]) -> Option<&[f32]> {
for n in names {
if let Some(v) = self.get(n) {
return Some(v);
}
}
for n in names {
let suffix = format!(".{}", n.to_ascii_lowercase());
if let Some((_, v)) = self.channels.iter().find(|(c, _)| c.to_ascii_lowercase().ends_with(&suffix)) {
return Some(v);
}
}
None
}
pub fn names(&self) -> Vec<&str> {
self.channels.iter().map(|(n, _)| n.as_str()).collect()
}
/// The layers of the channels (OpenEXR layers: the name before the last `.`; `""` for the
/// unnamed layer), in channel order.
pub fn layers(&self) -> Vec<&str> {
craft_exr::channels::layers(self.channels.iter().map(|(n, _)| n.as_str()))
}
/// A layer's channels as the names to show in red, green, blue and alpha (`""` = none):
/// its R, G, B, A channels (or red / green / blue / alpha, X / Y / Z, U / V); a layer of one
/// channel (depth, an ID) shows it in all three colours.
pub fn layer_rgba(&self, layer: &str) -> [String; 4] {
craft_exr::channels::layer_rgba(self.channels.iter().map(|(n, _)| n.as_str()), layer)
.map(|i| i.and_then(|i| self.channels.get(i)).map_or(String::new(), |(n, _)| n.clone()))
}
}
pub use craft_exr::channels::split_channel;
impl AuxChannels {
pub fn depth(&self) -> Option<&[f32]> {
self.find(&["Z", "depth", "Depth", "zDepth", "Z-Depth"])
}
pub fn object_id(&self) -> Option<&[f32]> {
self.find(&["ObjectID", "object_id", "objectId", "id"])
}
pub fn material_id(&self) -> Option<&[f32]> {
self.find(&["MaterialID", "material_id", "materialId"])
}
pub fn coverage(&self) -> Option<&[f32]> {
self.find(&["Coverage", "coverage"])
}
/// Cryptomatte layer names present (prefixes with a `00.R` channel).
pub fn crypto_layers(&self) -> Vec<String> {
let mut v: Vec<String> =
self.channels.iter().filter_map(|(n, _)| n.strip_suffix("00.R").or_else(|| n.strip_suffix("00.r")).map(str::to_string)).collect();
v.sort();
v.dedup();
v
}
/// The rank planes of Cryptomatte layer `layer`, in rank order: (ID plane, coverage plane)
/// for `layer00.R/G`, `layer00.B/A`, `layer01.R/G`, ... Resolve them once per evaluation and
/// index them per pixel; looking the channels up by name for every pixel is what made the
/// effect slow.
pub fn crypto_rank_planes(&self, layer: &str) -> Vec<(&[f32], &[f32])> {
let mut out = vec![];
for k in 0.. {
let (r, g, b, a) = (self.rank(layer, k, 'R'), self.rank(layer, k, 'G'), self.rank(layer, k, 'B'), self.rank(layer, k, 'A'));
let (Some(r), Some(g)) = (r, g) else { break };
out.push((r, g));
if let (Some(b), Some(a)) = (b, a) {
out.push((b, a));
}
}
out
}
/// The plane `{layer}{k:02}.{comp}`: the layer name matches case-sensitively (layers
/// `Crypto_A` and `crypto_a` are different layers), the component letter either case.
fn rank(&self, layer: &str, k: usize, comp: char) -> Option<&[f32]> {
let tail = format!("{k:02}.{comp}");
self.channels.iter().find(|(n, _)| n.strip_prefix(layer).is_some_and(|rest| rest.eq_ignore_ascii_case(&tail))).map(|(_, v)| v.as_slice())
}
/// Rank pairs (id, coverage) of Cryptomatte layer `layer` at aux pixel index `i`. For a
/// loop over pixels, use [`AuxChannels::crypto_rank_planes`] once instead.
pub fn crypto_ranks(&self, layer: &str, i: usize) -> Vec<(f32, f32)> {
self.crypto_rank_planes(layer).iter().map(|(id, c)| (id[i], c[i])).collect()
}
/// The Cryptomatte layer an effect asking for `want` (`CryptoObject`, …) reads: an exact
/// match, else one ending in it (`ViewLayer.CryptoObject`), else the first layer.
pub fn resolve_crypto_layer(&self, want: &str) -> Option<String> {
let layers = self.crypto_layers();
layers.iter().find(|l| l.as_str() == want || l.ends_with(want)).or(layers.first()).cloned()
}
/// [`AuxChannels::resolve_crypto_layer`] with a layer named in full first: the layer called
/// exactly `name` when it is not empty and the footage has it (`Crypto_Material`, a name an
/// imported After Effects project carries), else the layer for `want`.
/// The name as given is tried first (EXR channel names may carry spaces), then trimmed.
pub fn resolve_crypto_layer_named(&self, name: &str, want: &str) -> Option<String> {
let layers = self.crypto_layers();
for name in [name, name.trim()] {
if !name.is_empty() && layers.iter().any(|l| l == name) {
return Some(name.to_string());
}
}
self.resolve_crypto_layer(want)
}
/// The ID (its hash, `f32::to_bits`) with the most coverage at aux pixel `i` of Cryptomatte
/// layer `layer`, summed over the ranks it appears in. Ties go to the lower rank; IDs with
/// no positive coverage don't count. `None` when nothing covers the pixel.
pub fn crypto_id_at(&self, layer: &str, i: usize) -> Option<u32> {
let mut ids: Vec<(u32, f32)> = vec![];
for (id, cov) in self.crypto_rank_planes(layer) {
let (Some(id), Some(&c)) = (id.get(i), cov.get(i)) else { continue };
if c > 0.0 {
match ids.iter_mut().find(|(h, _)| *h == id.to_bits()) {
Some((_, sum)) => *sum += c,
None => ids.push((id.to_bits(), c)),
}
}
}
// `min_by` keeps the first of equal elements: a tie goes to the lower rank.
ids.into_iter().min_by(|a, b| b.1.total_cmp(&a.1)).map(|(h, _)| h)
}
/// Aux pixel index of a layer-space point (nearest; `None` outside).
#[inline]
pub fn index_at(&self, lx: f64, ly: f64) -> Option<usize> {
let x = (lx * self.scale).floor();
let y = (ly * self.scale).floor();
if x < 0.0 || y < 0.0 || x >= self.width as f64 || y >= self.height as f64 {
return None;
}
Some(y as usize * self.width as usize + x as usize)
}
/// Manifest entry name for a hash in Cryptomatte layer `layer`.
pub fn manifest_name(&self, layer: &str, hash: u32) -> Option<&str> {
self.manifests.iter().find(|(l, _)| l == layer)?.1.iter().find(|(_, h)| *h == hash).map(|(n, _)| n.as_str())
}
}
pub use craft_exr::cryptomatte::{hash as crypto_hash, murmur3_32};
/// The ID float stored in Cryptomatte channels for a hash.
pub fn crypto_float(hash: u32) -> f32 {
f32::from_bits(hash)
}
#[cfg(test)]
mod tests {
use super::*;
/// The picked ID: most coverage (summed over ranks), ties to the lower rank, nothing when
/// no rank covers the pixel; layers resolve as the Cryptomatte effect does.
#[test]
fn crypto_id_at_takes_the_top_coverage_and_layers_resolve_by_suffix() {
let mut a = AuxChannels::new(4, 1, 1.0);
let f = |n: &str| crypto_float(crypto_hash(n));
let (x, y, z) = (f("x"), f("y"), f("z"));
for (c, v) in [("R", [x, x, x, x]), ("G", [0.3, 0.5, 0.0, 0.2]), ("B", [y, y, y, y]), ("A", [0.6, 0.5, 0.0, 0.3])] {
a.channels.push((format!("ViewLayer.CryptoObject00.{c}"), v.to_vec()));
}
for (c, v) in [("R", [z, z, z, x]), ("G", [0.1, 0.0, -1.0, 0.2])] {
a.channels.push((format!("ViewLayer.CryptoObject01.{c}"), v.to_vec()));
}
a.channels.push(("Other00.R".into(), vec![0.0; 4]));
let l = a.resolve_crypto_layer("CryptoObject").unwrap();
assert_eq!(l, "ViewLayer.CryptoObject");
assert_eq!(a.resolve_crypto_layer("CryptoMaterial").as_deref(), Some("Other"), "falls back to the first");
let at = |i| a.crypto_id_at(&l, i);
assert_eq!([at(0), at(1), at(2), at(3), at(9)], [Some(crypto_hash("y")), Some(crypto_hash("x")), None, Some(crypto_hash("x")), None]);
assert_eq!(AuxChannels::new(1, 1, 1.0).resolve_crypto_layer("CryptoObject"), None);
// A layer named in full wins; an empty or missing name falls back to `want`.
assert_eq!(a.resolve_crypto_layer_named("Other", "CryptoObject").as_deref(), Some("Other"));
assert_eq!(a.resolve_crypto_layer_named(" Other ", "CryptoObject").as_deref(), Some("Other"));
assert_eq!(a.resolve_crypto_layer_named("", "CryptoObject").as_deref(), Some("ViewLayer.CryptoObject"));
assert_eq!(a.resolve_crypto_layer_named("Crypto_Name", "CryptoObject").as_deref(), Some("ViewLayer.CryptoObject"));
assert_eq!(AuxChannels::new(1, 1, 1.0).resolve_crypto_layer_named("Other", "CryptoObject"), None);
// A layer whose name ends in a space is matched as named, before the trimmed name.
let mut b = AuxChannels::new(1, 1, 1.0);
for l in ["Mat", "Mat "] {
b.channels.push((format!("{l}00.R"), vec![0.0]));
}
assert_eq!(b.resolve_crypto_layer_named("Mat ", "CryptoObject").as_deref(), Some("Mat "));
assert_eq!(b.resolve_crypto_layer_named(" Mat", "CryptoObject").as_deref(), Some("Mat"));
}
#[test]
fn murmur3_reference_values() {
// Published MurmurHash3_x86_32 test vectors.
assert_eq!(murmur3_32(b"", 0), 0);
assert_eq!(murmur3_32(b"", 1), 0x514e_28b7);
assert_eq!(murmur3_32(b"", 0xffff_ffff), 0x81f1_6f39);
assert_eq!(murmur3_32(&[0, 0, 0, 0], 0), 0x2362_f9de);
assert_eq!(murmur3_32(b"a", 0x9747_b28c), 0x7fa0_9ea6);
assert_eq!(murmur3_32(b"aaaa", 0x9747_b28c), 0x5a97_808a);
assert_eq!(murmur3_32(b"Hello, world!", 0x9747_b28c), 0x2488_4cba);
assert_eq!(murmur3_32(b"The quick brown fox jumps over the lazy dog", 0x9747_b28c), 0x2fa8_26cd);
}
#[test]
fn crypto_floats_are_normal_and_round_trip() {
for n in ["bunny", "set", "ground", "a", ""] {
let h = crypto_hash(n);
let f = crypto_float(h);
assert!(f.is_finite() && (f == 0.0 || f.is_normal() || f.abs() > 0.0), "{n}");
assert_eq!(f.to_bits(), h);
}
}
#[test]
fn lookup_helpers() {
let mut a = AuxChannels::new(2, 1, 1.0);
a.channels.push(("depth.Z".into(), vec![5.0, 6.0]));
a.channels.push(("CryptoObject00.R".into(), vec![1.0, 2.0]));
a.channels.push(("CryptoObject00.G".into(), vec![0.5, 1.0]));
assert_eq!(a.depth(), Some(&[5.0, 6.0][..]));
assert_eq!(a.crypto_layers(), vec!["CryptoObject".to_string()]);
assert_eq!(a.crypto_ranks("CryptoObject", 0), vec![(1.0, 0.5)]);
assert_eq!(a.index_at(1.5, 0.2), Some(1));
assert_eq!(a.index_at(2.5, 0.2), None);
}
/// The rank planes come in rank order (00.R/G, 00.B/A, 01.R/G, ...), match lowercase channel
/// names as Blender writes them, stop at the first missing rank and agree with
/// `crypto_ranks` at every pixel.
#[test]
fn crypto_rank_planes_resolve_ranks_in_order() {
let mut a = AuxChannels::new(2, 1, 1.0);
for (n, v) in [
("00.r", [1.0, 2.0]),
("00.g", [0.5, 0.6]),
("00.b", [3.0, 4.0]),
("00.a", [0.25, 0.3]),
("01.R", [5.0, 6.0]),
("01.G", [0.1, 0.2]),
("03.R", [9.0, 9.0]),
("03.G", [1.0, 1.0]),
] {
a.channels.push((format!("CryptoMaterial{n}"), v.to_vec()));
}
let planes = a.crypto_rank_planes("CryptoMaterial");
let ids: Vec<f32> = planes.iter().map(|(id, _)| id[1]).collect();
assert_eq!(ids, vec![2.0, 4.0, 6.0]);
for i in 0..2 {
let from_planes: Vec<(f32, f32)> = planes.iter().map(|(id, c)| (id[i], c[i])).collect();
assert_eq!(from_planes, a.crypto_ranks("CryptoMaterial", i));
}
assert!(a.crypto_rank_planes("CryptoObject").is_empty());
}
/// Layers whose names differ only in case stay separate: `Crypto_A` and `crypto_a` each read
/// their own ranks (lowercase component letters still match), and picking agrees.
#[test]
fn crypto_layers_differing_in_case_read_their_own_planes() {
let mut a = AuxChannels::new(1, 1, 1.0);
let f = |n: &str| crypto_float(crypto_hash(n));
for (n, v) in [("Crypto_A00.R", f("upper")), ("Crypto_A00.G", 1.0), ("crypto_a00.r", f("lower")), ("crypto_a00.g", 1.0)] {
a.channels.push((n.into(), vec![v]));
}
assert_eq!(a.crypto_layers(), vec!["Crypto_A".to_string(), "crypto_a".to_string()]);
assert_eq!(a.resolve_crypto_layer_named("crypto_a", "CryptoObject").as_deref(), Some("crypto_a"));
assert_eq!(a.crypto_rank_planes("crypto_a")[0].0, &[f("lower")][..]);
assert_eq!(a.crypto_rank_planes("Crypto_A")[0].0, &[f("upper")][..]);
assert_eq!(a.crypto_id_at("crypto_a", 0), Some(crypto_hash("lower")));
assert_eq!(a.crypto_id_at("Crypto_A", 0), Some(crypto_hash("upper")));
assert!(a.crypto_rank_planes("CRYPTO_A").is_empty());
}
}
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.