Formats: move EffectCraft format codecs to craft-libs

This commit is contained in:
Dylan M. Taylor committed 2026-11-12 05:33:48 +00:00
1 parent 79c42749a8
commit fd1df348c0
107 files changed
+1755 -17948

No files matched your search

+25 -944
View File
@@ -1,953 +1,34 @@
//! FBX 7.x scenes, binary and ASCII.
//!
//! Written from public descriptions of the format (the binary node-record layout, the ASCII
//! syntax, and the scene objects of the Autodesk FBX SDK documentation): no importer source was
//! read.
//!
//! - **Binary**: the `Kaydara FBX Binary` header and version, node records with 32-bit (before
//! 7.5) or 64-bit offsets, every property type (`Y C I F D L S R` and the `f d l i b` arrays,
//! zlib-compressed or not). Object names `Name\0\x01Class` become `Class::Name` as in ASCII.
//! - **ASCII**: `Key: value, value { children }` with `;` comments and `*N { a: … }` arrays.
//! - **Scene**: `Geometry` meshes (`Vertices`, `PolygonVertexIndex` polygons fan-triangulated,
//! the first `LayerElementNormal`, `LayerElementUV` and `LayerElementMaterial` with every
//! mapping and reference mode), `Model` nodes with the SDK transform (translation, rotation
//! offset and pivot, pre/post rotation, Euler rotation in its order, scaling offset and pivot,
//! scaling) and geometric transforms, `Material` (Lambert/Phong mapped onto
//! metallic-roughness), `Texture` and `Video` (embedded or relative image files), joined by
//! `Connections`. `GlobalSettings` axes turn the scene to +Y up.
//!
//! Not imported: FBX 6.x and older, animation stacks, skin deformers, blend shapes, cameras and
//! lights, NURBS and patches. Units stay the file's own (like OBJ).
//! FBX 6.x and 7.x scenes, binary and ASCII, read with `craft-mesh` (`craft_mesh::fbx`):
//! `Geometry` meshes, `Model` nodes with the SDK transform and geometric transforms, `Material`
//! (Lambert/Phong mapped onto metallic-roughness), embedded or relative `Texture` images,
//! joined by `Connections`. A root node turns the file's `GlobalSettings` axes to +Y up; units
//! stay the file's own (like OBJ). Meshes without normals get smooth ones.
use std::collections::HashMap;
use std::sync::Arc;
use crate::scene::{MissingNormals, error, limits, mat4, to_model};
use crate::{Model, ModelError, Node, Result};
use crate::obj::srgb_to_linear;
use crate::{AlphaMode, Mat4, Material, Mesh, Model, ModelError, Node, Primitive, Result, TexRef, Texture, perr, vec3};
pub use craft_mesh::fbx::BINARY_MAGIC;
/// The binary file's magic (`Kaydara FBX Binary`, two spaces, NUL, 0x1A, 0x00).
pub const BINARY_MAGIC: &[u8] = b"Kaydara FBX Binary \0\x1a\0";
/// Deepest node nesting accepted (real files nest well under 10 levels).
const MAX_DEPTH: usize = 64;
/// Largest decoded array accepted (bytes).
const MAX_ARRAY_BYTES: usize = 1 << 30;
/// Most memory one import may keep: parsed arrays as stored (8 bytes per element, whatever the
/// wire type) plus the meshes built from them (#1234).
const MAX_IMPORT_BYTES: usize = 1 << 31;
/// What is left of an import's memory budget.
struct Budget(std::cell::Cell<usize>);
impl Budget {
fn new(bytes: usize) -> Budget {
Budget(std::cell::Cell::new(bytes))
}
/// Take `bytes` (None: a size that overflowed) from the budget, or fail the import before
/// anything that large is allocated.
fn take(&self, bytes: Option<usize>, what: &str) -> Result<()> {
let left = self.0.get();
match bytes.filter(|&b| b <= left) {
Some(b) => {
self.0.set(left - b);
Ok(())
}
None => Err(perr(format!("FBX: {what} would take the import past its {} MiB memory limit", MAX_IMPORT_BYTES >> 20))),
}
}
}
/// Bytes a mesh keeps.
fn mesh_bytes(m: &Mesh) -> Option<usize> {
m.primitives.iter().try_fold(0usize, |acc, p| {
let n = p.positions.len().checked_mul(12)?.checked_add(p.normals.len().checked_mul(12)?)?.checked_add(p.uvs.len().checked_mul(8)?)?;
let n = n.checked_add(p.tangents.len().checked_mul(16)?)?.checked_add(p.joints.len().checked_mul(8)?)?.checked_add(p.weights.len().checked_mul(16)?)?;
acc.checked_add(n)?.checked_add(p.indices.len().checked_mul(4)?)
})
}
/// Bytes the values under `nodes` keep. Used for ASCII files, which hold array elements as
/// one `Prop` each and are parsed before they can be counted (the text itself bounds them).
fn value_bytes(nodes: &[FbxNode]) -> Option<usize> {
nodes.iter().try_fold(0usize, |acc, n| {
let own = n.props.iter().try_fold(0usize, |a, p| {
let extra = match p {
Prop::Ints(v) => v.len().checked_mul(8)?,
Prop::Floats(v) => v.len().checked_mul(8)?,
Prop::Str(v) => v.len(),
Prop::Bytes(v) => v.len(),
Prop::Int(_) | Prop::Float(_) => 0,
};
a.checked_add(std::mem::size_of::<Prop>())?.checked_add(extra)
})?;
acc.checked_add(own)?.checked_add(value_bytes(&n.children)?)
})
}
/// One property value of an FBX node.
#[derive(Clone, Debug, PartialEq)]
pub enum Prop {
Int(i64),
Float(f64),
Str(String),
Bytes(Vec<u8>),
Ints(Vec<i64>),
Floats(Vec<f64>),
}
impl Prop {
fn as_f64(&self) -> Option<f64> {
match self {
Prop::Int(i) => Some(*i as f64),
Prop::Float(f) => Some(*f),
_ => None,
}
}
fn as_i64(&self) -> Option<i64> {
match self {
Prop::Int(i) => Some(*i),
Prop::Float(f) if f.is_finite() => Some(*f as i64),
_ => None,
}
}
fn as_str(&self) -> Option<&str> {
match self {
Prop::Str(s) => Some(s),
_ => None,
}
}
}
/// A node of the FBX document tree (the same for binary and ASCII files).
#[derive(Clone, Debug, Default, PartialEq)]
pub struct FbxNode {
pub name: String,
pub props: Vec<Prop>,
pub children: Vec<FbxNode>,
}
impl FbxNode {
pub fn child(&self, name: &str) -> Option<&FbxNode> {
self.children.iter().find(|c| c.name == name)
}
pub fn children_named<'a>(&'a self, name: &'a str) -> impl Iterator<Item = &'a FbxNode> + 'a {
self.children.iter().filter(move |c| c.name == name)
}
fn prop(&self, i: usize) -> Option<&Prop> {
self.props.get(i)
}
fn str_at(&self, i: usize) -> Option<&str> {
self.prop(i).and_then(Prop::as_str)
}
/// The node's array as floats: a binary array property, an ASCII `a:` child, or the plain
/// value list.
pub fn floats(&self) -> Vec<f64> {
if let Some(a) = self.child("a") {
return a.floats();
}
let mut out = vec![];
for p in &self.props {
match p {
Prop::Floats(v) => out.extend_from_slice(v),
Prop::Ints(v) => out.extend(v.iter().map(|&i| i as f64)),
Prop::Int(i) => out.push(*i as f64),
Prop::Float(f) => out.push(*f),
_ => {}
}
}
out
}
/// The node's array as integers (see [`FbxNode::floats`]).
pub fn ints(&self) -> Vec<i64> {
if let Some(a) = self.child("a") {
return a.ints();
}
let mut out = vec![];
for p in &self.props {
match p {
Prop::Ints(v) => out.extend_from_slice(v),
Prop::Floats(v) => out.extend(v.iter().filter(|f| f.is_finite()).map(|&f| f as i64)),
p => out.extend(p.as_i64()),
}
}
out
}
}
/// Read an FBX file (binary or ASCII) into its top-level nodes and the file version
/// (e.g. 7400).
pub fn read(bytes: &[u8]) -> Result<(u32, Vec<FbxNode>)> {
read_within(bytes, &Budget::new(MAX_IMPORT_BYTES))
}
fn read_within(bytes: &[u8], budget: &Budget) -> Result<(u32, Vec<FbxNode>)> {
if bytes.starts_with(BINARY_MAGIC) {
read_binary(bytes, budget)
} else {
let (version, nodes) = read_ascii(&String::from_utf8_lossy(bytes))?;
budget.take(value_bytes(&nodes), "its values")?;
Ok((version, nodes))
}
}
// ---------------------------------------------------------------------------------------------
// Binary
struct Bin<'a> {
d: &'a [u8],
/// 64-bit record offsets (version 7500 and later).
wide: bool,
budget: &'a Budget,
}
impl Bin<'_> {
fn take(&self, pos: &mut usize, n: usize) -> Result<&[u8]> {
let end = pos.checked_add(n).ok_or_else(|| perr("FBX: offset overflow"))?;
let s = self.d.get(*pos..end).ok_or_else(|| perr(format!("FBX: truncated at byte {pos}")))?;
*pos = end;
Ok(s)
}
fn arr<const N: usize>(&self, pos: &mut usize) -> Result<[u8; N]> {
let s = self.take(pos, N)?;
let mut a = [0u8; N];
a.copy_from_slice(s);
Ok(a)
}
fn u32(&self, pos: &mut usize) -> Result<u32> {
Ok(u32::from_le_bytes(self.arr(pos)?))
}
fn offset(&self, pos: &mut usize) -> Result<u64> {
if self.wide { Ok(u64::from_le_bytes(self.arr(pos)?)) } else { Ok(self.u32(pos)? as u64) }
}
fn to_usize(v: u64) -> Result<usize> {
usize::try_from(v).map_err(|_| perr("FBX: offset out of range"))
}
/// Records until `end` or a null record.
fn list(&self, pos: &mut usize, end: usize, depth: usize) -> Result<Vec<FbxNode>> {
if depth > MAX_DEPTH {
return Err(perr("FBX: nodes nested too deeply"));
}
let mut out = vec![];
while *pos < end {
match self.record(pos, depth)? {
Some(n) => out.push(n),
None => break,
}
}
Ok(out)
}
/// One node record; `None` for the null record that closes a list.
fn record(&self, pos: &mut usize, depth: usize) -> Result<Option<FbxNode>> {
let start = *pos;
let end = Self::to_usize(self.offset(pos)?)?;
let nprops = self.offset(pos)?;
let plen = Self::to_usize(self.offset(pos)?)?;
let nlen = self.arr::<1>(pos)?[0] as usize;
if end == 0 && nprops == 0 && plen == 0 && nlen == 0 {
return Ok(None);
}
if end <= start || end > self.d.len() {
return Err(perr(format!("FBX: bad record end {end} at byte {start}")));
}
let name = String::from_utf8_lossy(self.take(pos, nlen)?).into_owned();
let pstart = *pos;
let pend = pstart.checked_add(plen).filter(|&e| e <= end).ok_or_else(|| perr(format!("FBX: `{name}`: property list past the record")))?;
// Every property is at least one byte, so a count above the list length is corrupt.
if nprops > plen as u64 {
return Err(perr(format!("FBX: `{name}`: {nprops} properties in {plen} bytes")));
}
let mut props = Vec::with_capacity(nprops as usize);
for _ in 0..nprops {
props.push(self.prop(pos, pend)?);
}
*pos = pend;
let children = if *pos < end { self.list(pos, end, depth + 1)? } else { vec![] };
*pos = end;
Ok(Some(FbxNode { name, props, children }))
}
fn prop(&self, pos: &mut usize, pend: usize) -> Result<Prop> {
let sub = Bin { d: self.d.get(..pend).ok_or_else(|| perr("FBX: truncated property"))?, wide: self.wide, budget: self.budget };
let t = sub.arr::<1>(pos)?[0];
Ok(match t {
b'Y' => Prop::Int(i16::from_le_bytes(sub.arr(pos)?) as i64),
b'C' => Prop::Int((sub.arr::<1>(pos)?[0] != 0) as i64),
b'I' => Prop::Int(i32::from_le_bytes(sub.arr(pos)?) as i64),
b'L' => Prop::Int(i64::from_le_bytes(sub.arr(pos)?)),
b'F' => Prop::Float(f32::from_le_bytes(sub.arr(pos)?) as f64),
b'D' => Prop::Float(f64::from_le_bytes(sub.arr(pos)?)),
b'S' => {
let n = sub.u32(pos)? as usize;
Prop::Str(object_name(sub.take(pos, n)?))
}
b'R' => {
let n = sub.u32(pos)? as usize;
Prop::Bytes(sub.take(pos, n)?.to_vec())
}
b'f' | b'd' | b'l' | b'i' | b'b' => {
let len = sub.u32(pos)? as usize;
let enc = sub.u32(pos)?;
let clen = sub.u32(pos)? as usize;
let size = match t {
b'd' | b'l' => 8,
b'f' | b'i' => 4,
_ => 1,
};
let want = len.checked_mul(size).filter(|&n| n <= MAX_ARRAY_BYTES).ok_or_else(|| perr("FBX: array too large"))?;
// Elements are kept as f64/i64 (booleans and 32-bit values widen), so the budget
// is charged for what is kept, not for the wire bytes.
sub.budget.take(len.checked_mul(8), "an array")?;
let data = sub.take(pos, clen)?;
let raw = match enc {
0 => data.to_vec(),
1 => miniz_oxide::inflate::decompress_to_vec_zlib_with_limit(data, want).map_err(|e| perr(format!("FBX: array zlib: {e:?}")))?,
e => return Err(perr(format!("FBX: unknown array encoding {e}"))),
};
let raw = raw.get(..want).ok_or_else(|| perr("FBX: array shorter than its length"))?;
match t {
b'f' => Prop::Floats(raw.as_chunks::<4>().0.iter().map(|c| f32::from_le_bytes(*c) as f64).collect()),
b'd' => Prop::Floats(raw.as_chunks::<8>().0.iter().map(|c| f64::from_le_bytes(*c)).collect()),
b'l' => Prop::Ints(raw.as_chunks::<8>().0.iter().map(|c| i64::from_le_bytes(*c)).collect()),
b'i' => Prop::Ints(raw.as_chunks::<4>().0.iter().map(|c| i32::from_le_bytes(*c) as i64).collect()),
_ => Prop::Ints(raw.iter().map(|&b| (b != 0) as i64).collect()),
}
}
t => return Err(perr(format!("FBX: unknown property type 0x{t:02x}"))),
})
}
}
/// Binary object names are `Name\0\x01Class`; ASCII writes `Class::Name`.
fn object_name(b: &[u8]) -> String {
let s = String::from_utf8_lossy(b);
match s.split_once("\0\x01") {
Some((name, class)) => format!("{class}::{name}"),
None => s.into_owned(),
}
}
fn read_binary(bytes: &[u8], budget: &Budget) -> Result<(u32, Vec<FbxNode>)> {
let mut pos = BINARY_MAGIC.len();
let version = Bin { d: bytes, wide: false, budget }.u32(&mut pos)?;
let bin = Bin { d: bytes, wide: version >= 7500, budget };
let mut nodes = vec![];
while pos < bytes.len() {
match bin.record(&mut pos, 0) {
Ok(Some(n)) => nodes.push(n),
Ok(None) => break,
// A damaged tail (footer, padding) after complete sections is ignored.
Err(_) if nodes.iter().any(|n| n.name == "Objects") => break,
Err(e) => return Err(e),
}
}
Ok((version, nodes))
}
// ---------------------------------------------------------------------------------------------
// ASCII
#[derive(Clone, Debug, PartialEq)]
enum Tok {
Key(String),
Val(Prop),
/// `*N` array length (the values follow in an `a:` child).
Count,
Comma,
Open,
Close,
}
fn tokenize(text: &str) -> Vec<Tok> {
let mut out = vec![];
let mut it = text.char_indices().peekable();
while let Some(&(i, c)) = it.peek() {
match c {
c if c.is_whitespace() => {
it.next();
}
';' => {
for (_, c) in it.by_ref() {
if c == '\n' {
break;
}
}
}
',' => {
it.next();
out.push(Tok::Comma);
}
'{' => {
it.next();
out.push(Tok::Open);
}
'}' => {
it.next();
out.push(Tok::Close);
}
'"' => {
it.next();
let start = i + 1;
let mut end = text.len();
for (j, c) in it.by_ref() {
if c == '"' {
end = j;
break;
}
}
out.push(Tok::Val(Prop::Str(text.get(start..end).unwrap_or("").replace("&quot;", "\""))));
}
_ => {
let start = i;
let mut end = text.len();
while let Some(&(j, c)) = it.peek() {
if c.is_whitespace() || matches!(c, ',' | '{' | '}' | '"' | ';' | ':') {
end = j;
break;
}
it.next();
}
let word = text.get(start..end).unwrap_or("");
if it.peek().is_some_and(|&(_, c)| c == ':') {
it.next();
out.push(Tok::Key(word.to_string()));
} else if word.starts_with('*') {
out.push(Tok::Count);
} else if let Ok(i) = word.parse::<i64>() {
out.push(Tok::Val(Prop::Int(i)));
} else if let Ok(f) = word.parse::<f64>() {
out.push(Tok::Val(Prop::Float(f)));
} else if !word.is_empty() {
out.push(Tok::Val(Prop::Str(word.to_string())));
} else {
// A stray `:` with no key.
it.next();
}
}
}
}
out
}
fn ascii_list(toks: &[Tok], i: &mut usize, depth: usize) -> Result<Vec<FbxNode>> {
if depth > MAX_DEPTH {
return Err(perr("FBX: nodes nested too deeply"));
}
let mut out = vec![];
while let Some(t) = toks.get(*i) {
*i += 1;
match t {
Tok::Close if depth > 0 => return Ok(out),
Tok::Key(name) => {
let mut node = FbxNode { name: name.clone(), ..FbxNode::default() };
loop {
match toks.get(*i) {
Some(Tok::Val(v)) => node.props.push(v.clone()),
Some(Tok::Count | Tok::Comma) => {}
_ => break,
}
*i += 1;
}
if toks.get(*i) == Some(&Tok::Open) {
*i += 1;
node.children = ascii_list(toks, i, depth + 1)?;
}
out.push(node);
}
_ => {}
}
}
Ok(out)
}
fn read_ascii(text: &str) -> Result<(u32, Vec<FbxNode>)> {
let toks = tokenize(text);
let mut i = 0;
let nodes = ascii_list(&toks, &mut i, 0)?;
let version = nodes
.iter()
.find(|n| n.name == "FBXHeaderExtension")
.and_then(|h| h.child("FBXVersion"))
.and_then(|v| v.prop(0))
.and_then(Prop::as_i64)
.and_then(|v| u32::try_from(v).ok())
.unwrap_or(0);
Ok((version, nodes))
}
// ---------------------------------------------------------------------------------------------
// Scene
/// `Properties70` entries by name (`P: name, type, label, flags, values…`).
struct Props70<'a>(HashMap<&'a str, &'a FbxNode>);
impl<'a> Props70<'a> {
fn of(node: &'a FbxNode) -> Props70<'a> {
let mut m = HashMap::new();
if let Some(p) = node.child("Properties70") {
for e in p.children_named("P") {
if let Some(name) = e.str_at(0) {
m.entry(name).or_insert(e);
}
}
}
Props70(m)
}
fn values(&self, name: &str) -> Vec<f64> {
self.0.get(name).map(|e| e.props.iter().skip(4).filter_map(Prop::as_f64).collect()).unwrap_or_default()
}
fn f(&self, name: &str) -> Option<f64> {
self.values(name).first().copied().filter(|v| v.is_finite())
}
fn v3(&self, name: &str, default: [f64; 3]) -> [f64; 3] {
match self.values(name).as_slice() {
[x, y, z, ..] if x.is_finite() && y.is_finite() && z.is_finite() => [*x, *y, *z],
_ => default,
}
}
}
/// An Euler rotation (degrees) in FBX rotation order (`eEulerXYZ` = 0 rotates about X first).
fn euler(d: [f64; 3], order: i64) -> Mat4 {
let (x, y, z) = (Mat4::rotate_x(d[0]), Mat4::rotate_y(d[1]), Mat4::rotate_z(d[2]));
match order {
1 => y * z * x,
2 => x * z * y,
3 => z * x * y,
4 => y * x * z,
5 => x * y * z,
_ => z * y * x,
}
}
fn translate(t: [f64; 3]) -> Mat4 {
Mat4::translate(vec3(t[0], t[1], t[2]))
}
/// A Model's local transform: `T · Roff · Rp · Rpre · R · Rpost⁻¹ · Rp⁻¹ · Soff · Sp · S · Sp⁻¹`.
fn model_local(p: &Props70) -> Mat4 {
let order = p.f("RotationOrder").map_or(0, |o| o as i64);
let active = p.f("RotationActive").is_some_and(|a| a != 0.0);
let (pre, post) =
if active { (euler(p.v3("PreRotation", [0.0; 3]), 0), euler(p.v3("PostRotation", [0.0; 3]), 0).transpose()) } else { (Mat4::IDENTITY, Mat4::IDENTITY) };
let rp = p.v3("RotationPivot", [0.0; 3]);
let sp = p.v3("ScalingPivot", [0.0; 3]);
let s = p.v3("Lcl Scaling", [1.0; 3]);
translate(p.v3("Lcl Translation", [0.0; 3]))
* translate(p.v3("RotationOffset", [0.0; 3]))
* translate(rp)
* pre
* euler(p.v3("Lcl Rotation", [0.0; 3]), order)
* post
* translate([-rp[0], -rp[1], -rp[2]])
* translate(p.v3("ScalingOffset", [0.0; 3]))
* translate(sp)
* Mat4::scale(vec3(s[0], s[1], s[2]))
* translate([-sp[0], -sp[1], -sp[2]])
}
/// The geometric transform of a Model (applies to its geometry, not to its children).
fn geometric(p: &Props70) -> Option<Mat4> {
let t = p.v3("GeometricTranslation", [0.0; 3]);
let r = p.v3("GeometricRotation", [0.0; 3]);
let s = p.v3("GeometricScaling", [1.0; 3]);
if t == [0.0; 3] && r == [0.0; 3] && s == [1.0; 3] {
return None;
}
Some(translate(t) * euler(r, 0) * Mat4::scale(vec3(s[0], s[1], s[2])))
}
/// The file's axis system → +Y up, +Z front, +X right.
fn axis_matrix(settings: Option<&FbxNode>) -> Mat4 {
let p = settings.map(Props70::of);
let get = |name: &str, d: f64| p.as_ref().and_then(|p| p.f(name)).unwrap_or(d);
let axis = |a: f64, s: f64| -> Option<[f64; 4]> {
let a = a as i64;
let sign = if s < 0.0 { -1.0 } else { 1.0 };
let mut v = [0.0; 4];
*v.get_mut(usize::try_from(a).ok().filter(|&a| a < 3)?)? = sign;
Some(v)
};
let (Some(right), Some(up), Some(front)) = (
axis(get("CoordAxis", 0.0), get("CoordAxisSign", 1.0)),
axis(get("UpAxis", 1.0), get("UpAxisSign", 1.0)),
axis(get("FrontAxis", 2.0), get("FrontAxisSign", 1.0)),
) else {
return Mat4::IDENTITY;
};
let m = Mat4([right, up, front, [0.0, 0.0, 0.0, 1.0]]);
// Two axes on the same file axis: not a rotation.
let used = |k: usize| right[k] != 0.0 || up[k] != 0.0 || front[k] != 0.0;
if (0..3).all(used) { m } else { Mat4::IDENTITY }
}
#[derive(Clone, Copy, PartialEq, Eq)]
enum Mapping {
PolygonVertex,
Vertex,
Polygon,
AllSame,
}
/// A geometry layer element (normals, UVs, material indices).
struct LayerData {
mapping: Mapping,
data: Vec<f64>,
index: Option<Vec<i64>>,
width: usize,
}
impl LayerData {
fn of(geom: &FbxNode, element: &str, data: &str, index: &str, width: usize) -> Option<LayerData> {
let e = geom.child(element)?;
let mapping = match e.child("MappingInformationType").and_then(|m| m.str_at(0)).unwrap_or("ByPolygonVertex") {
"ByPolygonVertex" => Mapping::PolygonVertex,
"ByVertex" | "ByVertice" | "ByControlPoint" => Mapping::Vertex,
"ByPolygon" => Mapping::Polygon,
"AllSame" => Mapping::AllSame,
_ => return None,
};
let reference = e.child("ReferenceInformationType").and_then(|m| m.str_at(0)).unwrap_or("Direct");
let index = (reference != "Direct").then(|| e.child(index).map(FbxNode::ints)).flatten();
Some(LayerData { mapping, data: e.child(data)?.floats(), index, width })
}
fn get(&self, pv: usize, v: usize, poly: usize) -> Option<&[f64]> {
let i = match self.mapping {
Mapping::PolygonVertex => pv,
Mapping::Vertex => v,
Mapping::Polygon => poly,
Mapping::AllSame => 0,
};
let j = match &self.index {
Some(ix) => usize::try_from(*ix.get(i)?).ok()?,
None => i,
};
let a = j.checked_mul(self.width)?;
self.data.get(a..a.checked_add(self.width)?)
}
}
fn f32s<const N: usize>(s: &[f64]) -> [f32; N] {
let mut a = [0.0f32; N];
for (o, v) in a.iter_mut().zip(s) {
*o = if v.is_finite() { *v as f32 } else { 0.0 };
}
a
}
/// A Mesh geometry with its polygons triangulated; `materials[k]` is the model-level material
/// index of the geometry's material slot `k`.
fn build_mesh(name: &str, geom: &FbxNode, materials: &[usize], with_normal_maps: &dyn Fn(usize) -> bool) -> Option<Mesh> {
let positions: Vec<[f32; 3]> = geom.child("Vertices")?.floats().as_chunks::<3>().0.iter().map(|c| f32s::<3>(c)).collect();
let pvi = geom.child("PolygonVertexIndex")?.ints();
let normals = LayerData::of(geom, "LayerElementNormal", "Normals", "NormalsIndex", 3);
let uvs = LayerData::of(geom, "LayerElementUV", "UV", "UVIndex", 2);
let mats = geom.child("LayerElementMaterial").and_then(|e| {
let mapping = e.child("MappingInformationType").and_then(|m| m.str_at(0)).unwrap_or("AllSame");
let ids = e.child("Materials")?.ints();
Some((mapping == "ByPolygon", ids))
});
type Key = (u32, [u32; 3], [u32; 2]);
let mut prims: Vec<(Option<usize>, Primitive, HashMap<Key, u32>, Vec<bool>)> = vec![];
let mut corners: Vec<(usize, usize)> = vec![];
let mut poly = 0usize;
for (pv, &raw) in pvi.iter().enumerate() {
// The last corner of a polygon is stored as `-index - 1`.
let (v, last) = if raw < 0 { (!raw, true) } else { (raw, false) };
corners.push((pv, usize::try_from(v).unwrap_or(usize::MAX)));
if !last {
continue;
}
let poly_corners = std::mem::take(&mut corners);
let p_index = poly;
poly += 1;
if poly_corners.len() < 3 || poly_corners.iter().any(|&(_, v)| v >= positions.len()) {
continue;
}
let slot = mats.as_ref().and_then(|(by_poly, ids)| {
let k = if *by_poly { *ids.get(p_index)? } else { *ids.first()? };
materials.get(usize::try_from(k).ok()?).copied()
});
let slot = slot.or_else(|| materials.first().copied());
let at = match prims.iter().position(|p| p.0 == slot) {
Some(i) => i,
None => {
prims.push((slot, Primitive { material: slot, ..Default::default() }, HashMap::new(), vec![]));
prims.len() - 1
}
};
let Some((_, prim, map, need)) = prims.get_mut(at) else { continue };
let mut ids = Vec::with_capacity(poly_corners.len());
for &(pv, v) in &poly_corners {
let n = normals.as_ref().and_then(|l| l.get(pv, v, p_index)).map(f32s::<3>);
let t = uvs.as_ref().and_then(|l| l.get(pv, v, p_index)).map(f32s::<2>);
let key: Key = (v as u32, n.unwrap_or([f32::NAN; 3]).map(f32::to_bits), t.unwrap_or([f32::NAN; 2]).map(f32::to_bits));
let id = *map.entry(key).or_insert_with(|| {
prim.positions.push(positions.get(v).copied().unwrap_or_default());
prim.normals.push(n.unwrap_or_default());
prim.uvs.push(t.unwrap_or_default());
need.push(n.is_none());
(prim.positions.len() - 1) as u32
});
ids.push(id);
}
for i in 2..ids.len() {
prim.indices.extend([ids[0], ids[i - 1], ids[i]]);
}
}
let mut mesh = Mesh { name: name.to_string(), primitives: vec![] };
for (_, mut p, _, need) in prims {
if p.indices.is_empty() {
continue;
}
if need.iter().any(|&b| b) {
let given = p.normals.clone();
p.compute_normals();
for ((n, g), need) in p.normals.iter_mut().zip(given).zip(&need) {
if !need {
*n = g;
}
}
}
if uvs.is_none() {
p.uvs.clear();
} else {
// FBX's v axis points up the image; textures are stored top row first.
for uv in p.uvs.iter_mut() {
uv[1] = 1.0 - uv[1];
}
}
if p.material.is_some_and(with_normal_maps) {
p.compute_tangents();
}
mesh.primitives.push(p);
}
(!mesh.primitives.is_empty()).then_some(mesh)
}
/// Lambert/Phong surface properties onto metallic-roughness.
fn material(name: &str, node: &FbxNode) -> Material {
let p = Props70::of(node);
let phong = node.child("ShadingModel").and_then(|s| s.str_at(0)).is_some_and(|s| s.eq_ignore_ascii_case("phong"));
let factor = p.f("DiffuseFactor").unwrap_or(1.0);
let d = p.v3("DiffuseColor", p.v3("Diffuse", [0.8; 3]));
let alpha = match p.f("Opacity") {
Some(o) => o,
None => {
let tc = p.v3("TransparentColor", [0.0; 3]);
1.0 - (tc[0] + tc[1] + tc[2]) / 3.0 * p.f("TransparencyFactor").unwrap_or(0.0)
}
}
.clamp(0.0, 1.0);
let lin = |c: f64| srgb_to_linear((c * factor).clamp(0.0, 1.0) as f32);
let e = p.v3("EmissiveColor", [0.0; 3]);
let ef = p.f("EmissiveFactor").unwrap_or(1.0);
let roughness = if phong {
let ns = p.f("ShininessExponent").or_else(|| p.f("Shininess")).unwrap_or(20.0).max(0.0);
(2.0 / (ns + 2.0)).sqrt() as f32
} else {
1.0
};
Material {
name: name.to_string(),
base_color: [lin(d[0]), lin(d[1]), lin(d[2]), alpha as f32],
metallic: 0.0,
roughness,
emissive: e.map(|c| srgb_to_linear((c * ef).clamp(0.0, 1.0) as f32)),
alpha_mode: if alpha < 0.999 { AlphaMode::Blend } else { AlphaMode::Opaque },
..Material::default()
}
}
/// Decode standard base64 (ASCII FBX embeds `Video` content this way); `None` on bad input.
fn base64(s: &str) -> Option<Vec<u8>> {
let mut out = Vec::with_capacity(s.len() / 4 * 3);
let (mut acc, mut bits) = (0u32, 0u32);
for c in s.bytes() {
let v = match c {
b'A'..=b'Z' => c - b'A',
b'a'..=b'z' => c - b'a' + 26,
b'0'..=b'9' => c - b'0' + 52,
b'+' => 62,
b'/' => 63,
b'=' => break,
c if c.is_ascii_whitespace() => continue,
_ => return None,
};
acc = (acc << 6) | v as u32;
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((acc >> bits) as u8);
acc &= (1 << bits) - 1;
}
}
Some(out)
}
fn short_name(full: &str) -> &str {
full.split_once("::").map_or(full, |(_, n)| n)
}
/// Parse an FBX file into a model. `resolve(uri)` reads texture files next to it.
/// Parse an FBX file; `resolve(path)` reads texture files the file names but does not embed.
pub fn parse(bytes: &[u8], resolve: &dyn Fn(&str) -> Option<Vec<u8>>) -> Result<Model> {
parse_within(bytes, resolve, MAX_IMPORT_BYTES)
}
/// [`parse`] keeping at most `limit` bytes of arrays and meshes.
fn parse_within(bytes: &[u8], resolve: &dyn Fn(&str) -> Option<Vec<u8>>, limit: usize) -> Result<Model> {
let budget = Budget::new(limit);
let (version, doc) = read_within(bytes, &budget)?;
if version != 0 && version < 7000 {
return Err(ModelError::Unsupported(format!("FBX {}.{} (only FBX 7.x files are read)", version / 1000, version % 1000 / 100)));
let limits = limits();
let doc = craft_mesh::fbx::read_document(bytes, &limits).map_err(error)?;
let mut textures = |path: &str| resolve(path);
let scene = doc.scene(&limits, &mut textures).map_err(error)?;
if scene.meshes.is_empty() {
return Err(ModelError::Parse("FBX file without meshes".into()));
}
let top = |name: &str| doc.iter().find(|n| n.name == name);
let objects = top("Objects").ok_or_else(|| perr("FBX: no Objects section"))?;
let by_id: HashMap<i64, &FbxNode> = objects.children.iter().filter_map(|o| Some((o.prop(0)?.as_i64()?, o))).collect();
let kind = |id: i64| by_id.get(&id).map(|n| n.name.as_str());
// Connections: (child, parent, property) in file order.
let mut links: Vec<(i64, i64, Option<&str>)> = vec![];
if let Some(c) = top("Connections") {
for e in c.children_named("C") {
let (Some(a), Some(b)) = (e.prop(1).and_then(Prop::as_i64), e.prop(2).and_then(Prop::as_i64)) else { continue };
links.push((a, b, e.str_at(3)));
}
let mut m = to_model(scene, MissingNormals::Smooth, &|_| None)?;
// The axes node goes first: every node index moves up by one.
for n in &mut m.nodes {
n.children.iter_mut().for_each(|c| *c += 1);
}
let model_ids: Vec<i64> = objects.children.iter().filter(|o| o.name == "Model").filter_map(|o| o.prop(0)?.as_i64()).collect();
let mut node_of: HashMap<i64, usize> = HashMap::new();
let mut nodes = vec![Node { name: "FBX axes".into(), matrix: Some(axis_matrix(top("GlobalSettings"))), ..Node::default() }];
for &id in &model_ids {
if node_of.contains_key(&id) {
continue;
}
let Some(o) = by_id.get(&id) else { continue };
let name = short_name(o.str_at(1).unwrap_or("")).to_string();
node_of.insert(id, nodes.len());
nodes.push(Node { name, matrix: Some(model_local(&Props70::of(o))), ..Node::default() });
}
// Hierarchy: the first Model→Model link is the parent; anything else hangs off the root.
let mut parent: HashMap<usize, usize> = HashMap::new();
for &(c, p, _) in &links {
if let (Some(&ci), Some(&pi)) = (node_of.get(&c), node_of.get(&p))
&& ci != pi
{
parent.entry(ci).or_insert(pi);
}
}
for i in 1..nodes.len() {
let p = parent.get(&i).copied().unwrap_or(0);
if let Some(n) = nodes.get_mut(p) {
n.children.push(i);
}
}
// Materials (in first-use order) and their textures.
let mut materials: Vec<Material> = vec![];
let mut textures: Vec<Arc<Texture>> = vec![];
let mut material_of: HashMap<i64, usize> = HashMap::new();
let mut texture_of: HashMap<i64, Option<usize>> = HashMap::new();
let mut load_texture = |tid: i64, textures: &mut Vec<Arc<Texture>>| -> Option<usize> {
if let Some(t) = texture_of.get(&tid) {
return *t;
}
let t = (|| {
let tex = by_id.get(&tid)?;
let embedded = links.iter().filter(|l| l.1 == tid && kind(l.0) == Some("Video")).find_map(|l| {
let content = by_id.get(&l.0)?.child("Content")?;
match content.props.first()? {
Prop::Bytes(b) if !b.is_empty() => Some(b.clone()),
Prop::Str(_) => {
let s: String = content.props.iter().filter_map(Prop::as_str).collect();
base64(&s).filter(|b| !b.is_empty())
}
_ => None,
}
});
let bytes = embedded.or_else(|| {
["RelativeFilename", "FileName"].iter().find_map(|k| {
let f = tex.child(k)?.str_at(0)?.replace('\\', "/");
resolve(&f).or_else(|| resolve(f.rsplit('/').next()?))
})
})?;
let t = Texture::decode(&bytes).ok()?;
textures.push(Arc::new(t));
Some(textures.len() - 1)
})();
texture_of.insert(tid, t);
t
};
let mut material_index = |mid: i64, materials: &mut Vec<Material>, textures: &mut Vec<Arc<Texture>>| -> Option<usize> {
if let Some(&m) = material_of.get(&mid) {
return Some(m);
}
let node = by_id.get(&mid)?;
let mut m = material(short_name(node.str_at(1).unwrap_or("")), node);
for &(tid, _, prop) in links.iter().filter(|l| l.1 == mid && kind(l.0) == Some("Texture")) {
let slot = match prop {
Some("DiffuseColor") => &mut m.base_color_tex,
Some("NormalMap") => &mut m.normal_tex,
Some("EmissiveColor") => &mut m.emissive_tex,
_ => continue,
};
if slot.is_none() {
*slot = load_texture(tid, textures).map(|texture| TexRef { texture, uv_set: 0 });
}
}
if m.emissive_tex.is_some() && m.emissive == [0.0; 3] {
m.emissive = [1.0; 3];
}
materials.push(m);
material_of.insert(mid, materials.len() - 1);
Some(materials.len() - 1)
};
// One mesh per Model with Mesh geometry (material slots are per Model). Models instancing the
// same geometry with the same materials share one mesh rather than each building a copy.
let mut meshes: Vec<Mesh> = vec![];
let mut mesh_of: HashMap<(i64, Vec<usize>), usize> = HashMap::new();
for &id in &model_ids {
let Some(&ni) = node_of.get(&id) else { continue };
let Some(gid) = links.iter().find(|l| l.1 == id && kind(l.0) == Some("Geometry")).map(|l| l.0) else { continue };
let Some(geom) = by_id.get(&gid) else { continue };
let mats: Vec<usize> =
links.iter().filter(|l| l.1 == id && kind(l.0) == Some("Material")).filter_map(|l| material_index(l.0, &mut materials, &mut textures)).collect();
let name = nodes.get(ni).map(|n| n.name.clone()).unwrap_or_default();
let mesh_index = match mesh_of.get(&(gid, mats.clone())) {
Some(&i) => i,
None => {
let normal_mapped: Vec<bool> = materials.iter().map(|m| m.normal_tex.is_some()).collect();
let Some(mesh) = build_mesh(&name, geom, &mats, &|m| normal_mapped.get(m).copied().unwrap_or(false)) else { continue };
budget.take(mesh_bytes(&mesh), &format!("mesh `{name}`"))?;
meshes.push(mesh);
mesh_of.insert((gid, mats), meshes.len() - 1);
meshes.len() - 1
}
};
let geo = by_id.get(&id).and_then(|o| geometric(&Props70::of(o)));
match geo {
Some(matrix) => {
nodes.push(Node { name: format!("{name} geometry"), matrix: Some(matrix), mesh: Some(mesh_index), ..Node::default() });
let gi = nodes.len() - 1;
if let Some(n) = nodes.get_mut(ni) {
n.children.push(gi);
}
}
None => {
if let Some(n) = nodes.get_mut(ni) {
n.mesh = Some(mesh_index);
}
}
}
}
if meshes.is_empty() {
return Err(perr("FBX file without meshes"));
}
Ok(Model { meshes, nodes, roots: vec![0], materials, textures, ..Model::default() })
m.skins.iter_mut().flat_map(|s| s.joints.iter_mut()).for_each(|j| *j += 1);
m.animations.iter_mut().flat_map(|a| a.channels.iter_mut()).for_each(|c| c.node += 1);
let roots = m.roots.iter().map(|r| r + 1).collect();
m.nodes.insert(0, Node { name: "FBX axes".into(), matrix: Some(mat4(&doc.axes_to_y_up())), children: roots, ..Node::default() });
m.roots = vec![0];
Ok(m)
}
#[cfg(test)]
+1 -197
View File
@@ -1,5 +1,5 @@
use super::*;
use crate::load;
use crate::{AlphaMode, load, vec3};
/// A Z-up scene: a Null parent with a mesh child (rotated, scaled, with a geometric offset)
/// holding a quad and a triangle with a material each.
@@ -131,116 +131,12 @@ fn check_scene(m: &Model) {
assert!(close(lo, [8.0, 2.0, -2.0]) && close(hi, [10.0, 4.0, 0.0]), "{lo:?} {hi:?}");
}
/// A binary FBX of the same node tree (`a:` children become typed arrays).
fn write_binary(nodes: &[FbxNode], version: u32, compress: bool) -> Vec<u8> {
fn prop(out: &mut Vec<u8>, p: &Prop, compress: bool) {
let array = |out: &mut Vec<u8>, t: u8, len: usize, raw: Vec<u8>| {
out.push(t);
out.extend((len as u32).to_le_bytes());
let data = if compress { miniz_oxide::deflate::compress_to_vec_zlib(&raw, 6) } else { raw };
out.extend((compress as u32).to_le_bytes());
out.extend((data.len() as u32).to_le_bytes());
out.extend(data);
};
match p {
Prop::Int(i) => match i32::try_from(*i) {
Ok(v) => {
out.push(b'I');
out.extend(v.to_le_bytes());
}
Err(_) => {
out.push(b'L');
out.extend(i.to_le_bytes());
}
},
Prop::Float(f) => {
out.push(b'D');
out.extend(f.to_le_bytes());
}
Prop::Str(s) => {
let s = match s.split_once("::") {
Some((class, name)) => format!("{name}\0\x01{class}"),
None => s.clone(),
};
out.push(b'S');
out.extend((s.len() as u32).to_le_bytes());
out.extend(s.as_bytes());
}
Prop::Bytes(b) => {
out.push(b'R');
out.extend((b.len() as u32).to_le_bytes());
out.extend(b);
}
Prop::Ints(v) => array(out, b'i', v.len(), v.iter().flat_map(|&i| (i as i32).to_le_bytes()).collect()),
Prop::Floats(v) => array(out, b'd', v.len(), v.iter().flat_map(|f| f.to_le_bytes()).collect()),
}
}
fn record(out: &mut Vec<u8>, n: &FbxNode, wide: bool, compress: bool) {
let w = if wide { 8 } else { 4 };
let start = out.len();
out.extend(vec![0u8; 3 * w]);
out.push(n.name.len() as u8);
out.extend(n.name.as_bytes());
let props = match n.child("a") {
Some(a) if a.props.iter().all(|p| matches!(p, Prop::Int(_))) => vec![Prop::Ints(a.ints())],
Some(a) => vec![Prop::Floats(a.floats())],
None => n.props.clone(),
};
let pstart = out.len();
for p in &props {
prop(out, p, compress);
}
let plen = out.len() - pstart;
let kids: Vec<&FbxNode> = n.children.iter().filter(|c| c.name != "a").collect();
if !kids.is_empty() {
for k in kids {
record(out, k, wide, compress);
}
out.extend(vec![0u8; 3 * w + 1]);
}
let end = out.len();
for (k, v) in [end, props.len(), plen].into_iter().enumerate() {
let at = start + k * w;
if wide {
out[at..at + 8].copy_from_slice(&(v as u64).to_le_bytes());
} else {
out[at..at + 4].copy_from_slice(&(v as u32).to_le_bytes());
}
}
}
let wide = version >= 7500;
let mut out = BINARY_MAGIC.to_vec();
out.extend(version.to_le_bytes());
for n in nodes {
record(&mut out, n, wide, compress);
}
out.extend(vec![0u8; if wide { 25 } else { 13 }]);
// Footer bytes after the closing null record.
out.extend([0xfa; 16]);
out
}
#[test]
fn ascii_fbx_scene() {
let m = load("scene.fbx", ASCII.as_bytes(), &|_| None).unwrap();
check_scene(&m);
}
#[test]
fn binary_fbx_matches_ascii() {
let (_, doc) = read(ASCII.as_bytes()).unwrap();
let ascii = parse(ASCII.as_bytes(), &|_| None).unwrap();
for (version, compress) in [(7400, false), (7400, true), (7500, true)] {
let bin = write_binary(&doc, version, compress);
let (v, nodes) = read(&bin).unwrap();
assert_eq!(v, version);
assert_eq!(nodes.iter().map(|n| n.name.as_str()).collect::<Vec<_>>(), ["FBXHeaderExtension", "GlobalSettings", "Objects", "Connections"]);
// Found by its magic even without the extension.
let m = load("scene.bin", &bin, &|_| None).unwrap();
assert_eq!(m, ascii, "version {version}, compressed {compress}");
}
}
#[test]
fn embedded_and_relative_textures() {
let png = {
@@ -291,91 +187,6 @@ fn b64(b: &[u8]) -> String {
s
}
#[test]
fn hostile_fbx_files_fail_cleanly() {
let (_, doc) = read(ASCII.as_bytes()).unwrap();
let bin = write_binary(&doc, 7500, true);
// Every truncation and every single-byte corruption returns (no panic, no runaway).
for n in 0..bin.len() {
let _ = parse(&bin[..n], &|_| None);
}
for i in 0..bin.len() {
let mut b = bin.clone();
b[i] ^= 0xff;
let _ = parse(&b, &|_| None);
}
// An array claiming 4 G elements.
let mut huge = BINARY_MAGIC.to_vec();
huge.extend(7400u32.to_le_bytes());
let body: Vec<u8> = b"d".iter().copied().chain(u32::MAX.to_le_bytes()).chain(0u32.to_le_bytes()).chain(8u32.to_le_bytes()).chain([0u8; 8]).collect();
let start = huge.len();
let end = start + 13 + 1 + body.len();
huge.extend((end as u32).to_le_bytes());
huge.extend(1u32.to_le_bytes());
huge.extend((body.len() as u32).to_le_bytes());
huge.push(1);
huge.push(b'V');
huge.extend(body);
assert!(read(&huge).is_err());
// Deep nesting, both encodings.
assert!(read("A: {".repeat(100_000).as_bytes()).is_err());
// Not an FBX scene at all, an old FBX version, and a scene without meshes.
assert!(parse(b"\x00\x01garbage", &|_| None).is_err());
let v6 = "FBXHeaderExtension: {\n FBXVersion: 6100\n}\nObjects: {\n}\n";
assert!(matches!(parse(v6.as_bytes(), &|_| None), Err(ModelError::Unsupported(_))));
assert!(parse(b"Objects: {\n Model: 1, \"Model::Empty\", \"Null\" {\n }\n}\n", &|_| None).is_err());
}
/// A version-7400 binary FBX holding one top-level node `A` with uncompressed arrays of type
/// `t` (`b'b'`, `b'i'`, `b'f'`, `b'd'`, `b'l'`) and `len` elements each.
fn binary_arrays(arrays: &[(u8, usize)]) -> Vec<u8> {
let mut props = vec![];
for &(t, len) in arrays {
let size = match t {
b'd' | b'l' => 8,
b'f' | b'i' => 4,
_ => 1,
};
props.push(t);
props.extend((len as u32).to_le_bytes());
props.extend(0u32.to_le_bytes());
props.extend(((len * size) as u32).to_le_bytes());
props.extend(std::iter::repeat_n(1u8, len * size));
}
let mut out = BINARY_MAGIC.to_vec();
out.extend(7400u32.to_le_bytes());
let end = out.len() + 13 + 1 + props.len();
out.extend((end as u32).to_le_bytes());
out.extend((arrays.len() as u32).to_le_bytes());
out.extend((props.len() as u32).to_le_bytes());
out.push(1);
out.push(b'A');
out.extend(props);
out
}
#[test]
fn fbx_arrays_are_charged_for_the_memory_they_keep() {
// A boolean array is one byte per element on the wire but eight once kept as `Prop::Ints`:
// the budget counts the eight (#1234).
let n = 10_000;
let bin = binary_arrays(&[(b'b', n)]);
assert!(read_within(&bin, &Budget::new(n * 8)).is_ok());
let e = read_within(&bin, &Budget::new(n * 8 - 1)).unwrap_err();
assert!(e.to_string().contains("memory limit"), "{e}");
// 32-bit floats widen to f64 the same way.
assert!(read_within(&binary_arrays(&[(b'f', n)]), &Budget::new(n * 4)).is_err());
// Several arrays each within the budget but not together.
let bin = binary_arrays(&[(b'i', n), (b'd', n), (b'b', n)]);
assert!(read_within(&bin, &Budget::new(n * 24)).is_ok());
assert!(read_within(&bin, &Budget::new(n * 20)).is_err());
// ASCII values count too.
let (_, doc) = read(ASCII.as_bytes()).unwrap();
let values = value_bytes(&doc).unwrap();
assert!(values > 45 * std::mem::size_of::<Prop>(), "{values}");
assert!(parse_within(ASCII.as_bytes(), &|_| None, values - 1).unwrap_err().to_string().contains("memory limit"));
}
/// [`ASCII`] with two more Models instancing its geometry: `Copy` with the same two materials,
/// `Red only` with just the first.
fn instanced_scene() -> String {
@@ -401,11 +212,4 @@ fn fbx_models_instancing_one_geometry_share_its_mesh() {
assert_eq!(mesh_of("Shape"), mesh_of("Copy"), "same geometry and materials: one mesh");
assert_ne!(mesh_of("Shape"), mesh_of("Red only"), "different materials: its own mesh");
assert_eq!(m.meshes.len(), 2);
// A budget with room for one copy of the geometry's mesh, but not three, still imports.
let one = parse(ASCII.as_bytes(), &|_| None).unwrap();
let mesh = mesh_bytes(&one.meshes[0]).unwrap();
let (_, doc) = read(instanced_scene().as_bytes()).unwrap();
let values = value_bytes(&doc).unwrap();
assert!(parse_within(instanced_scene().as_bytes(), &|_| None, values + 2 * mesh).is_ok());
assert!(parse_within(instanced_scene().as_bytes(), &|_| None, values + mesh).is_err());
}
+19 -682
View File
@@ -1,687 +1,24 @@
//! glTF 2.0 import, written from the Khronos glTF 2.0 specification.
//!
//! Supports `.gltf` (JSON with external `.bin`/image files or `data:` URIs) and `.glb` (binary
//! container: a JSON chunk and a BIN chunk). Imports the default scene's node hierarchy (TRS or
//! matrix), triangle primitives (`TRIANGLES`, `TRIANGLE_STRIP`, `TRIANGLE_FAN`) with POSITION,
//! NORMAL, TANGENT, TEXCOORD_0, JOINTS_0 and WEIGHTS_0, PBR metallic-roughness materials
//! (base colour, metallic-roughness, normal, occlusion and emissive textures; alpha modes;
//! double-sided; `KHR_materials_emissive_strength`, `KHR_materials_unlit`), embedded or
//! external PNG/JPEG images with sampler wrap modes, skins and animations (step, linear and
//! cubic-spline translation/rotation/scale), perspective and orthographic cameras, and
//! `KHR_lights_punctual` lights (directional, point, spot). Sparse accessors and morph targets
//! are ignored.
//! glTF 2.0 import (`.gltf` with external or embedded buffers, `.glb`), read with `craft-mesh`
//! (`craft_mesh::gltf`): meshes, PBR metallic-roughness materials, the node hierarchy, skins,
//! animations, cameras and `KHR_lights_punctual` lights. External buffers and images are read
//! through the caller's resolver by their percent-decoded URI. Primitives without normals get
//! flat normals (glTF 2.0 §3.7.2.1); normal-mapped ones get tangents from their UVs.
use std::{cell::Cell, sync::Arc};
use crate::scene::{MissingNormals, error, limits, to_model};
use crate::{Model, Result};
use serde_json::Value;
pub use craft_mesh::base64_decode;
pub use craft_mesh::gltf::{split_glb, uri_decode};
use crate::{
AlphaMode, Animation, Channel, ChannelPath, Interp, Mat4, Material, Mesh, Model, ModelError, Node, Primitive, Result, Skin, TexRef, Texture, Wrap, perr,
};
const GLB_MAGIC: u32 = 0x4654_6C67;
const CHUNK_JSON: u32 = 0x4E4F_534A;
const CHUNK_BIN: u32 = 0x004E_4942;
/// Split a GLB container into its JSON text and BIN chunk.
pub fn split_glb(b: &[u8]) -> Result<(&[u8], Option<&[u8]>)> {
let u32_at = |o: usize| -> Option<u32> { b.get(o..o + 4).map(|s| u32::from_le_bytes([s[0], s[1], s[2], s[3]])) };
if u32_at(0) != Some(GLB_MAGIC) {
return Err(perr("not a GLB file"));
}
if u32_at(4) != Some(2) {
return Err(ModelError::Unsupported(format!("GLB version {}", u32_at(4).unwrap_or(0))));
}
let total = (u32_at(8).unwrap_or(0) as usize).min(b.len());
let mut o = 12;
let mut json = None;
let mut bin = None;
while o + 8 <= total {
let len = u32_at(o).unwrap_or(0) as usize;
let ty = u32_at(o + 4).unwrap_or(0);
let past_end = || perr("GLB chunk runs past the end of the file");
let end = (o + 8).checked_add(len).ok_or_else(past_end)?;
let data = b.get(o + 8..end).ok_or_else(past_end)?;
match ty {
CHUNK_JSON if json.is_none() => json = Some(data),
CHUNK_BIN if bin.is_none() => bin = Some(data),
_ => {}
}
o = end;
}
Ok((json.ok_or_else(|| perr("GLB without a JSON chunk"))?, bin))
}
/// Decode standard base64 (with or without padding; whitespace ignored).
pub fn base64_decode(s: &str) -> Option<Vec<u8>> {
let mut out = Vec::with_capacity(s.len() * 3 / 4);
let mut acc = 0u32;
let mut bits = 0;
for c in s.bytes() {
let v = match c {
b'A'..=b'Z' => c - b'A',
b'a'..=b'z' => c - b'a' + 26,
b'0'..=b'9' => c - b'0' + 52,
b'+' | b'-' => 62,
b'/' | b'_' => 63,
b'=' => break,
b' ' | b'\n' | b'\r' | b'\t' => continue,
_ => return None,
} as u32;
acc = (acc << 6) | v;
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((acc >> bits) as u8);
acc &= (1 << bits) - 1;
}
}
Some(out)
}
/// Percent-decode a relative URI.
pub fn uri_decode(s: &str) -> String {
let b = s.as_bytes();
let mut out = Vec::with_capacity(b.len());
let mut i = 0;
while i < b.len() {
if b[i] == b'%'
&& i + 2 < b.len()
&& b[i + 1].is_ascii_hexdigit()
&& b[i + 2].is_ascii_hexdigit()
&& let Ok(v) = u8::from_str_radix(std::str::from_utf8(&b[i + 1..i + 3]).unwrap_or("zz"), 16)
{
out.push(v);
i += 3;
continue;
}
out.push(b[i]);
i += 1;
}
String::from_utf8_lossy(&out).into_owned()
}
/// Bytes of a `data:` URI or an external resource.
fn load_uri(uri: &str, resolve: &dyn Fn(&str) -> Option<Vec<u8>>) -> Result<Vec<u8>> {
if let Some(rest) = uri.strip_prefix("data:") {
let (meta, data) = rest.split_once(',').ok_or_else(|| perr("malformed data URI"))?;
return if meta.ends_with(";base64") { base64_decode(data).ok_or_else(|| perr("bad base64 in data URI")) } else { Ok(uri_decode(data).into_bytes()) };
}
let name = uri_decode(uri);
resolve(&name).ok_or(ModelError::Missing(name))
}
struct Doc<'a> {
j: &'a Value,
buffers: Vec<Vec<u8>>,
/// Zero components that buffer-less accessors may still allocate, across the whole file:
/// nothing backs them, so many references to one capped accessor must not multiply (#2139).
zero_left: Cell<usize>,
/// Components every accessor read may still allocate, across the whole file: each primitive
/// that references an accessor keeps its own copy, so references must not multiply memory.
read_left: Cell<usize>,
/// The budget `read_left` started from, for the error message.
read_cap: usize,
}
fn arr<'v>(v: &'v Value, k: &str) -> &'v [Value] {
v.get(k).and_then(Value::as_array).map(Vec::as_slice).unwrap_or(&[])
}
/// A non-negative integer field; one too large for `usize` counts as absent (#1235).
fn idx(v: &Value, k: &str) -> Option<usize> {
v.get(k).and_then(Value::as_u64).and_then(|x| usize::try_from(x).ok())
}
/// Node indices in an array field (out-of-range ones are dropped).
fn indices(v: &Value, k: &str) -> Vec<usize> {
arr(v, k).iter().filter_map(Value::as_u64).filter_map(|c| usize::try_from(c).ok()).collect()
}
/// The most components accessors without a buffer view (all zeros) may have, together: nothing
/// in the file backs their counts, so they are capped instead of checked against a buffer
/// (#1235, #2139).
const MAX_ZERO_COMPONENTS: usize = 1 << 24;
/// The most components all accessor reads in one file may allocate together (about 1 GiB as
/// `f32`/`u32`). Each primitive keeps its own copy of what it reads, so an accessor referenced
/// N times costs N times; this bounds that by a fixed amount rather than by buffer size, because
/// real assets legitimately share one vertex buffer across many primitives. A 10M-triangle scan
/// (5M vertices with position, normal, UV and tangent, 30M indices) reads about 90M.
const MAX_READ_COMPONENTS: usize = 1 << 28;
/// Where an accessor's elements lie in its buffer: `count` elements of `elem` bytes, `stride`
/// apart from `base`, all checked to be inside `buf`.
struct Span<'b> {
buf: &'b [u8],
base: usize,
stride: usize,
}
fn num(v: &Value, k: &str, d: f64) -> f64 {
v.get(k).and_then(Value::as_f64).unwrap_or(d)
}
fn nums<const N: usize>(v: &Value, k: &str, d: [f64; N]) -> [f64; N] {
let mut out = d;
if let Some(a) = v.get(k).and_then(Value::as_array) {
for (i, x) in a.iter().take(N).enumerate() {
out[i] = x.as_f64().unwrap_or(d[i]);
}
}
out
}
/// Bytes of component `c` of element `i`, with checked offsets (the span was validated, but
/// nothing derived from the file is indexed unchecked).
fn component(buf: &[u8], base: usize, stride: usize, i: usize, c: usize, csize: usize) -> Result<&[u8]> {
let o = i.checked_mul(stride).and_then(|o| o.checked_add(base)).and_then(|o| o.checked_add(c.checked_mul(csize)?));
o.and_then(|o| buf.get(o..o.checked_add(csize)?)).ok_or_else(|| perr("accessor reads past its buffer"))
}
impl Doc<'_> {
/// Charge `total` components to the file's read budget before allocating them.
fn charge(&self, total: usize) -> Result<()> {
let left = self.read_left.get();
let Some(rest) = left.checked_sub(total) else {
let cap = self.read_cap;
return Err(perr(format!("accessor reads need more than {cap} components in total ({total} requested, {left} left)")));
};
self.read_left.set(rest);
Ok(())
}
/// Charge `count` items of `per` components each.
fn charge_each(&self, count: usize, per: usize) -> Result<()> {
self.charge(count.checked_mul(per).ok_or_else(|| perr("primitive is too large"))?)
}
/// The accessor's element count and total components (`count * n`), checked; and its span in
/// the buffer, validated before anything is allocated from the count. `None` for an
/// accessor without a buffer view, whose components are all zero.
fn layout(&self, acc: &Value, n: usize, csize: usize) -> Result<(usize, usize, Option<Span<'_>>)> {
let count = match acc.get("count") {
None => 0,
Some(c) => c.as_u64().and_then(|c| usize::try_from(c).ok()).ok_or_else(|| perr("accessor count is not a valid size"))?,
};
let total = count.checked_mul(n).ok_or_else(|| perr("accessor count is too large"))?;
let Some(bv) = idx(acc, "bufferView") else {
let left = self.zero_left.get();
let Some(rest) = left.checked_sub(total) else {
return Err(perr(format!("accessors without a bufferView have more than {MAX_ZERO_COMPONENTS} components ({total} requested, {left} left)")));
};
self.zero_left.set(rest);
self.charge(total)?;
return Ok((count, total, None));
};
let view = arr(self.j, "bufferViews").get(bv).ok_or_else(|| perr(format!("no bufferView {bv}")))?;
let buf = self.buffers.get(idx(view, "buffer").unwrap_or(0)).ok_or_else(|| perr("bufferView buffer out of range"))?;
let past = || perr("accessor reads past its buffer");
let base = idx(view, "byteOffset").unwrap_or(0).checked_add(idx(acc, "byteOffset").unwrap_or(0)).ok_or_else(past)?;
let elem = csize.checked_mul(n).ok_or_else(past)?;
let stride = idx(view, "byteStride").filter(|s| *s > 0).unwrap_or(elem);
if stride < elem {
return Err(perr(format!("bufferView byteStride {stride} is smaller than its {elem}-byte elements")));
}
if count > 0 {
let end = (count - 1).checked_mul(stride).and_then(|o| o.checked_add(base)).and_then(|o| o.checked_add(elem)).ok_or_else(past)?;
if end > buf.len() {
return Err(past());
}
}
self.charge(total)?;
Ok((count, total, Some(Span { buf, base, stride })))
}
/// An accessor as `f32` rows of `n` components (normalised integers mapped to 0..1 / -1..1).
fn floats(&self, a: usize) -> Result<(Vec<f32>, usize)> {
let acc = arr(self.j, "accessors").get(a).ok_or_else(|| perr(format!("no accessor {a}")))?;
let n = match acc.get("type").and_then(Value::as_str).unwrap_or("") {
"SCALAR" => 1,
"VEC2" => 2,
"VEC3" => 3,
"VEC4" => 4,
"MAT2" => 4,
"MAT3" => 9,
"MAT4" => 16,
t => return Err(perr(format!("accessor type `{t}`"))),
};
let ct = idx(acc, "componentType").unwrap_or(5126);
let norm = acc.get("normalized").and_then(Value::as_bool).unwrap_or(false);
let csize = match ct {
5120 | 5121 => 1,
5122 | 5123 => 2,
5125 | 5126 => 4,
_ => return Err(perr(format!("componentType {ct}"))),
};
let (count, total, span) = self.layout(acc, n, csize)?;
let mut out = vec![0.0f32; total];
let Some(Span { buf, base, stride }) = span else {
// No buffer view: all zeros (sparse substitution is not supported).
return Ok((out, n));
};
// Matrices of 1/2-byte components pad columns to 4 bytes; ignored (rare).
for i in 0..count {
for c in 0..n {
let s = component(buf, base, stride, i, c, csize)?;
out[i * n + c] = match ct {
5126 => f32::from_le_bytes([s[0], s[1], s[2], s[3]]),
5125 => u32::from_le_bytes([s[0], s[1], s[2], s[3]]) as f32,
5123 => {
let v = u16::from_le_bytes([s[0], s[1]]) as f32;
if norm { v / 65535.0 } else { v }
}
5122 => {
let v = i16::from_le_bytes([s[0], s[1]]) as f32;
if norm { (v / 32767.0).max(-1.0) } else { v }
}
5121 => {
let v = s[0] as f32;
if norm { v / 255.0 } else { v }
}
_ => {
let v = s[0] as i8 as f32;
if norm { (v / 127.0).max(-1.0) } else { v }
}
};
}
}
Ok((out, n))
}
/// Integer accessor (indices, joints) read exactly.
fn ints(&self, a: usize) -> Result<Vec<u32>> {
let acc = arr(self.j, "accessors").get(a).ok_or_else(|| perr(format!("no accessor {a}")))?;
let ct = idx(acc, "componentType").unwrap_or(5125);
if ct == 5126 {
return Ok(self.floats(a)?.0.into_iter().map(|v| v as u32).collect());
}
let n = match acc.get("type").and_then(Value::as_str).unwrap_or("SCALAR") {
"VEC4" => 4,
"VEC3" => 3,
"VEC2" => 2,
_ => 1,
};
let csize = match ct {
5120 | 5121 => 1,
5122 | 5123 => 2,
_ => 4,
};
let (count, total, span) = self.layout(acc, n, csize)?;
let Some(Span { buf, base, stride }) = span else { return Ok(vec![0; total]) };
let mut out = Vec::with_capacity(total);
for i in 0..count {
for c in 0..n {
let s = component(buf, base, stride, i, c, csize)?;
out.push(match csize {
1 => s[0] as u32,
2 => u16::from_le_bytes([s[0], s[1]]) as u32,
_ => u32::from_le_bytes([s[0], s[1], s[2], s[3]]),
});
}
}
Ok(out)
}
}
/// Parse a `.gltf` (JSON) or `.glb` file.
/// Parse a `.gltf` (JSON) or `.glb` file; `resolve(uri)` reads external buffers and images.
pub fn parse(bytes: &[u8], resolve: &dyn Fn(&str) -> Option<Vec<u8>>) -> Result<Model> {
parse_with_budget(bytes, resolve, MAX_READ_COMPONENTS)
}
/// [`parse`] with a read budget of `read_budget` accessor components for the whole file.
pub(crate) fn parse_with_budget(bytes: &[u8], resolve: &dyn Fn(&str) -> Option<Vec<u8>>, read_budget: usize) -> Result<Model> {
let (json, bin) = if bytes.starts_with(b"glTF") { split_glb(bytes)? } else { (bytes, None) };
let j: Value = serde_json::from_slice(json).map_err(|e| perr(format!("glTF JSON: {e}")))?;
let ver = j.get("asset").and_then(|a| a.get("version")).and_then(Value::as_str).unwrap_or("");
if !ver.starts_with('2') {
return Err(ModelError::Unsupported(format!("glTF version `{ver}` (2.0 required)")));
}
for ext in arr(&j, "extensionsRequired") {
let e = ext.as_str().unwrap_or("");
if !matches!(e, "KHR_materials_unlit" | "KHR_materials_emissive_strength") {
return Err(ModelError::Unsupported(format!("required extension {e}")));
}
}
let mut buffers = vec![];
for (i, b) in arr(&j, "buffers").iter().enumerate() {
let data = match b.get("uri").and_then(Value::as_str) {
Some(u) => load_uri(u, resolve)?,
None if i == 0 => bin.map(<[u8]>::to_vec).ok_or_else(|| perr("buffer 0 has no uri and the file has no BIN chunk"))?,
None => vec![],
};
buffers.push(data);
}
let d = Doc { j: &j, buffers, zero_left: Cell::new(MAX_ZERO_COMPONENTS), read_left: Cell::new(read_budget), read_cap: read_budget };
// Images → textures (decoded once per image; samplers set the wrap modes).
let mut images: Vec<Option<Arc<Texture>>> = vec![];
for im in arr(&j, "images") {
let data = if let Some(u) = im.get("uri").and_then(Value::as_str) {
load_uri(u, resolve).ok()
} else if let Some(bv) = idx(im, "bufferView") {
arr(&j, "bufferViews").get(bv).and_then(|v| {
let b = d.buffers.get(idx(v, "buffer").unwrap_or(0))?;
let o = idx(v, "byteOffset").unwrap_or(0);
b.get(o..o.checked_add(idx(v, "byteLength").unwrap_or(0))?).map(<[u8]>::to_vec)
})
} else {
None
};
images.push(data.and_then(|b| Texture::decode(&b).ok()).map(Arc::new));
}
let wrap = |v: u64| match v {
33071 => Wrap::Clamp,
33648 => Wrap::Mirror,
_ => Wrap::Repeat,
};
let mut textures: Vec<Arc<Texture>> = vec![];
let mut tex_map: Vec<Option<usize>> = vec![];
for t in arr(&j, "textures") {
let Some(img) = idx(t, "source").and_then(|s| images.get(s).cloned().flatten()) else {
tex_map.push(None);
continue;
};
let samp = idx(t, "sampler").and_then(|s| arr(&j, "samplers").get(s));
let ws = samp.and_then(|s| s.get("wrapS")).and_then(Value::as_u64).unwrap_or(10497);
let wt = samp.and_then(|s| s.get("wrapT")).and_then(Value::as_u64).unwrap_or(10497);
let w = [wrap(ws), wrap(wt)];
let tex = if img.wrap == w { img } else { Arc::new(Texture { wrap: w, ..(*img).clone() }) };
tex_map.push(Some(textures.len()));
textures.push(tex);
}
let tref = |v: Option<&Value>| -> Option<TexRef> {
let v = v?;
let t = tex_map.get(idx(v, "index")?).copied().flatten()?;
Some(TexRef { texture: t, uv_set: idx(v, "texCoord").unwrap_or(0) as u32 })
};
let mut materials = vec![];
for m in arr(&j, "materials") {
let pbr = m.get("pbrMetallicRoughness").cloned().unwrap_or(Value::Null);
let bc = nums(&pbr, "baseColorFactor", [1.0; 4]);
let ext = m.get("extensions");
let strength = ext.and_then(|e| e.get("KHR_materials_emissive_strength")).map_or(1.0, |e| num(e, "emissiveStrength", 1.0));
let em = nums(m, "emissiveFactor", [0.0; 3]);
materials.push(Material {
name: m.get("name").and_then(Value::as_str).unwrap_or("").to_string(),
base_color: bc.map(|v| v as f32),
base_color_tex: tref(pbr.get("baseColorTexture")),
metallic: num(&pbr, "metallicFactor", 1.0) as f32,
roughness: num(&pbr, "roughnessFactor", 1.0) as f32,
metallic_roughness_tex: tref(pbr.get("metallicRoughnessTexture")),
normal_tex: tref(m.get("normalTexture")),
normal_scale: m.get("normalTexture").map_or(1.0, |n| num(n, "scale", 1.0)) as f32,
occlusion_tex: tref(m.get("occlusionTexture")),
occlusion_strength: m.get("occlusionTexture").map_or(1.0, |n| num(n, "strength", 1.0)) as f32,
emissive: [(em[0] * strength) as f32, (em[1] * strength) as f32, (em[2] * strength) as f32],
emissive_tex: tref(m.get("emissiveTexture")),
alpha_mode: match m.get("alphaMode").and_then(Value::as_str) {
Some("MASK") => AlphaMode::Mask,
Some("BLEND") => AlphaMode::Blend,
_ => AlphaMode::Opaque,
},
alpha_cutoff: num(m, "alphaCutoff", 0.5) as f32,
double_sided: m.get("doubleSided").and_then(Value::as_bool).unwrap_or(false),
unlit: ext.and_then(|e| e.get("KHR_materials_unlit")).is_some(),
});
}
let mut meshes = vec![];
for m in arr(&j, "meshes") {
let mut mesh = Mesh { name: m.get("name").and_then(Value::as_str).unwrap_or("").to_string(), primitives: vec![] };
for p in arr(m, "primitives") {
if let Some(prim) = primitive(&d, p, &materials)? {
mesh.primitives.push(prim);
}
}
meshes.push(mesh);
}
let mut nodes = vec![];
for n in arr(&j, "nodes") {
let matrix = n.get("matrix").and_then(Value::as_array).filter(|a| a.len() == 16).map(|a| {
// Column-major in the file.
let v: Vec<f64> = a.iter().map(|x| x.as_f64().unwrap_or(0.0)).collect();
let mut m = [[0.0; 4]; 4];
for c in 0..4 {
for r in 0..4 {
m[r][c] = v[c * 4 + r];
}
}
Mat4(m)
});
nodes.push(Node {
name: n.get("name").and_then(Value::as_str).unwrap_or("").to_string(),
translation: nums(n, "translation", [0.0; 3]),
rotation: nums(n, "rotation", [0.0, 0.0, 0.0, 1.0]),
scale: nums(n, "scale", [1.0; 3]),
matrix,
mesh: idx(n, "mesh").filter(|&m| m < meshes.len()),
skin: idx(n, "skin"),
camera: idx(n, "camera"),
light: n.get("extensions").and_then(|e| e.get("KHR_lights_punctual")).and_then(|e| idx(e, "light")),
children: indices(n, "children"),
});
}
let scene = idx(&j, "scene").unwrap_or(0);
let roots: Vec<usize> = match arr(&j, "scenes").get(scene) {
Some(s) => indices(s, "nodes"),
None => {
// No scene: every node that is nobody's child.
let mut child = vec![false; nodes.len()];
for n in &nodes {
for &c in &n.children {
if c < child.len() {
child[c] = true;
}
}
}
(0..nodes.len()).filter(|&i| !child[i]).collect()
}
};
let mut skins = vec![];
for s in arr(&j, "skins") {
let joints: Vec<usize> = indices(s, "joints");
let inverse_bind = match idx(s, "inverseBindMatrices") {
Some(a) => {
let (f, _) = d.floats(a)?;
f.as_chunks::<16>()
.0
.iter()
.map(|v| {
let mut m = [[0.0; 4]; 4];
for c in 0..4 {
for r in 0..4 {
m[r][c] = v[c * 4 + r] as f64;
}
}
Mat4(m)
})
.collect()
}
None => vec![Mat4::IDENTITY; joints.len()],
};
skins.push(Skin { joints, inverse_bind });
}
let mut animations = vec![];
for a in arr(&j, "animations") {
let samplers = arr(a, "samplers");
let mut anim = Animation { name: a.get("name").and_then(Value::as_str).unwrap_or("").to_string(), channels: vec![] };
for c in arr(a, "channels") {
let Some(t) = c.get("target") else { continue };
let Some(node) = idx(t, "node") else { continue };
let path = match t.get("path").and_then(Value::as_str) {
Some("translation") => ChannelPath::Translation,
Some("rotation") => ChannelPath::Rotation,
Some("scale") => ChannelPath::Scale,
_ => continue,
};
let Some(s) = idx(c, "sampler").and_then(|s| samplers.get(s)) else { continue };
let interp = match s.get("interpolation").and_then(Value::as_str) {
Some("STEP") => Interp::Step,
Some("CUBICSPLINE") => Interp::CubicSpline,
_ => Interp::Linear,
};
let (Some(input), Some(output)) = (idx(s, "input"), idx(s, "output")) else { continue };
let (times, _) = d.floats(input)?;
let (values, _) = d.floats(output)?;
anim.channels.push(Channel { node, path, interp, times, values });
}
animations.push(anim);
}
let cameras = arr(&j, "cameras").iter().enumerate().map(|(i, c)| camera(c, i)).collect();
let lights = j
.get("extensions")
.and_then(|e| e.get("KHR_lights_punctual"))
.map(|e| arr(e, "lights").iter().enumerate().map(|(i, l)| light(l, i)).collect())
.unwrap_or_default();
Ok(Model { meshes, nodes, roots, materials, textures, skins, animations, cameras, lights })
}
fn name_or(v: &Value, d: String) -> String {
v.get("name").and_then(Value::as_str).filter(|s| !s.is_empty()).map(str::to_string).unwrap_or(d)
}
/// A glTF camera (glTF 2.0 §5.12): `perspective` {yfov, aspectRatio?, znear} or
/// `orthographic` {xmag, ymag}.
fn camera(c: &Value, i: usize) -> crate::ModelCamera {
let projection = match (c.get("type").and_then(Value::as_str), c.get("orthographic")) {
(Some("orthographic"), Some(o)) => crate::CameraProjection::Orthographic { xmag: num(o, "xmag", 1.0), ymag: num(o, "ymag", 1.0) },
_ => {
let p = c.get("perspective").cloned().unwrap_or(Value::Null);
crate::CameraProjection::Perspective {
yfov: num(&p, "yfov", 0.8).clamp(1e-3, 3.1),
aspect: p.get("aspectRatio").and_then(Value::as_f64),
znear: num(&p, "znear", 0.01),
}
}
};
crate::ModelCamera { name: name_or(c, format!("Camera {}", i + 1)), projection }
}
/// A `KHR_lights_punctual` light: type, color, intensity, range, spot cone angles.
fn light(l: &Value, i: usize) -> crate::ModelLight {
let kind = match l.get("type").and_then(Value::as_str) {
Some("directional") => crate::ModelLightKind::Directional,
Some("spot") => {
let s = l.get("spot").cloned().unwrap_or(Value::Null);
let outer = num(&s, "outerConeAngle", std::f64::consts::FRAC_PI_4).clamp(1e-3, std::f64::consts::FRAC_PI_2);
crate::ModelLightKind::Spot { inner: num(&s, "innerConeAngle", 0.0).clamp(0.0, outer), outer }
}
_ => crate::ModelLightKind::Point,
};
crate::ModelLight {
name: name_or(l, format!("Light {}", i + 1)),
kind,
color: nums(l, "color", [1.0; 3]),
intensity: num(l, "intensity", 1.0).max(0.0),
range: l.get("range").and_then(Value::as_f64),
}
}
fn primitive(d: &Doc, p: &Value, materials: &[Material]) -> Result<Option<Primitive>> {
let mode = idx(p, "mode").unwrap_or(4);
if !matches!(mode, 4..=6) {
return Ok(None);
}
let attrs = p.get("attributes").ok_or_else(|| perr("primitive without attributes"))?;
let Some(pa) = idx(attrs, "POSITION") else { return Ok(None) };
let (pos, _) = d.floats(pa)?;
let positions: Vec<[f32; 3]> = pos.as_chunks::<3>().0.iter().map(|c| [c[0], c[1], c[2]]).collect();
let n = positions.len();
let vec3s = |a: Option<usize>| -> Result<Vec<[f32; 3]>> {
Ok(match a {
Some(a) => d.floats(a)?.0.as_chunks::<3>().0.iter().map(|c| [c[0], c[1], c[2]]).collect(),
None => vec![],
})
};
let mut normals = vec3s(idx(attrs, "NORMAL"))?;
let uvs: Vec<[f32; 2]> = match idx(attrs, "TEXCOORD_0") {
Some(a) => d.floats(a)?.0.as_chunks::<2>().0.iter().map(|c| [c[0], c[1]]).collect(),
None => vec![],
};
let tangents: Vec<[f32; 4]> = match idx(attrs, "TANGENT") {
Some(a) => d.floats(a)?.0.as_chunks::<4>().0.iter().map(|c| [c[0], c[1], c[2], c[3]]).collect(),
None => vec![],
};
let joints: Vec<[u16; 4]> = match idx(attrs, "JOINTS_0") {
Some(a) => d.ints(a)?.as_chunks::<4>().0.iter().map(|c| [c[0] as u16, c[1] as u16, c[2] as u16, c[3] as u16]).collect(),
None => vec![],
};
let weights: Vec<[f32; 4]> = match idx(attrs, "WEIGHTS_0") {
Some(a) => d.floats(a)?.0.as_chunks::<4>().0.iter().map(|c| [c[0], c[1], c[2], c[3]]).collect(),
None => vec![],
};
let raw: Vec<u32> = match idx(p, "indices") {
Some(a) => d.ints(a)?,
None => {
// Generated indices are allocated like a read, once per referencing primitive.
d.charge(n)?;
(0..n as u32).collect()
}
};
if raw.iter().any(|&i| i as usize >= n) {
return Err(perr("index out of range"));
}
let mut indices = Vec::with_capacity(raw.len());
match mode {
5 => {
for i in 2..raw.len() {
let (a, b, c) = (raw[i - 2], raw[i - 1], raw[i]);
if i % 2 == 0 { indices.extend([a, b, c]) } else { indices.extend([b, a, c]) }
}
}
6 => {
for i in 2..raw.len() {
indices.extend([raw[0], raw[i - 1], raw[i]]);
}
}
_ => indices.extend(raw.as_chunks::<3>().0.iter().flatten()),
}
// The triangle list is kept besides the raw indices (a strip or fan of k indices becomes
// 3(k-2)), so it is charged like a read.
d.charge(indices.len())?;
if normals.len() != n {
normals.clear();
}
let material = idx(p, "material").filter(|&m| m < materials.len());
let skinned = joints.len() == n && weights.len() == n;
if normals.is_empty() {
// Flat normals unshare every vertex: position and normal, plus UVs and joints/weights.
let per = 6 + if uvs.len() == n { 2 } else { 0 } + if skinned { 8 } else { 0 };
d.charge_each(indices.len(), per)?;
}
let mut prim = Primitive {
positions,
normals,
uvs: if uvs.len() == n { uvs } else { vec![] },
tangents: if tangents.len() == n { tangents } else { vec![] },
joints: if skinned { joints } else { vec![] },
weights: if skinned { weights } else { vec![] },
indices,
material,
};
if prim.normals.is_empty() {
prim.flat_normals();
prim.tangents.clear();
}
let needs_tangents = material.is_some_and(|m| materials[m].normal_tex.is_some());
if needs_tangents && prim.tangents.is_empty() {
d.charge_each(prim.positions.len(), 4)?;
prim.compute_tangents();
}
Ok(Some(prim))
}
#[cfg(test)]
mod tests {
use super::uri_decode;
#[test]
fn uri_decode_rejects_signed_hex_pair() {
assert_eq!(uri_decode("a%+1b"), "a%+1b");
assert_eq!(uri_decode("a%-1b"), "a%-1b");
assert_eq!(uri_decode("a%41b"), "aAb");
}
let mut buffers = |uri: &str| resolve(uri);
let scene = craft_mesh::gltf::read(bytes, &limits(), &mut buffers).map_err(error)?;
to_model(scene, MissingNormals::Flat, &|im| {
let uri = im.uri.as_deref()?;
match uri.strip_prefix("data:") {
Some(_) => None,
None => resolve(&uri_decode(uri)),
}
})
}
+8 -5
View File
@@ -1,12 +1,14 @@
//! 3D models for the Advanced 3D renderer.
//!
//! - [`gltf`]: glTF 2.0 import (`.gltf` with external or embedded buffers, `.glb`), written from
//! the Khronos glTF 2.0 specification: meshes, PBR metallic-roughness materials (base colour,
//! metallic-roughness, normal, occlusion and emissive maps), the node hierarchy, skins and
//! animations.
//! The file formats are read with `craft-mesh` (storytold/craft-libs); this crate maps its
//! scene onto [`Model`], decodes the textures and adds the normals and tangents a file leaves out.
//!
//! - [`gltf`]: glTF 2.0 import (`.gltf` with external or embedded buffers, `.glb`): meshes, PBR
//! metallic-roughness materials (base colour, metallic-roughness, normal, occlusion and
//! emissive maps), the node hierarchy, skins, animations, cameras and lights.
//! - [`obj`]: Wavefront OBJ geometry with MTL materials (mapped onto the metallic-roughness model).
//! - [`stl`]: STL meshes (binary and ASCII, with the binary per-facet and part colours).
//! - [`fbx`]: FBX 7.x scenes, binary and ASCII: meshes, the Model hierarchy, Lambert/Phong
//! - [`fbx`]: FBX 6.x and 7.x scenes, binary and ASCII: meshes, the Model hierarchy, Lambert/Phong
//! materials and their textures.
//! - [`prim`]: parametric primitives (cube, sphere, plane, torus, cone, cylinder).
//! - [`extrude`]: extruded, bevelled meshes from 2D outlines (text and shape layers), with
@@ -22,6 +24,7 @@ pub mod fbx;
pub mod gltf;
pub mod obj;
pub mod prim;
mod scene;
pub mod stl;
pub mod triangulate;
+16 -282
View File
@@ -1,33 +1,21 @@
//! Wavefront OBJ geometry and MTL materials.
//! Wavefront OBJ geometry and MTL materials, read with `craft-mesh` (`craft_mesh::obj`).
//!
//! OBJ: `v` (optional vertex colours ignored), `vt`, `vn`, `f` with `v`, `v/vt`, `v//vn`,
//! `v/vt/vn` references (negative = relative), polygons fan-triangulated, `o`/`g` groups, `s`
//! smoothing (normals computed per smoothing state when a face has none), `usemtl`, `mtllib`.
//!
//! MTL materials map onto metallic-roughness: `Kd` → base colour, `d`/`Tr` → alpha, `Ke` →
//! emissive, `Pr`/`Pm` (the PBR extension) → roughness/metallic, otherwise roughness from the
//! Phong exponent `Ns` (`sqrt(2 / (Ns + 2))`) and metallic 0; `map_Kd`, `map_Ke`,
//! `map_Bump`/`bump`/`norm` load base colour, emissive and normal textures.
//! The material library and the textures it names are read through the caller's resolver: a
//! texture is looked up by the name as written (a name containing spaces is one name), then by
//! its file name (an absolute path from another machine, #1274), then by the final token (the
//! options convention, `-bm 1 file.png`). Faces without normals get smooth normals within a
//! smoothing group and flat ones where smoothing is off.
use std::collections::HashMap;
use std::sync::Arc;
use crate::scene::{MissingNormals, error, limits, to_model};
use crate::{Model, Result};
use crate::{AlphaMode, Material, Mesh, Model, Primitive, Result, TexRef, Texture, perr};
pub use craft_mesh::srgb_to_linear;
/// The last component of a referenced path, treating `\` as a separator too: a path from a
/// machine of another kind (`C:\textures\checker.png`) still finds `checker.png` next to the
/// model (#1274). `None` when the name carries no path at all.
fn sibling_name(name: &str) -> Option<&str> {
let file = name.rsplit(['/', '\\']).next()?;
(!file.is_empty() && file.len() < name.len()).then_some(file)
}
/// A material reference resolved against the model's folder: the name as written (a name
/// containing spaces is one name), then its file name (an absolute path from another machine,
/// #1274), then the final token (the options convention, `-bm 1 file.png`).
/// A material reference resolved against the model's folder: the name as written, then its file
/// name, then the final token.
fn resolve_reference(resolve: &dyn Fn(&str) -> Option<Vec<u8>>, name: &str) -> Option<Vec<u8>> {
let mut tried: Vec<&str> = vec![];
for candidate in [name, sibling_name(name).unwrap_or(name), name.split_whitespace().last().unwrap_or(name)] {
for candidate in [name, craft_mesh::obj::sibling_name(name).unwrap_or(name), name.split_whitespace().last().unwrap_or(name)] {
if tried.contains(&candidate) {
continue;
}
@@ -39,263 +27,9 @@ fn resolve_reference(resolve: &dyn Fn(&str) -> Option<Vec<u8>>, name: &str) -> O
None
}
/// Parse MTL text into named materials (textures appended to `textures`).
pub fn parse_mtl(text: &str, resolve: &dyn Fn(&str) -> Option<Vec<u8>>, textures: &mut Vec<Arc<Texture>>) -> Vec<Material> {
let mut out: Vec<Material> = vec![];
let mut loaded: HashMap<String, Option<usize>> = HashMap::new();
let mut tex = |name: &str, textures: &mut Vec<Arc<Texture>>| -> Option<TexRef> {
let key = name.trim().to_string();
let t = *loaded.entry(key.clone()).or_insert_with(|| {
let Some(b) = resolve_reference(resolve, &key) else {
log::warn!("model: texture `{key}` was not found next to the model");
return None;
};
match Texture::decode(&b) {
Ok(t) => {
textures.push(Arc::new(t));
Some(textures.len() - 1)
}
Err(e) => {
log::warn!("model: cannot decode texture `{key}`: {e}");
None
}
}
});
t.map(|texture| TexRef { texture, uv_set: 0 })
};
let mut ns_seen = false;
let mut pr_seen = false;
for line in text.lines() {
let line = line.trim();
let (key, rest) = line.split_once(char::is_whitespace).map(|(k, r)| (k, r.trim())).unwrap_or((line, ""));
let f3 = || -> [f32; 3] {
let v: Vec<f32> = rest.split_whitespace().filter_map(|x| x.parse().ok()).collect();
match v.len() {
0 => [0.0; 3],
1 | 2 => [v[0]; 3],
_ => [v[0], v[1], v[2]],
}
};
let f1 = || rest.split_whitespace().next().and_then(|x| x.parse::<f32>().ok());
if key == "newmtl" {
if let Some(m) = out.last_mut() {
finish(m, ns_seen, pr_seen);
}
ns_seen = false;
pr_seen = false;
out.push(Material { name: rest.to_string(), metallic: 0.0, roughness: 0.5, ..Material::default() });
continue;
}
let Some(m) = out.last_mut() else { continue };
match key {
"Kd" => {
let c = f3();
m.base_color = [srgb_to_linear(c[0]), srgb_to_linear(c[1]), srgb_to_linear(c[2]), m.base_color[3]];
}
"Ke" => m.emissive = f3().map(srgb_to_linear),
"d" => m.base_color[3] = f1().unwrap_or(1.0),
"Tr" => m.base_color[3] = 1.0 - f1().unwrap_or(0.0),
"Ns" => {
let ns = f1().unwrap_or(0.0).max(0.0);
if !pr_seen {
m.roughness = (2.0 / (ns + 2.0)).sqrt();
}
ns_seen = true;
}
"Pr" => {
m.roughness = f1().unwrap_or(0.5).clamp(0.0, 1.0);
pr_seen = true;
}
"Pm" => m.metallic = f1().unwrap_or(0.0).clamp(0.0, 1.0),
"map_Kd" => m.base_color_tex = tex(rest, textures),
"map_Ke" => {
m.emissive_tex = tex(rest, textures);
if m.emissive == [0.0; 3] {
m.emissive = [1.0; 3];
}
}
"map_Bump" | "map_bump" | "bump" | "norm" => m.normal_tex = tex(rest, textures),
_ => {}
}
}
if let Some(m) = out.last_mut() {
finish(m, ns_seen, pr_seen);
}
out
}
fn finish(m: &mut Material, _ns: bool, _pr: bool) {
if m.base_color[3] < 0.999 {
m.alpha_mode = AlphaMode::Blend;
}
}
/// sRGB-encoded component → linear (MTL colours are display colours).
pub fn srgb_to_linear(c: f32) -> f32 {
if c <= 0.04045 { c / 12.92 } else { ((c + 0.055) / 1.055).powf(2.4) }
}
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
struct Key {
v: u32,
t: u32,
n: u32,
/// Smoothing state (faces without normals get computed normals per state).
s: u32,
}
/// Parse OBJ text (and its MTL libraries through `resolve`).
/// Parse OBJ text (and its MTL libraries and textures through `resolve`).
pub fn parse(bytes: &[u8], resolve: &dyn Fn(&str) -> Option<Vec<u8>>) -> Result<Model> {
let text = String::from_utf8_lossy(bytes);
let mut v: Vec<[f32; 3]> = vec![];
let mut vt: Vec<[f32; 2]> = vec![];
let mut vn: Vec<[f32; 3]> = vec![];
let mut materials: Vec<Material> = vec![];
let mut textures: Vec<Arc<Texture>> = vec![];
// One primitive per material, in order of first use.
let mut prims: Vec<(Option<usize>, Primitive, HashMap<Key, u32>, Vec<bool>)> = vec![];
let mut current: Option<usize> = None;
let mut smooth = 0u32;
let mut flat_id = 1u32 << 31;
let mut faces = 0usize;
// Join `\` line continuations.
let joined = text.replace("\\\r\n", " ").replace("\\\n", " ");
for (ln, line) in joined.lines().enumerate() {
let line = line.split('#').next().unwrap_or("").trim();
if line.is_empty() {
continue;
}
let mut it = line.split_whitespace();
let key = it.next().unwrap_or("");
let rest: Vec<&str> = it.collect();
let fl = |i: usize| rest.get(i).and_then(|x| x.parse::<f32>().ok());
match key {
"v" => v.push([fl(0).unwrap_or(0.0), fl(1).unwrap_or(0.0), fl(2).unwrap_or(0.0)]),
"vt" => vt.push([fl(0).unwrap_or(0.0), fl(1).unwrap_or(0.0)]),
"vn" => vn.push([fl(0).unwrap_or(0.0), fl(1).unwrap_or(0.0), fl(2).unwrap_or(1.0)]),
"s" => {
smooth = match rest.first().copied() {
None | Some("off") | Some("0") => 0,
Some(x) => x.parse().unwrap_or(1).max(1),
}
}
"mtllib" => {
let name = line["mtllib".len()..].trim();
let mut found = false;
for file in std::iter::once(name).chain(name.split_whitespace()).chain(sibling_name(name)) {
if let Some(b) = resolve(file) {
let mut ms = parse_mtl(&String::from_utf8_lossy(&b), resolve, &mut textures);
materials.append(&mut ms);
found = true;
break;
}
}
if !found && !name.is_empty() {
log::warn!("model: material library `{name}` was not found next to the model");
}
}
"usemtl" => {
let name = line["usemtl".len()..].trim();
current = materials.iter().position(|m| m.name == name);
if current.is_none() {
// Unknown material: a named grey default.
materials.push(Material { name: name.to_string(), metallic: 0.0, roughness: 0.5, base_color: [0.8, 0.8, 0.8, 1.0], ..Material::default() });
current = Some(materials.len() - 1);
}
}
"f" => {
if rest.len() < 3 {
continue;
}
faces += 1;
let resolve_i = |s: &str, len: usize| -> Option<u32> {
if s.is_empty() {
return None;
}
let i: i64 = s.parse().ok()?;
let k = if i < 0 { len as i64 + i } else { i - 1 };
(k >= 0 && (k as usize) < len).then_some(k as u32)
};
let mut refs = vec![];
for r in &rest {
let mut parts = r.split('/');
let vi = resolve_i(parts.next().unwrap_or(""), v.len()).ok_or_else(|| perr(format!("line {}: bad vertex index `{r}`", ln + 1)))?;
let ti = parts.next().and_then(|s| resolve_i(s, vt.len()));
let ni = parts.next().and_then(|s| resolve_i(s, vn.len()));
refs.push((vi, ti, ni));
}
let has_n = refs.iter().all(|r| r.2.is_some());
// Faces without normals: shared within a smoothing group, unique otherwise.
let s = if has_n {
0
} else if smooth == 0 {
flat_id += 1;
flat_id
} else {
smooth
};
let slot = match prims.iter().position(|p| p.0 == current) {
Some(i) => i,
None => {
prims.push((current, Primitive { material: current, ..Default::default() }, HashMap::new(), vec![]));
prims.len() - 1
}
};
let (_, prim, map, need) = &mut prims[slot];
let mut ids = vec![];
for (vi, ti, ni) in refs {
let k = Key { v: vi, t: ti.unwrap_or(u32::MAX), n: ni.unwrap_or(u32::MAX), s };
let id = *map.entry(k).or_insert_with(|| {
prim.positions.push(v[vi as usize]);
prim.uvs.push(ti.map_or([0.0, 0.0], |t| vt[t as usize]));
prim.normals.push(ni.map_or([0.0; 3], |n| vn[n as usize]));
need.push(ni.is_none());
(prim.positions.len() - 1) as u32
});
ids.push(id);
}
for i in 2..ids.len() {
prim.indices.extend([ids[0], ids[i - 1], ids[i]]);
}
}
_ => {}
}
}
if faces == 0 {
return Err(perr("OBJ file without faces"));
}
let any_uv = !vt.is_empty();
let mut mesh = Mesh { name: String::new(), primitives: vec![] };
for (_, mut p, _, need) in prims {
if need.iter().any(|&b| b) {
// Fill missing normals from the triangles (area weighted), keep given ones.
let given = p.normals.clone();
p.compute_normals();
for (i, n) in p.normals.iter_mut().enumerate() {
if !need[i] {
*n = given[i];
}
}
}
if !any_uv {
p.uvs.clear();
} else {
// OBJ's v axis points up the image; textures are stored top row first.
for uv in p.uvs.iter_mut() {
uv[1] = 1.0 - uv[1];
}
}
if p.material.is_some_and(|m| materials[m].normal_tex.is_some()) {
p.compute_tangents();
}
mesh.primitives.push(p);
}
Ok(Model::single(mesh, materials).with_textures(textures))
}
impl Model {
fn with_textures(mut self, t: Vec<Arc<Texture>>) -> Model {
self.textures = t;
self
}
let mut library = |name: &str| resolve_reference(resolve, name);
let scene = craft_mesh::obj::read(bytes, &limits(), &mut library).map_err(error)?;
to_model(scene, MissingNormals::BySmoothing, &|im| resolve_reference(resolve, im.uri.as_deref()?.trim()))
}
+268
View File
@@ -0,0 +1,268 @@
//! 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, 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(scene: cm::Scene, missing: MissingNormals, image: &dyn Fn(&cm::Image) -> Option<Vec<u8>>) -> Result<Model> {
for w in &scene.warnings {
log::warn!("model: {w}");
}
// Images decode once; each (image, wrap) a material uses is one texture.
let decoded: Vec<Option<Arc<Texture>>> = scene
.images
.iter()
.map(|im| {
let bytes = im.data.clone().or_else(|| image(im));
match bytes.map(|b| Texture::decode(&b)) {
Some(Ok(t)) => Some(Arc::new(t)),
Some(Err(e)) => {
log::warn!("model: cannot decode texture `{}`: {e}", im.uri.as_deref().unwrap_or(&im.name));
None
}
None => {
log::warn!("model: texture `{}` was not found next to the model", im.uri.as_deref().unwrap_or(&im.name));
None
}
}
})
.collect();
let mut textures: Vec<Arc<Texture>> = vec![];
let mut texture_of: HashMap<(usize, [Wrap; 2]), usize> = HashMap::new();
let mut tref = |t: Option<cm::TextureRef>| -> Option<TexRef> {
let t = t?;
let img = decoded.get(t.image).cloned().flatten()?;
let w = t.wrap.map(wrap);
let texture = *texture_of.entry((t.image, w)).or_insert_with(|| {
textures.push(if img.wrap == w { img } else { Arc::new(Texture { wrap: w, ..(*img).clone() }) });
textures.len() - 1
});
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 meshes = scene.meshes.iter().map(|m| mesh(m, &materials, missing)).collect();
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 })
}
/// 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) -> 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();
let mut primitives = vec![];
for part in &m.parts {
let normals = part.corners.iter().all(|c| (c.normal as usize) < m.normals.len());
let uvs = uv_set.filter(|set| part.corners.iter().all(|c| (c.uv as usize) < set.len()));
let mut ids: HashMap<cm::Corner, u32> = HashMap::new();
let mut p = Primitive { material: part.material.filter(|&i| i < materials.len()), ..Primitive::default() };
for t in part.triangles() {
if t.iter().any(|c| c.position as usize >= m.positions.len()) {
continue;
}
for c in t {
let key = cm::Corner { position: c.position, normal: if normals { c.normal } else { cm::NONE }, uv: if uvs.is_some() { c.uv } else { cm::NONE } };
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 {
p.normals.push(m.normals.get(c.normal as usize).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 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.material.is_some_and(|i| materials.get(i).is_some_and(|mat| mat.normal_tex.is_some())) {
p.compute_tangents();
}
primitives.push(p);
}
Mesh { name: m.name.clone(), primitives }
}
+14 -192
View File
@@ -1,201 +1,23 @@
//! STL (stereolithography) meshes, binary and ASCII.
//! STL (stereolithography) meshes, binary and ASCII, read with `craft-mesh`
//! (`craft_mesh::stl`): every facet keeps its own three vertices and its face normal, and binary
//! colour extensions become one plain material per colour.
//!
//! Written from the public description of the format (3D Systems' StereoLithography Interface
//! Specification, 1989, and its widely documented colour extensions):
//!
//! - Binary: an 80-byte header, a little-endian `u32` facet count, then 50 bytes per facet: a
//! normal and three vertices (12 `f32`) and a 16-bit attribute word. Bytes after the last
//! facet are ignored.
//! - ASCII: `solid name`, then `facet normal nx ny nz` / `outer loop` / `vertex x y z`… /
//! `endloop` / `endfacet`, closed by `endsolid`; several solids may follow each other.
//! Loops with more than three vertices are fan-triangulated.
//! - Colour (binary only): with `COLOR=r g b a` (four bytes) in the header (Materialise Magics),
//! that is the part's colour and a facet whose attribute has bit 15 clear has its own colour
//! (red in bits 0–4, green 5–9, blue 10–14); otherwise (VisCAM / SolidView) a facet with bit 15
//! set has its own colour (blue in bits 0–4, green 5–9, red 10–14). Each colour becomes a
//! plain dielectric material; uncoloured files get none (the renderer's default material).
//!
//! STL has no units, no UVs and no shared vertices: every facet keeps its own three vertices
//! with the face normal from its counter-clockwise winding (the stored normal is only used when
//! the triangle is degenerate), which gives the faceted look of an STL part. STL files are
//! Z-up (3D printing and CAD); they are turned to the +Y-up convention of [`crate::Model`]
//! (`(x, y, z)` → `(x, z, −y)`, a proper rotation, so winding is kept). Facets with non-finite
//! coordinates are skipped.
//! STL files are Z-up (3D printing and CAD); they are turned to the +Y-up convention of
//! [`crate::Model`] (`(x, y, z)` → `(x, z, −y)`, a proper rotation, so winding is kept).
use std::collections::HashMap;
use crate::{Material, Mesh, Model, Primitive, Result, cross, normalize, obj::srgb_to_linear, perr, sub};
/// Header (80) plus facet count (4).
const HEADER: usize = 84;
/// Bytes per binary facet.
const FACET: usize = 50;
/// Parse an STL file (binary or ASCII, detected from the contents).
pub fn parse(bytes: &[u8]) -> Result<Model> {
let count = bytes.get(80..HEADER).and_then(|b| <[u8; 4]>::try_from(b).ok()).map(u32::from_le_bytes);
let needed = count.and_then(|n| (n as usize).checked_mul(FACET)).and_then(|n| n.checked_add(HEADER));
// A binary file's size is exact; many binary headers still begin with `solid`, so the size
// decides first, then the ASCII keyword.
if needed.is_some_and(|n| n == bytes.len()) {
return binary(bytes);
}
if looks_ascii(bytes) {
return ascii(bytes);
}
if needed.is_some_and(|n| n <= bytes.len()) {
return binary(bytes);
}
Err(perr("not an STL file (truncated binary facets or no `solid` keyword)"))
}
fn looks_ascii(bytes: &[u8]) -> bool {
let head = bytes.get(..bytes.len().min(512)).unwrap_or(&[]);
let text = String::from_utf8_lossy(head);
let t = text.trim_start();
t.get(..5).is_some_and(|k| k.eq_ignore_ascii_case("solid")) && (t.contains("facet") || t.contains("endsolid"))
}
use crate::scene::{MissingNormals, error, limits, to_model};
use crate::{Model, Result};
/// The Z-up → Y-up turn.
fn y_up(v: [f32; 3]) -> [f32; 3] {
fn y_up(v: [f64; 3]) -> [f64; 3] {
[v[0], v[2], -v[1]]
}
/// Facets grouped into primitives by colour, in order of first use.
#[derive(Default)]
struct Builder {
/// (colour key, primitive); `None` = uncoloured.
prims: Vec<(Option<[u8; 3]>, Primitive)>,
/// Colour → index into `prims` (up to 32 768 colours, so not a linear search).
slots: HashMap<Option<[u8; 3]>, usize>,
facets: usize,
}
impl Builder {
/// Add one triangle (file coordinates); `stored` is the file's facet normal.
fn tri(&mut self, color: Option<[u8; 3]>, stored: [f32; 3], v: [[f32; 3]; 3]) {
if v.iter().flatten().any(|c| !c.is_finite()) {
return;
}
let v = v.map(y_up);
let n = normalize(cross(sub(v[1], v[0]), sub(v[2], v[0])))
.or_else(|| stored.iter().all(|c| c.is_finite()).then(|| normalize(y_up(stored))).flatten())
.unwrap_or([0.0, 1.0, 0.0]);
let slot = *self.slots.entry(color).or_insert_with(|| {
self.prims.push((color, Primitive::default()));
self.prims.len() - 1
});
let Some((_, p)) = self.prims.get_mut(slot) else { return };
for c in v {
p.indices.push(p.positions.len() as u32);
p.positions.push(c);
p.normals.push(n);
}
self.facets += 1;
}
fn finish(self, name: String) -> Result<Model> {
if self.facets == 0 {
return Err(perr("STL file without facets"));
}
let mut materials = vec![];
let mut mesh = Mesh { name, primitives: vec![] };
for (color, mut p) in self.prims {
if let Some(c) = color {
let lin = c.map(|x| srgb_to_linear(x as f32 / 255.0));
let name = format!("#{:02X}{:02X}{:02X}", c[0], c[1], c[2]);
materials.push(Material { name, ..Material::plain([lin[0], lin[1], lin[2], 1.0], 0.0, 0.5) });
p.material = Some(materials.len() - 1);
}
mesh.primitives.push(p);
}
// Uncoloured facets next to coloured ones: a neutral grey of their own.
if !materials.is_empty() {
for p in mesh.primitives.iter_mut().filter(|p| p.material.is_none()) {
materials.push(Material { name: "STL".into(), ..Material::plain([0.6, 0.6, 0.6, 1.0], 0.0, 0.5) });
p.material = Some(materials.len() - 1);
}
}
Ok(Model::single(mesh, materials))
/// Parse an STL file (binary or ASCII, detected from the contents).
pub fn parse(bytes: &[u8]) -> Result<Model> {
let mut scene = craft_mesh::stl::read(bytes, &limits()).map_err(error)?;
for m in &mut scene.meshes {
m.positions.iter_mut().chain(m.normals.iter_mut()).for_each(|v| *v = y_up(*v));
}
}
fn f32_at(b: &[u8], at: usize) -> f32 {
b.get(at..at + 4).and_then(|s| <[u8; 4]>::try_from(s).ok()).map_or(f32::NAN, f32::from_le_bytes)
}
/// A 5-bit channel expanded to 8 bits.
fn five(x: u16) -> u8 {
let x = (x & 31) as u8;
(x << 3) | (x >> 2)
}
/// The Magics `COLOR=` part colour in the header (RGB; alpha is ignored).
fn header_color(header: &[u8]) -> Option<[u8; 3]> {
let at = header.windows(6).position(|w| w == b"COLOR=")?;
let c = header.get(at + 6..at + 10)?;
Some([*c.first()?, *c.get(1)?, *c.get(2)?])
}
fn binary(bytes: &[u8]) -> Result<Model> {
let header = bytes.get(..80).ok_or_else(|| perr("STL header truncated"))?;
let magics = header_color(header);
let body = bytes.get(HEADER..).unwrap_or(&[]);
let count = bytes.get(80..HEADER).and_then(|b| <[u8; 4]>::try_from(b).ok()).map_or(0, u32::from_le_bytes) as usize;
let mut b = Builder::default();
for f in body.as_chunks::<FACET>().0.iter().take(count) {
let n = [f32_at(f, 0), f32_at(f, 4), f32_at(f, 8)];
let v = [0usize, 1, 2].map(|k| [f32_at(f, 12 + 12 * k), f32_at(f, 16 + 12 * k), f32_at(f, 20 + 12 * k)]);
let attr = f.get(48..50).and_then(|a| <[u8; 2]>::try_from(a).ok()).map_or(0, u16::from_le_bytes);
let color = match magics {
Some(part) => Some(if attr & 0x8000 == 0 { [five(attr), five(attr >> 5), five(attr >> 10)] } else { part }),
None => (attr & 0x8000 != 0).then(|| [five(attr >> 10), five(attr >> 5), five(attr)]),
};
b.tri(color, n, v);
}
let text = String::from_utf8_lossy(header);
let name = text.trim_matches(|c: char| c == '\0' || c.is_whitespace());
b.finish(name.strip_prefix("solid").unwrap_or(name).trim().to_string())
}
/// Three numbers from the rest of an ASCII line.
fn three<'a>(it: &mut impl Iterator<Item = &'a str>) -> Option<[f32; 3]> {
Some([it.next()?.parse().ok()?, it.next()?.parse().ok()?, it.next()?.parse().ok()?])
}
fn ascii(bytes: &[u8]) -> Result<Model> {
let text = String::from_utf8_lossy(bytes);
let mut b = Builder::default();
let mut name: Option<String> = None;
let mut normal = [0.0f32; 3];
let mut loop_v: Vec<[f32; 3]> = vec![];
for (ln, line) in text.lines().enumerate() {
let line = line.trim();
let mut it = line.split_whitespace();
let Some(key) = it.next() else { continue };
let bad = || perr(format!("STL line {}: expected three numbers", ln + 1));
match key.to_ascii_lowercase().as_str() {
"solid" if name.is_none() => {
name = Some(line.get(5..).unwrap_or("").trim().to_string());
}
"facet" => {
// `facet normal nx ny nz`
normal = it.next().and_then(|_| three(&mut it)).unwrap_or([0.0; 3]);
loop_v.clear();
}
"vertex" => loop_v.push(three(&mut it).ok_or_else(bad)?),
"endloop" | "endfacet" => {
if let Some((&first, rest)) = loop_v.split_first() {
for w in rest.windows(2) {
if let [a, c] = w {
b.tri(None, normal, [first, *a, *c]);
}
}
}
loop_v.clear();
}
_ => {}
}
}
b.finish(name.unwrap_or_default())
to_model(scene, MissingNormals::Flat, &|_| None)
}
-48
View File
@@ -683,51 +683,3 @@ fn gltf_buffer_less_accessors_share_one_zero_budget() {
assert!(crate::gltf::parse(doc.as_bytes(), &|_| None).is_ok());
}
/// `refs` primitives sharing one buffer-backed `verts`-vertex POSITION accessor, without indices.
fn gltf_shared_positions(verts: usize, refs: usize) -> String {
let acc = format!(r#"{{"bufferView": 0, "componentType": 5126, "type": "VEC3", "count": {verts}}}"#);
let prims = vec![r#"{"attributes": {"POSITION": 0}}"#; refs].join(", ");
gltf_doc(&acc, r#"{"buffer": 0}"#, verts * 12).replace(r#"[{"attributes": {"POSITION": 0}}]"#, &format!("[{prims}]"))
}
#[test]
fn gltf_buffer_backed_reads_share_one_read_budget() {
// A buffer-backed accessor is checked against its buffer, but each primitive that references
// it reads and keeps its own copy, so a small file listing many references must not ask for
// memory set by the reference count (#2139 review). Everything a primitive keeps is charged
// to one per-file budget: 1,000 vertices without indices or normals cost 3,000 position
// components, 1,000 generated indices, a 999-index triangle list and 999 flat-shaded
// vertices of 6 components, 10,993 in all.
let one = gltf_shared_positions(1000, 1);
let m = crate::gltf::parse_with_budget(one.as_bytes(), &|_| None, 20_000).unwrap();
assert_eq!(m.meshes[0].primitives.len(), 1);
let three = gltf_shared_positions(1000, 3);
assert_eq!(three.matches(r#""POSITION": 0"#).count(), 3);
let e = crate::gltf::parse_with_budget(three.as_bytes(), &|_| None, 20_000).err().unwrap_or_else(|| panic!("imported"));
assert!(e.to_string().contains("more than 20000 components"), "{e}");
// The real cap leaves room for legitimate sharing: many primitives over one vertex buffer.
let m = crate::gltf::parse(gltf_shared_positions(1000, 50).as_bytes(), &|_| None).unwrap();
assert_eq!(m.meshes[0].primitives.len(), 50);
}
#[test]
fn gltf_missing_indices_are_charged_to_the_read_budget() {
// Without `indices` every vertex gets a generated index, allocated like a read: after the
// 3,000 position components, 999 left is one short for the 1,000 indices.
let doc = gltf_shared_positions(1000, 1);
let e = crate::gltf::parse_with_budget(doc.as_bytes(), &|_| None, 3999).err().unwrap_or_else(|| panic!("imported"));
assert!(e.to_string().contains("(1000 requested, 999 left)"), "{e}");
}
#[test]
fn gltf_strip_expansion_is_charged_to_the_read_budget() {
// A strip of k indices becomes 3(k-2) triangle indices and as many flat-shaded vertices, so
// the output is charged, not only the 1,009 components read.
let doc = gltf_doc(r#"{"bufferView": 0, "componentType": 5126, "type": "VEC3", "count": 3}"#, r#"{"buffer": 0}"#, 1036)
.replace(r#""count": 3}]"#, r#""count": 3}, {"bufferView": 0, "componentType": 5121, "type": "SCALAR", "count": 1000}]"#)
.replace(r#""attributes": {"POSITION": 0}"#, r#""attributes": {"POSITION": 0}, "indices": 1, "mode": 5"#);
let m = crate::gltf::parse_with_budget(doc.as_bytes(), &|_| None, 30_000).unwrap();
assert_eq!(m.meshes[0].primitives[0].indices.len(), 2994);
let e = crate::gltf::parse_with_budget(doc.as_bytes(), &|_| None, 5000).err().unwrap_or_else(|| panic!("imported"));
assert!(e.to_string().contains("more than 5000 components"), "{e}");
}