Files
effectcraft/crates/model/src/scene.rs
Dylan M. Taylor 92274ec914 Merge remote-tracking branch 'origin/main' into codex/778-effect-migration
# Conflicts:
#	crates/aep/src/container.rs
#	crates/aep/src/container/footage.rs
#	crates/aep/tests/it/container/robustness.rs
#	crates/model/src/fbx.rs
#	crates/model/src/gltf.rs
#	crates/model/src/obj.rs
2026-11-13 02:26:44 +00:00

460 lines
20 KiB
Rust

//! A `craft-mesh` scene (glTF, OBJ, STL or FBX, read there) as a [`Model`]: one primitive per
//! part with one index per vertex, decoded textures, and the normals and tangents the renderer
//! needs where the file has none.
use std::collections::HashMap;
use std::sync::Arc;
use craft_mesh as cm;
use crate::{
AlphaMode, Animation, CameraProjection, Channel, ChannelPath, Interp, MAX_IMPORT_TEXTURE_PIXELS, Mat4, Material, Mesh, Model, ModelCamera, ModelError,
ModelLight, ModelLightKind, Node, Primitive, Result, Skin, TexRef, Texture, Wrap,
};
/// The bounds every reader keeps: `craft-mesh`'s defaults, with up to 2 GiB of buffers,
/// arrays and embedded images in one import.
pub(crate) fn limits() -> cm::Limits {
cm::Limits { max_data_bytes: 2 << 30, ..cm::Limits::default() }
}
pub(crate) fn error(e: cm::Error) -> ModelError {
match e {
cm::Error::Missing(name) => ModelError::Missing(name),
cm::Error::Unsupported(m) => ModelError::Unsupported(m),
cm::Error::Malformed(m) | cm::Error::TooLarge(m) => ModelError::Parse(m),
}
}
/// What a primitive without normals gets.
#[derive(Clone, Copy, PartialEq, Eq)]
pub(crate) enum MissingNormals {
/// Every triangle its own vertices and face normal (glTF 2.0 §3.7.2.1).
Flat,
/// Area-weighted vertex normals (FBX).
Smooth,
/// Smooth within an OBJ smoothing group, flat where smoothing is off.
BySmoothing,
}
/// A column-major `craft-mesh` matrix as a [`Mat4`].
pub(crate) fn mat4(m: &cm::Mat4) -> Mat4 {
let mut out = [[0.0; 4]; 4];
for (c, col) in m.as_chunks::<4>().0.iter().enumerate() {
for (r, v) in col.iter().enumerate() {
out[r][c] = *v;
}
}
Mat4(out)
}
fn wrap(w: cm::Wrap) -> Wrap {
match w {
cm::Wrap::Repeat => Wrap::Repeat,
cm::Wrap::Clamp => Wrap::Clamp,
cm::Wrap::Mirror => Wrap::Mirror,
}
}
/// The scene as a model. `image` gives the bytes of an image the scene names but does not hold
/// (OBJ, which only names its textures); an image that cannot be read or decoded leaves its
/// material untextured, with a log line.
pub(crate) fn to_model(mut scene: cm::Scene, missing: MissingNormals, image: &dyn Fn(&cm::Image) -> Option<Vec<u8>>) -> Result<Model> {
let mut warnings = std::mem::take(&mut scene.warnings);
for w in &warnings {
log::warn!("model: {w}");
}
// Images decode once; each (image, wrap) a material uses is one texture.
let mut pixels_left = MAX_IMPORT_TEXTURE_PIXELS;
let mut decoded_by_name: HashMap<String, Option<Arc<Texture>>> = HashMap::new();
let decoded: Vec<Option<Arc<Texture>>> = scene
.images
.iter()
.enumerate()
.map(|(index, im)| {
let key = image_key(im, index);
if let Some(decoded) = decoded_by_name.get(&key) {
return decoded.clone();
}
let external;
let bytes = if let Some(data) = im.data.as_deref() {
Some(data)
} else {
external = image(im);
external.as_deref()
};
let decoded = match bytes.map(|b| Texture::decode_within(b, &mut pixels_left)) {
Some(Ok(t)) => Some(Arc::new(t)),
Some(Err(e)) => {
let warning = format!("texture `{}` was left out: {e}", im.uri.as_deref().unwrap_or(&im.name));
log::warn!("model: {warning}");
warnings.push(warning);
None
}
None => {
let warning = format!("texture `{}` was not found next to the model", im.uri.as_deref().unwrap_or(&im.name));
log::warn!("model: {warning}");
warnings.push(warning);
None
}
};
decoded_by_name.insert(key, decoded.clone());
decoded
})
.collect();
let mut textures: Vec<Arc<Texture>> = vec![];
let mut texture_of: HashMap<(String, [Wrap; 2]), usize> = HashMap::new();
for texture in &scene.texture_variants {
ensure_texture(&scene, &decoded, *texture, &mut textures, &mut texture_of, &mut pixels_left, &mut warnings);
}
let mut tref = |t: Option<cm::TextureRef>| -> Option<TexRef> {
let t = t?;
let texture = ensure_texture(&scene, &decoded, t, &mut textures, &mut texture_of, &mut pixels_left, &mut warnings)?;
Some(TexRef { texture, uv_set: t.uv_set })
};
let materials: Vec<Material> = scene
.materials
.iter()
.map(|m| Material {
name: m.name.clone(),
base_color: m.base_color,
base_color_tex: tref(m.base_color_texture),
metallic: m.metallic,
roughness: m.roughness,
metallic_roughness_tex: tref(m.metallic_roughness_texture),
normal_tex: tref(m.normal_texture),
normal_scale: m.normal_scale,
occlusion_tex: tref(m.occlusion_texture),
occlusion_strength: m.occlusion_strength,
emissive: m.emissive,
emissive_tex: tref(m.emissive_texture),
alpha_mode: match m.alpha_mode {
cm::AlphaMode::Opaque => AlphaMode::Opaque,
cm::AlphaMode::Mask(_) => AlphaMode::Mask,
cm::AlphaMode::Blend => AlphaMode::Blend,
},
alpha_cutoff: if let cm::AlphaMode::Mask(c) = m.alpha_mode { c } else { 0.5 },
double_sided: m.double_sided,
unlit: m.unlit,
})
.collect();
let mut adapter_bytes = 0u64;
let meshes = scene.meshes.iter().map(|m| mesh(m, &materials, missing, &mut adapter_bytes)).collect::<Result<Vec<_>>>()?;
let nodes = scene
.nodes
.iter()
.map(|n| {
let (translation, rotation, scale, matrix) = match n.trs {
Some(t) => (t.translation, t.rotation, t.scale, None),
None => ([0.0; 3], [0.0, 0.0, 0.0, 1.0], [1.0; 3], Some(mat4(&n.transform))),
};
Node {
name: n.name.clone(),
translation,
rotation,
scale,
matrix,
mesh: n.mesh.filter(|&m| m < scene.meshes.len()),
skin: n.skin,
camera: n.camera,
light: n.light,
children: n.children.clone(),
}
})
.collect();
let skins = scene
.skins
.iter()
.map(|s| Skin {
joints: s.joints.clone(),
inverse_bind: if s.inverse_bind.is_empty() { vec![Mat4::IDENTITY; s.joints.len()] } else { s.inverse_bind.iter().map(mat4).collect() },
})
.collect();
let animations = scene
.animations
.iter()
.map(|a| Animation {
name: a.name.clone(),
channels: a
.channels
.iter()
.map(|c| Channel {
node: c.node,
path: match c.path {
cm::ChannelPath::Translation => ChannelPath::Translation,
cm::ChannelPath::Rotation => ChannelPath::Rotation,
cm::ChannelPath::Scale => ChannelPath::Scale,
},
interp: match c.interpolation {
cm::Interpolation::Step => Interp::Step,
cm::Interpolation::Linear => Interp::Linear,
cm::Interpolation::CubicSpline => Interp::CubicSpline,
},
times: c.times.clone(),
values: c.values.clone(),
})
.collect(),
})
.collect();
let name_or = |n: &str, d: String| if n.is_empty() { d } else { n.to_string() };
let cameras = scene
.cameras
.iter()
.enumerate()
.map(|(i, c)| ModelCamera {
name: name_or(&c.name, format!("Camera {}", i + 1)),
projection: match c.projection {
cm::Projection::Perspective { yfov, aspect, znear, .. } => CameraProjection::Perspective { yfov: yfov.clamp(1e-3, 3.1), aspect, znear },
cm::Projection::Orthographic { xmag, ymag, .. } => CameraProjection::Orthographic { xmag, ymag },
},
})
.collect();
let lights = scene
.lights
.iter()
.enumerate()
.map(|(i, l)| ModelLight {
name: name_or(&l.name, format!("Light {}", i + 1)),
kind: match l.kind {
cm::LightKind::Directional => ModelLightKind::Directional,
cm::LightKind::Point => ModelLightKind::Point,
cm::LightKind::Spot { inner, outer } => {
let outer = outer.clamp(1e-3, std::f64::consts::FRAC_PI_2);
ModelLightKind::Spot { inner: inner.clamp(0.0, outer), outer }
}
},
color: l.color,
intensity: l.intensity.max(0.0),
range: l.range,
})
.collect();
Ok(Model { meshes, nodes, roots: scene.roots, materials, textures, skins, animations, cameras, lights, warnings })
}
fn image_key(image: &cm::Image, index: usize) -> String {
image.uri.as_deref().or_else(|| (!image.name.is_empty()).then_some(image.name.as_str())).map(str::to_string).unwrap_or_else(|| format!("image:{index}"))
}
fn ensure_texture(
scene: &cm::Scene,
decoded: &[Option<Arc<Texture>>],
reference: cm::TextureRef,
textures: &mut Vec<Arc<Texture>>,
texture_of: &mut HashMap<(String, [Wrap; 2]), usize>,
pixels_left: &mut u64,
warnings: &mut Vec<String>,
) -> Option<usize> {
let image = decoded.get(reference.image)?.as_ref()?;
let wrap_mode = reference.wrap.map(wrap);
let key = (image_key(scene.images.get(reference.image)?, reference.image), wrap_mode);
if let Some(&index) = texture_of.get(&key) {
return Some(index);
}
if image.wrap != wrap_mode {
let cost = (image.width as u64).checked_mul(image.height as u64);
let Some(cost) = cost.filter(|&cost| cost <= *pixels_left) else {
let source = scene.images.get(reference.image)?;
let warning = format!("texture `{}` wrap variant exceeds the model texture pixel limit", source.uri.as_deref().unwrap_or(&source.name));
log::warn!("model: {warning}");
warnings.push(warning);
return None;
};
*pixels_left -= cost;
textures.push(Arc::new(Texture { wrap: wrap_mode, ..(**image).clone() }));
} else {
textures.push(image.clone());
}
let index = textures.len() - 1;
texture_of.insert(key, index);
Some(index)
}
/// One primitive per part, each with one vertex per distinct corner of its triangles. Normals
/// and UVs are kept for a part when every corner of it has them; a triangle naming a vertex
/// that is not there is left out.
fn mesh(m: &cm::Mesh, materials: &[Material], missing: MissingNormals, adapter_bytes: &mut u64) -> Result<Mesh> {
let skinned = !m.joints.is_empty() && m.joints.len() == m.positions.len() && m.weights.len() == m.positions.len();
let uv_set = m.uv_sets.first();
// Include temporary hash keys, smoothing maps and the peak duplicate produced by
// flat-normal expansion.
// Account against the whole scene before building any primitive arrays.
let projected = m
.parts
.iter()
.try_fold(0u64, |sum, part| {
let has_missing = part.corners.iter().any(|c| (c.normal as usize) >= m.normals.len());
let flat = missing == MissingNormals::Flat || (missing == MissingNormals::BySmoothing && part.smoothing == 0);
let vertices = if flat && has_missing { (part.triangle_count() as u64).checked_mul(3)? } else { part.corners.len() as u64 };
let bytes_per_vertex = if missing == MissingNormals::Flat { 64 } else { 128 };
sum.checked_add(vertices.checked_mul(bytes_per_vertex)?)
})
.ok_or_else(|| ModelError::Parse("expanded mesh size overflow".into()))?;
*adapter_bytes = adapter_bytes.checked_add(projected).ok_or_else(|| ModelError::Parse("expanded mesh size overflow".into()))?;
if *adapter_bytes > (2u64 << 30) {
return Err(ModelError::Parse("expanded mesh data exceeds the 2 GiB import limit".into()));
}
let smooth = smooth_normals(m, missing);
let mut primitives = vec![];
for part in &m.parts {
let normals = part.corners.iter().any(|c| (c.normal as usize) < m.normals.len());
let tangents = part.has_tangents && m.tangents.len() == m.positions.len();
let uvs = uv_set.filter(|set| part.corners.iter().any(|c| (c.uv as usize) < set.len()));
let flat_missing = missing == MissingNormals::BySmoothing && part.smoothing == 0;
let mut authored_normals = vec![];
let mut ids: HashMap<(cm::Corner, Option<usize>), u32> = HashMap::new();
let mut p = Primitive { material: part.material.filter(|&i| i < materials.len()), ..Primitive::default() };
for (face, t) in part.triangles().enumerate() {
if t.iter().any(|c| c.position as usize >= m.positions.len()) {
continue;
}
let flat_face_normal = (normals && flat_missing).then(|| face_normal(m, t));
for c in t {
let has_normal = (c.normal as usize) < m.normals.len();
let has_uv = uvs.is_some_and(|set| (c.uv as usize) < set.len());
let key = (
cm::Corner { position: c.position, normal: if has_normal { c.normal } else { cm::NONE }, uv: if has_uv { c.uv } else { cm::NONE } },
(!has_normal && flat_face_normal.is_some()).then_some(face),
);
let next = p.positions.len() as u32;
let id = *ids.entry(key).or_insert_with(|| {
let at = c.position as usize;
p.positions.push(m.positions.get(at).copied().unwrap_or_default().map(|x| x as f32));
if normals {
let authored = m.normals.get(c.normal as usize).copied().map(|n| n.map(|x| x as f32));
let fallback = flat_face_normal.or_else(|| smooth.get(&(c.position, part.material, smooth_group(part, missing))).copied());
authored_normals.push(authored.or(fallback));
p.normals.push(authored.or(fallback).unwrap_or([0.0, 0.0, 1.0]));
} else if let Some(n) = smooth.get(&(c.position, part.material, smooth_group(part, missing))) {
p.normals.push(*n);
}
if tangents {
p.tangents.push(m.tangents.get(at).copied().unwrap_or_default().map(|x| x as f32));
}
if let Some(set) = uvs {
p.uvs.push(set.get(c.uv as usize).copied().unwrap_or_default());
}
if skinned {
p.joints.push(m.joints.get(at).copied().unwrap_or_default());
p.weights.push(m.weights.get(at).copied().unwrap_or_default());
}
next
});
p.indices.push(id);
}
}
if p.indices.is_empty() {
continue;
}
if normals && authored_normals.iter().any(Option::is_none) {
// Keep authored corner normals, and fill only absent ones from the surrounding
// triangles. The generated normals are smooth in a mixed-authorship part.
if authored_normals.iter().any(Option::is_none) {
p.compute_normals();
for (n, authored) in p.normals.iter_mut().zip(authored_normals) {
if let Some(authored) = authored {
*n = authored;
}
}
}
} else if p.normals.is_empty() {
match missing {
MissingNormals::Flat => p.flat_normals(),
MissingNormals::BySmoothing if part.smoothing == 0 => p.flat_normals(),
MissingNormals::Smooth | MissingNormals::BySmoothing => p.compute_normals(),
}
}
if p.tangents.is_empty() && p.material.is_some_and(|i| materials.get(i).is_some_and(|mat| mat.normal_tex.is_some())) {
p.compute_tangents();
}
primitives.push(p);
}
Ok(Mesh { name: m.name.clone(), primitives })
}
fn smooth_group(part: &cm::Part, missing: MissingNormals) -> u32 {
match missing {
MissingNormals::Smooth => 1,
MissingNormals::BySmoothing => part.smoothing,
MissingNormals::Flat => 0,
}
}
fn face_normal(m: &cm::Mesh, tri: [cm::Corner; 3]) -> [f32; 3] {
let [a, b, c] = tri.map(|corner| m.positions.get(corner.position as usize).copied().unwrap_or_default());
let u = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
let v = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
let n = [u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]];
let len = (n[0] * n[0] + n[1] * n[1] + n[2] * n[2]).sqrt();
if len > 0.0 { n.map(|x| (x / len) as f32) } else { [0.0, 0.0, 1.0] }
}
/// Area weighted generated normals across parts with the same material and smoothing state.
fn smooth_normals(m: &cm::Mesh, missing: MissingNormals) -> HashMap<(u32, Option<usize>, u32), [f32; 3]> {
let mut sums: HashMap<(u32, Option<usize>, u32), [f64; 3]> = HashMap::new();
if missing == MissingNormals::Flat {
return HashMap::new();
}
for part in &m.parts {
let group = smooth_group(part, missing);
if group == 0 {
continue;
}
for tri in part.triangles() {
let Some(a) = m.positions.get(tri[0].position as usize) else { continue };
let Some(b) = m.positions.get(tri[1].position as usize) else { continue };
let Some(c) = m.positions.get(tri[2].position as usize) else { continue };
let u = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
let v = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
let face = [u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]];
for corner in tri {
if (corner.normal as usize) < m.normals.len() {
continue;
}
let n = sums.entry((corner.position, part.material, group)).or_default();
for i in 0..3 {
n[i] += face[i];
}
}
}
}
sums.into_iter()
.map(|(key, n)| {
let len = (n[0] * n[0] + n[1] * n[1] + n[2] * n[2]).sqrt();
let n = if len > 0.0 { n.map(|x| (x / len) as f32) } else { [0.0, 0.0, 1.0] };
(key, n)
})
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn wrap_variants_share_and_charge_the_import_pixel_budget() {
let scene = cm::Scene { images: vec![cm::Image { name: "texture.png".into(), ..cm::Image::default() }], ..cm::Scene::default() };
let texture = Arc::new(Texture { width: 2, height: 2, data: vec![[1.0; 4]; 4], wrap: [Wrap::Repeat; 2] });
let decoded = vec![Some(texture)];
let mut textures = vec![];
let mut texture_of = HashMap::new();
// The decoded image has already taken four pixels from this budget.
let mut pixels_left = 4;
let mut warnings = vec![];
let clamped = cm::TextureRef { image: 0, uv_set: 0, wrap: [cm::Wrap::Clamp; 2] };
let first = ensure_texture(&scene, &decoded, clamped, &mut textures, &mut texture_of, &mut pixels_left, &mut warnings).unwrap();
let shared = ensure_texture(&scene, &decoded, clamped, &mut textures, &mut texture_of, &mut pixels_left, &mut warnings).unwrap();
assert_eq!(first, shared);
assert_eq!(pixels_left, 0);
let repeated = cm::TextureRef { wrap: [cm::Wrap::Repeat; 2], ..clamped };
assert!(ensure_texture(&scene, &decoded, repeated, &mut textures, &mut texture_of, &mut pixels_left, &mut warnings).is_some());
assert_eq!(pixels_left, 0);
let mirrored = cm::TextureRef { wrap: [cm::Wrap::Mirror; 2], ..clamped };
assert!(ensure_texture(&scene, &decoded, mirrored, &mut textures, &mut texture_of, &mut pixels_left, &mut warnings).is_none());
assert_eq!(textures.len(), 2);
assert_eq!(warnings.len(), 1);
}
}