falcon_library/model3d/

fbx.rs

//! FBX, binary and ASCII, read with ufbx (MIT, <https://github.com/ufbx/ufbx>).
//!
//! Every node with a mesh becomes one [`Mesh`] per material it uses, with
//! the node's geometry-to-world transform baked into positions and normals.
//! Polygons are split with ufbx's triangulation; normals the file lacks are
//! generated by ufbx. Each material gives its base (diffuse) colour and
//! opacity, and its diffuse (or base colour) texture when there is one:
//! the picture comes from the file's embedded media, else from a file next
//! to the model (see [`texture::Loader`]), and is laid on with the file's
//! UVs (v flipped to picture space) and UV transform; wrap modes are ignored,
//! textures always repeat (see [`texture`]). A
//! picture that is missing or can't be decoded leaves the colour.
//!
//! The surface follows what Eagle's viewer shows for FBX: the `Bump` and
//! `NormalMap` pictures (also Maya's `TEX_normal_map`) are read the same
//! way and share the mesh's UVs; the one UV transform baked in is the base
//! map's, else the normal map's, else the bump map's. A material is drawn
//! see-through when its opacity is below 1 or a texture is connected to
//! `TransparentColor` or `TransparencyFactor` (that picture is not drawn).
//! Emissive colour and maps are deliberately not read: the viewer drops
//! them for FBX, so the emissive stays black.
//!
//! The scene is converted to the viewer's convention: right-handed, Y up,
//! and centimetres, the FBX default unit (the file's `UnitScaleFactor` is
//! applied, so a file saved in metres shows sizes in centimetres too).
//!
//! Not read: other maps (emissive, specular, ...), vertex colours, skinning
//! and blend shapes (meshes stay in their bind pose), animation, cameras,
//! lights, NURBS and external files other than texture pictures.

use std::collections::HashMap;

use super::math::{self, V3};
use super::texture::{self, Texture};
use super::{Material, Mesh, Model, ParseError, Result};

/// Most memory ufbx may use while parsing, and for the scene it returns;
/// a broken or hostile file fails with a memory-limit error instead.
const TEMP_LIMIT: usize = 1 << 30;
const RESULT_LIMIT: usize = 2 << 30;
/// Deepest node nesting accepted.
const NODE_DEPTH_LIMIT: u32 = 256;
/// Most output vertices, against files that instance a big mesh many times.
const MAX_VERTICES: usize = 50_000_000;

/// Metres per output unit: centimetres.
const TARGET_UNIT_METERS: f64 = 0.01;

fn limits(memory_limit: usize) -> ufbx::AllocatorOpts {
    ufbx::AllocatorOpts { memory_limit, ..Default::default() }
}

pub fn parse(bytes: &[u8], side: &dyn Fn(&str) -> Option<Vec<u8>>) -> Result<Model> {
    let opts = ufbx::LoadOpts {
        temp_allocator: limits(TEMP_LIMIT),
        result_allocator: limits(RESULT_LIMIT),
        ignore_animation: true,
        // Embedded media are read for textures; files on disk are not
        // opened by ufbx but fetched through `side`.
        ignore_embedded: false,
        load_external_files: false,
        generate_missing_normals: true,
        // Always FBX: an OBJ renamed .fbx is refused, not read by ufbx's
        // OBJ parser.
        file_format: ufbx::FileFormat::Fbx,
        node_depth_limit: NODE_DEPTH_LIMIT,
        space_conversion: ufbx::SpaceConversion::ModifyGeometry,
        target_axes: ufbx::CoordinateAxes {
            right: ufbx::CoordinateAxis::PositiveX,
            up: ufbx::CoordinateAxis::PositiveY,
            front: ufbx::CoordinateAxis::PositiveZ,
        },
        target_unit_meters: TARGET_UNIT_METERS,
        ..Default::default()
    };
    let scene = ufbx::load_memory(bytes, opts).map_err(|e| ParseError(format!("not a readable FBX file: {}", e.description.trim())))?;
    let mut model = Model::default();
    let mut vertices = 0usize;
    let mut loader = texture::Loader::new(side);
    for node in &scene.nodes {
        let Some(mesh) = node.mesh.as_ref() else { continue };
        for out in node_meshes(node, mesh, &mut loader) {
            vertices += out.positions.len();
            if vertices > MAX_VERTICES {
                return Err(ParseError::new("the FBX has too many vertices"));
            }
            model.meshes.push(out);
        }
    }
    model.finish()
}

fn v3(v: ufbx::Vec3) -> V3 {
    [v.x as f32, v.y as f32, v.z as f32]
}

/// The meshes one node draws: one per material part with triangles.
fn node_meshes(node: &ufbx::Node, mesh: &ufbx::Mesh, loader: &mut texture::Loader) -> Vec<Mesh> {
    let to_world = &node.geometry_to_world;
    let normal_matrix = ufbx::matrix_for_normals(to_world);
    // A mirroring transform turns the winding around; swap two corners to
    // keep the front counter-clockwise.
    let mirrored = ufbx::matrix_determinant(to_world) < 0.0;
    // A node may override the mesh's materials per instance.
    let materials = if node.materials.is_empty() { &mesh.materials } else { &node.materials };
    let positions = &mesh.vertex_position;
    let normals = &mesh.vertex_normal;
    let uvs = &mesh.vertex_uv;
    let mut tri = vec![0u32; mesh.max_face_triangles.max(1) * 3];
    let mut out = Vec::new();
    for part in mesh.material_parts.iter() {
        if part.num_triangles == 0 {
            continue;
        }
        let mut m = Mesh { name: node.element.name.to_string(), ..Default::default() };
        let mat = materials.get(part.index as usize);
        let tex = mat.and_then(|mat| map_texture(mat, loader));
        // The normal and bump maps need the mesh's UVs, so are not decoded
        // without them.
        let (normal, bump) = match mat {
            Some(mat) if uvs.exists => (
                loader.for_map(|l| normal_texture(mat).and_then(|t| file_texture(t, l))),
                loader.for_map(|l| mat.fbx.bump.texture.as_ref().and_then(|t| file_texture(t, l))),
            ),
            _ => (None, None),
        };
        // One transform for all the maps: the first map's that exists.
        let transform = tex.as_ref().or(normal.as_ref()).or(bump.as_ref()).and_then(|t| t.1);
        let mut ns: Vec<V3> = Vec::new();
        let mut uv_out: Vec<[f32; 2]> = Vec::new();
        // (position index, normal index, uv index) → output vertex.
        let mut seen: HashMap<(u32, u32, u32), u32> = HashMap::new();
        for &fi in part.face_indices.iter() {
            let Some(&face) = mesh.faces.get(fi as usize) else { continue };
            if face.num_indices < 3 {
                continue;
            }
            let n = ufbx::triangulate_face(&mut tri, mesh, face) as usize;
            for t in tri[..n * 3].as_chunks::<3>().0 {
                let t = if mirrored { [t[0], t[2], t[1]] } else { *t };
                for ix in t {
                    // ufbx keeps every index in range; a miss reads as 0.
                    let ix = ix as usize;
                    let pi = positions.indices.get(ix).copied().unwrap_or(0);
                    let ni = if normals.exists { normals.indices.get(ix).copied().unwrap_or(0) } else { u32::MAX };
                    let ui = if uvs.exists { uvs.indices.get(ix).copied().unwrap_or(0) } else { u32::MAX };
                    let next = m.positions.len() as u32;
                    let v = *seen.entry((pi, ni, ui)).or_insert_with(|| {
                        let p = positions.values.get(pi as usize).copied().unwrap_or_default();
                        m.positions.push(v3(ufbx::transform_position(to_world, p)));
                        let nv = normals.values.get(ni as usize).copied().unwrap_or_default();
                        ns.push(math::normalize(v3(ufbx::transform_direction(&normal_matrix, nv))));
                        if uvs.exists {
                            let uv = uvs.values.get(ui as usize).copied().unwrap_or_default();
                            uv_out.push(picture_uv(uv, transform.as_ref()));
                        }
                        next
                    });
                    m.indices.push(v);
                }
            }
        }
        if normals.exists {
            m.normals = Some(ns);
        }
        if uvs.exists {
            m.uvs = Some(uv_out);
        }
        // A picture without UVs can't be laid on.
        m.texture = tex.filter(|_| uvs.exists).map(|t| t.0);
        m.material = mat.map(|m| material(m));
        m.surface.normal_map = normal.map(|t| t.0);
        m.surface.bump_map = bump.map(|t| t.0);
        m.surface.blend = mat.is_some_and(|mat| see_through(mat, m.material.as_ref().map_or(1.0, |m| m.opacity)));
        out.push(m);
    }
    out
}

/// A texture coordinate in picture space: the texture's UV transform (when
/// it has one) applied in the file's v-up space, then v flipped.
fn picture_uv(uv: ufbx::Vec2, transform: Option<&ufbx::Matrix>) -> [f32; 2] {
    let (mut u, mut v) = (uv.x, uv.y);
    if let Some(t) = transform {
        (u, v) = (t.m00 * uv.x + t.m01 * uv.y + t.m03, t.m10 * uv.x + t.m11 * uv.y + t.m13);
    }
    [u as f32, 1.0 - v as f32]
}

/// The material's diffuse texture, decoded, with its UV transform if any.
fn map_texture(mat: &ufbx::Material, loader: &mut texture::Loader) -> Option<(Texture, Option<ufbx::Matrix>)> {
    let tex = mat.pbr.base_color.texture.as_ref().or(mat.fbx.diffuse_color.texture.as_ref())?;
    file_texture(tex, loader)
}

/// The texture connected as the normal map (FBX `NormalMap`, Maya's
/// `TEX_normal_map`).
fn normal_texture(mat: &ufbx::Material) -> Option<&ufbx::Texture> {
    mat.fbx.normal_map.texture.as_ref().or(mat.pbr.normal_map.texture.as_ref()).map(|t| &**t)
}

/// The picture of a texture, decoded, with its UV transform if any.
fn file_texture(tex: &ufbx::Texture, loader: &mut texture::Loader) -> Option<(Texture, Option<ufbx::Matrix>)> {
    // A layered or procedural texture: its first picture.
    let file = if tex.type_ == ufbx::TextureType::File { Some(tex) } else { tex.file_textures.first().map(|t| &**t) }?;
    let name = |p: &str| p.rsplit(['/', '\\']).next().unwrap_or(p).to_string();
    // An empty blob has a null pointer: test its size, not the slice.
    let image = if file.content.size > 0 {
        loader.embedded(&name(&file.filename), &file.content)
    } else {
        [&file.relative_filename, &file.filename]
            .into_iter()
            .filter(|p| !p.is_empty())
            .find_map(|p| loader.file(&p.replace('\\', "/")))
    }?;
    Some((Texture::new(image), file.has_uv_transform.then_some(file.uv_to_texture)))
}

/// Whether the material is drawn see-through: opacity below 1, or a
/// texture on its transparency colour or factor.
fn see_through(mat: &ufbx::Material, opacity: f32) -> bool {
    opacity < 1.0 - 1e-6 || mat.fbx.transparency_color.texture.is_some() || mat.fbx.transparency_factor.texture.is_some()
}

fn material(mat: &ufbx::Material) -> Material {
    let pbr = &mat.pbr;
    let c = pbr.base_color.value_vec4;
    let factor = if pbr.base_factor.has_value { pbr.base_factor.value_vec4.x } else { 1.0 };
    let color = [c.x, c.y, c.z].map(|v| ((v * factor) as f32).clamp(0.0, 1.0));
    let color = if pbr.base_color.has_value { color } else { super::DEFAULT_COLOR };
    // Only the `Opacity` property, as in Eagle's viewer. `TransparencyFactor`
    // is no guide: exporters commonly write 1 on fully opaque materials.
    let opacity = ufbx::find_prop(&mat.element.props, "Opacity").map_or(1.0f32, |p| p.value_vec4.x as f32);
    // NaN counts as opaque.
    let opacity = if opacity.is_nan() { 1.0 } else { opacity.clamp(0.0, 1.0) };
    Material { name: mat.element.name.to_string(), color, opacity }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A property of a hand-written FBX node.
    enum P {
        /// A 64-bit id (`L` in binary).
        Id(i64),
        /// A 32-bit integer (`I`).
        Int(i32),
        D(f64),
        S(&'static str),
        /// An object name: `Class::Name` in ASCII, `Name\0\x01Class` in
        /// binary.
        Name(&'static str, &'static str),
        Ints(Vec<i32>),
        Doubles(Vec<f64>),
        /// Raw bytes (`R`): binary files only.
        Bytes(Vec<u8>),
    }

    struct N {
        name: &'static str,
        props: Vec<P>,
        children: Vec<N>,
    }

    fn n(name: &'static str, props: Vec<P>, children: Vec<N>) -> N {
        N { name, props, children }
    }

    /// `P: "name", "type", "", "", values...` of a Properties70 block.
    fn prop(name: &'static str, ty: &'static str, values: Vec<P>) -> N {
        let mut props = vec![P::S(name), P::S(ty), P::S(""), P::S("")];
        props.extend(values);
        n("P", props, vec![])
    }

    fn ascii(nodes: &[N]) -> Vec<u8> {
        fn write(out: &mut String, node: &N, depth: usize) {
            let pad = "\t".repeat(depth);
            out.push_str(&format!("{pad}{}: ", node.name));
            let mut arrays = Vec::new();
            let parts: Vec<String> = node
                .props
                .iter()
                .map(|p| match p {
                    P::Id(v) => v.to_string(),
                    P::Int(v) => v.to_string(),
                    P::D(v) => format!("{v:?}"),
                    P::S(s) => format!("\"{s}\""),
                    P::Name(class, name) => format!("\"{class}::{name}\""),
                    P::Ints(v) => {
                        arrays.push(v.iter().map(|x| x.to_string()).collect::<Vec<_>>().join(","));
                        format!("*{}", v.len())
                    }
                    P::Bytes(_) => unreachable!("raw bytes in an ASCII file"),
                    P::Doubles(v) => {
                        arrays.push(v.iter().map(|x| format!("{x:?}")).collect::<Vec<_>>().join(","));
                        format!("*{}", v.len())
                    }
                })
                .collect();
            out.push_str(&parts.join(", "));
            if let Some(a) = arrays.first() {
                out.push_str(&format!(" {{\n{pad}\ta: {a}\n{pad}}}\n"));
            } else if node.children.is_empty() {
                out.push('\n');
            } else {
                out.push_str(" {\n");
                for c in &node.children {
                    write(out, c, depth + 1);
                }
                out.push_str(&format!("{pad}}}\n"));
            }
        }
        let mut out = String::from("; FBX 7.4.0 project file\n");
        for node in nodes {
            write(&mut out, node, 0);
        }
        out.into_bytes()
    }

    fn binary(nodes: &[N]) -> Vec<u8> {
        fn write(out: &mut Vec<u8>, node: &N) {
            let start = out.len();
            out.extend([0u8; 12]);
            out.push(node.name.len() as u8);
            out.extend(node.name.as_bytes());
            let props_start = out.len();
            for p in &node.props {
                match p {
                    P::Id(v) => {
                        out.push(b'L');
                        out.extend(v.to_le_bytes());
                    }
                    P::Int(v) => {
                        out.push(b'I');
                        out.extend(v.to_le_bytes());
                    }
                    P::D(v) => {
                        out.push(b'D');
                        out.extend(v.to_le_bytes());
                    }
                    P::S(s) => {
                        out.push(b'S');
                        out.extend((s.len() as u32).to_le_bytes());
                        out.extend(s.as_bytes());
                    }
                    P::Name(class, name) => {
                        let s = format!("{name}\0\x01{class}");
                        out.push(b'S');
                        out.extend((s.len() as u32).to_le_bytes());
                        out.extend(s.as_bytes());
                    }
                    P::Bytes(v) => {
                        out.push(b'R');
                        out.extend((v.len() as u32).to_le_bytes());
                        out.extend(v);
                    }
                    P::Ints(v) => {
                        out.push(b'i');
                        out.extend((v.len() as u32).to_le_bytes());
                        out.extend(0u32.to_le_bytes());
                        out.extend((v.len() as u32 * 4).to_le_bytes());
                        v.iter().for_each(|x| out.extend(x.to_le_bytes()));
                    }
                    P::Doubles(v) => {
                        out.push(b'd');
                        out.extend((v.len() as u32).to_le_bytes());
                        out.extend(0u32.to_le_bytes());
                        out.extend((v.len() as u32 * 8).to_le_bytes());
                        v.iter().for_each(|x| out.extend(x.to_le_bytes()));
                    }
                }
            }
            let props_len = (out.len() - props_start) as u32;
            if !node.children.is_empty() {
                for c in &node.children {
                    write(out, c);
                }
                out.extend([0u8; 13]);
            }
            let end = out.len() as u32;
            out[start..start + 4].copy_from_slice(&end.to_le_bytes());
            out[start + 4..start + 8].copy_from_slice(&(node.props.len() as u32).to_le_bytes());
            out[start + 8..start + 12].copy_from_slice(&props_len.to_le_bytes());
        }
        let mut out = b"Kaydara FBX Binary  \x00\x1a\x00".to_vec();
        out.extend(7400u32.to_le_bytes());
        for node in nodes {
            write(&mut out, node);
        }
        out.extend([0u8; 13]);
        out
    }

    fn header() -> N {
        n("FBXHeaderExtension", vec![], vec![n("FBXHeaderVersion", vec![P::Int(1003)], vec![]), n("FBXVersion", vec![P::Int(7400)], vec![])])
    }

    /// Global settings with `up` (0 X, 1 Y, 2 Z) as the up axis and the
    /// given unit scale (centimetres per file unit).
    fn settings(up: i32, unit_scale: f64) -> N {
        let front = if up == 2 { 1 } else { 2 };
        let front_sign = if up == 2 { -1 } else { 1 };
        n(
            "GlobalSettings",
            vec![],
            vec![
                n("Version", vec![P::Int(1000)], vec![]),
                n(
                    "Properties70",
                    vec![],
                    vec![
                        prop("UpAxis", "int", vec![P::Int(up)]),
                        prop("UpAxisSign", "int", vec![P::Int(1)]),
                        prop("FrontAxis", "int", vec![P::Int(front)]),
                        prop("FrontAxisSign", "int", vec![P::Int(front_sign)]),
                        prop("CoordAxis", "int", vec![P::Int(0)]),
                        prop("CoordAxisSign", "int", vec![P::Int(1)]),
                        prop("UnitScaleFactor", "double", vec![P::D(unit_scale)]),
                        prop("OriginalUnitScaleFactor", "double", vec![P::D(unit_scale)]),
                    ],
                ),
            ],
        )
    }

    /// A file with one box from (0,0,0) to (1,1,depth) as six quads,
    /// moved by `tx` along X, in a red material, without normals.
    fn box_file(up: i32, unit_scale: f64, tx: f64, depth: f64) -> Vec<N> {
        let corners = [[0., 0., 0.], [1., 0., 0.], [1., 1., 0.], [0., 1., 0.], [0., 0., 1.], [1., 0., 1.], [1., 1., 1.], [0., 1., 1.]];
        let verts: Vec<f64> = corners.iter().flat_map(|c: &[f64; 3]| [c[0], c[1], c[2] * depth]).collect();
        let quads = [[0, 3, 2, 1], [4, 5, 6, 7], [0, 1, 5, 4], [2, 3, 7, 6], [1, 2, 6, 5], [0, 4, 7, 3]];
        // The last corner of each polygon is stored as -(index + 1).
        let idx: Vec<i32> = quads.iter().flat_map(|q| [q[0], q[1], q[2], -q[3] - 1]).collect();
        vec![
            header(),
            settings(up, unit_scale),
            n(
                "Objects",
                vec![],
                vec![
                    n(
                        "Geometry",
                        vec![P::Id(1000), P::Name("Geometry", "Box"), P::S("Mesh")],
                        vec![n("Vertices", vec![P::Doubles(verts)], vec![]), n("PolygonVertexIndex", vec![P::Ints(idx)], vec![])],
                    ),
                    n(
                        "Model",
                        vec![P::Id(2000), P::Name("Model", "Box"), P::S("Mesh")],
                        vec![
                            n("Version", vec![P::Int(232)], vec![]),
                            n("Properties70", vec![], vec![prop("Lcl Translation", "Lcl Translation", vec![P::D(tx), P::D(0.0), P::D(0.0)])]),
                        ],
                    ),
                    n(
                        "Material",
                        vec![P::Id(3000), P::Name("Material", "Red"), P::S("")],
                        vec![
                            n("Version", vec![P::Int(102)], vec![]),
                            n("ShadingModel", vec![P::S("phong")], vec![]),
                            n("Properties70", vec![], vec![prop("DiffuseColor", "Color", vec![P::D(1.0), P::D(0.0), P::D(0.0)])]),
                        ],
                    ),
                ],
            ),
            n(
                "Connections",
                vec![],
                vec![
                    n("C", vec![P::S("OO"), P::Id(1000), P::Id(2000)], vec![]),
                    n("C", vec![P::S("OO"), P::Id(2000), P::Id(0)], vec![]),
                    n("C", vec![P::S("OO"), P::Id(3000), P::Id(2000)], vec![]),
                ],
            ),
        ]
    }

    fn size(m: &Model) -> V3 {
        let (lo, hi) = m.bounds().unwrap();
        math::sub(hi, lo)
    }

    fn close(a: V3, b: V3) -> bool {
        a.iter().zip(b).all(|(x, y)| (x - y).abs() < 1e-4)
    }

    #[test]
    fn ascii_and_binary_boxes_read_the_same() {
        for (kind, bytes) in [("ascii", ascii(&box_file(1, 1.0, 10.0, 1.0))), ("binary", binary(&box_file(1, 1.0, 10.0, 1.0)))] {
            let m = parse(&bytes, &|_| None).unwrap_or_else(|e| panic!("{kind}: {e}"));
            assert_eq!(m.meshes.len(), 1, "{kind}");
            assert_eq!(m.triangle_count(), 12, "{kind}: six quads, two triangles each");
            let mesh = &m.meshes[0];
            assert_eq!(mesh.name, "Box");
            let mat = mesh.material.as_ref().unwrap();
            assert_eq!((mat.name.as_str(), mat.color), ("Red", [1.0, 0.0, 0.0]), "{kind}");
            // The node's translation is applied.
            let (lo, hi) = m.bounds().unwrap();
            assert!(close(lo, [10.0, 0.0, 0.0]) && close(hi, [11.0, 1.0, 1.0]), "{kind}: {lo:?} {hi:?}");
            // Normals were generated, one per vertex, of unit length.
            let ns = mesh.normals.as_ref().expect("generated normals");
            assert_eq!(ns.len(), mesh.positions.len());
            assert!(ns.iter().all(|v| (math::length(*v) - 1.0).abs() < 1e-4));
            let s = super::super::geom::stats(&m);
            assert!((s.volume.unwrap() - 1.0).abs() < 1e-4, "{kind}: a closed box");
        }
    }

    /// Two triangles of a square with UVs (the second triangle's corner at
    /// position 0 has its own UV, a seam), in a red material that has a
    /// texture `tex.png`,
    /// with an embedded picture when `content` is given.
    fn textured_file(content: Option<Vec<u8>>) -> Vec<N> {
        textured_on("DiffuseColor", content, true, vec![])
    }

    /// As [`textured_file`] with the texture connected to the material
    /// property `on`, the UVs left out unless `uvs`, and `extra` material
    /// properties added.
    fn textured_on(on: &'static str, content: Option<Vec<u8>>, uvs: bool, extra: Vec<N>) -> Vec<N> {
        let verts = vec![0., 0., 0., 1., 0., 0., 1., 1., 0., 0., 1., 0.];
        let uv = vec![0.0, 0.0, 1.0, 0.0, 1.0, 1.0, 0.25, 0.0, 0.0, 1.0];
        let mut texture = vec![
            n("Type", vec![P::S("TextureVideoClip")], vec![]),
            n("FileName", vec![P::S("/elsewhere/tex.png")], vec![]),
            n("RelativeFilename", vec![P::S("tex.png")], vec![]),
        ];
        let mut objects = vec![
            n(
                "Geometry",
                vec![P::Id(1000), P::Name("Geometry", "Quad"), P::S("Mesh")],
                vec![
                    n("Vertices", vec![P::Doubles(verts)], vec![]),
                    n("PolygonVertexIndex", vec![P::Ints(vec![0, 1, -3, 0, 2, -4])], vec![]),
                    n(
                        if uvs { "LayerElementUV" } else { "Unused" },
                        vec![P::Int(0)],
                        vec![
                            n("Version", vec![P::Int(101)], vec![]),
                            n("Name", vec![P::S("UVMap")], vec![]),
                            n("MappingInformationType", vec![P::S("ByPolygonVertex")], vec![]),
                            n("ReferenceInformationType", vec![P::S("IndexToDirect")], vec![]),
                            n("UV", vec![P::Doubles(uv)], vec![]),
                            n("UVIndex", vec![P::Ints(vec![0, 1, 2, 3, 2, 4])], vec![]),
                        ],
                    ),
                ],
            ),
            n("Model", vec![P::Id(2000), P::Name("Model", "Quad"), P::S("Mesh")], vec![n("Version", vec![P::Int(232)], vec![])]),
            n(
                "Material",
                vec![P::Id(3000), P::Name("Material", "Red"), P::S("")],
                vec![
                    n("ShadingModel", vec![P::S("phong")], vec![]),
                    n("Properties70", vec![], std::iter::once(prop("DiffuseColor", "Color", vec![P::D(1.0), P::D(0.0), P::D(0.0)])).chain(extra).collect()),
                ],
            ),
        ];
        let mut connections = vec![
            n("C", vec![P::S("OO"), P::Id(1000), P::Id(2000)], vec![]),
            n("C", vec![P::S("OO"), P::Id(2000), P::Id(0)], vec![]),
            n("C", vec![P::S("OO"), P::Id(3000), P::Id(2000)], vec![]),
            n("C", vec![P::S("OP"), P::Id(4000), P::Id(3000), P::S(on)], vec![]),
        ];
        if let Some(bytes) = content {
            // The embedded picture is not the sidecar file, so a test can
            // tell which one was used.
            objects.push(n(
                "Video",
                vec![P::Id(5000), P::Name("Video", "Clip"), P::S("Clip")],
                vec![
                    n("Type", vec![P::S("Clip")], vec![]),
                    n("RelativeFilename", vec![P::S("tex.png")], vec![]),
                    n("Content", vec![P::Bytes(bytes)], vec![]),
                ],
            ));
            connections.push(n("C", vec![P::S("OO"), P::Id(5000), P::Id(4000)], vec![]));
        }
        texture.push(n("Version", vec![P::Int(202)], vec![]));
        objects.push(n("Texture", vec![P::Id(4000), P::Name("Texture", "Tex"), P::S("")], texture));
        vec![header(), settings(1, 1.0), n("Objects", vec![], objects), n("Connections", vec![], connections)]
    }

    #[test]
    fn uvs_and_a_sidecar_texture_are_read() {
        let png = super::texture::tests::png_2x2();
        let side = |name: &str| (name == "tex.png").then(|| png.clone());
        let m = parse(&ascii(&textured_file(None)), &side).unwrap();
        let mesh = &m.meshes[0];
        // Six corners: the generated flat normals already split the shared
        // positions, so the seam is checked through the UVs below.
        assert_eq!(mesh.positions.len(), 6);
        let uvs = mesh.uvs.as_ref().expect("uvs");
        assert_eq!(uvs.len(), 6);
        // Position 0 carries both its UVs, one per triangle.
        let origin: Vec<[f32; 2]> = (0..6).filter(|&i| close(mesh.positions[i], [0.0; 3])).map(|i| uvs[i]).collect();
        assert!(origin.contains(&[0.0, 1.0]) && origin.contains(&[0.25, 1.0]), "{origin:?}");
        // v is flipped to picture space.
        let at = |p: V3| mesh.positions.iter().position(|q| close(*q, p)).map(|i| uvs[i]);
        assert_eq!(at([1.0, 1.0, 0.0]), Some([1.0, 0.0]));
        assert_eq!(at([1.0, 0.0, 0.0]), Some([1.0, 1.0]));
        assert!(uvs.contains(&[0.0, 0.0]));
        let tex = mesh.texture.as_ref().expect("texture");
        assert_eq!((tex.image.width, tex.image.height), (2, 2));
        assert_eq!(tex.tint, [1.0; 3]);
        let mat = mesh.material.as_ref().unwrap();
        assert_eq!(mat.color, [1.0, 0.0, 0.0]);
    }

    #[test]
    fn a_missing_texture_keeps_the_colour() {
        let m = parse(&ascii(&textured_file(None)), &|_| None).unwrap();
        let mesh = &m.meshes[0];
        assert!(mesh.texture.is_none());
        assert!(mesh.uvs.is_some(), "UVs are still read");
        assert_eq!(mesh.material.as_ref().unwrap().color, [1.0, 0.0, 0.0]);
        // Bytes that are not a picture are the same as a missing file.
        let m = parse(&ascii(&textured_file(None)), &|_| Some(b"nope".to_vec())).unwrap();
        assert!(m.meshes[0].texture.is_none());
        // A mesh without UVs has no texture to lay on.
        let m = parse(&ascii(&box_file(1, 1.0, 0.0, 1.0)), &|_| Some(super::texture::tests::png_2x2())).unwrap();
        assert!(m.meshes[0].uvs.is_none() && m.meshes[0].texture.is_none());
    }

    #[test]
    fn bump_and_normal_sidecar_maps_are_read() {
        let png = super::texture::tests::png_2x2();
        let side = |name: &str| (name == "tex.png").then(|| png.clone());
        for (on, want_normal) in [("Bump", false), ("NormalMap", true)] {
            let m = parse(&ascii(&textured_on(on, None, true, vec![])), &side).unwrap();
            let mesh = &m.meshes[0];
            let s = &mesh.surface;
            assert!(mesh.texture.is_none(), "{on}: not the base map");
            let got = if want_normal { &s.normal_map } else { &s.bump_map };
            assert_eq!(got.as_ref().map(|t| t.image.width), Some(2), "{on}");
            assert!(if want_normal { s.bump_map.is_none() } else { s.normal_map.is_none() }, "{on}");
            assert!(s.emissive_map.is_none() && s.emissive == [0.0; 3] && !s.blend, "{on}");
            assert!(mesh.uvs.is_some());
        }
    }

    #[test]
    fn an_embedded_normal_map_is_read_from_binary() {
        let embedded = super::texture::tests::png(3, 1, [9, 8, 7, 255]);
        let m = parse(&binary(&textured_on("NormalMap", Some(embedded), true, vec![])), &|_| None).unwrap();
        let tex = m.meshes[0].surface.normal_map.as_ref().expect("normal map");
        assert_eq!((tex.image.width, tex.image.height), (3, 1));
    }

    #[test]
    fn opacity_and_transparency_textures_set_blend() {
        let opacity = |v: f64| vec![prop("Opacity", "double", vec![P::D(v)])];
        let blend = |file: Vec<N>| parse(&ascii(&file), &|_| None).unwrap().meshes[0].surface.blend;
        assert!(blend(textured_on("DiffuseColor", None, true, opacity(0.5))));
        assert!(!blend(textured_on("DiffuseColor", None, true, opacity(1.0))));
        assert!(!blend(textured_on("DiffuseColor", None, true, vec![])));
        // A TransparencyFactor value alone is not opacity: exporters write 1
        // on opaque materials.
        let factor = vec![prop("TransparencyFactor", "double", vec![P::D(1.0)])];
        assert!(!blend(textured_on("DiffuseColor", None, true, factor)));
        // A transparency texture alone, with no picture to read.
        assert!(blend(textured_on("TransparencyFactor", None, true, vec![])));
        assert!(blend(textured_on("TransparentColor", None, true, vec![])));
        let png = super::texture::tests::png_2x2();
        let m = parse(&ascii(&textured_on("TransparencyFactor", None, true, vec![])), &|_| Some(png.clone())).unwrap();
        assert!(m.meshes[0].surface.blend && m.meshes[0].texture.is_none(), "the transparency picture is not drawn");
        assert_eq!(m.meshes[0].material.as_ref().unwrap().opacity, 1.0);
    }

    #[test]
    fn a_missing_or_bad_map_stays_none() {
        for side in [&(|_: &str| None) as &dyn Fn(&str) -> Option<Vec<u8>>, &|_: &str| Some(b"nope".to_vec())] {
            let m = parse(&ascii(&textured_on("Bump", None, true, vec![])), side).unwrap();
            assert_eq!(m.meshes.len(), 1);
            assert!(m.meshes[0].surface.bump_map.is_none() && m.meshes[0].uvs.is_some());
            assert_eq!(m.meshes[0].material.as_ref().unwrap().color, [1.0, 0.0, 0.0]);
        }
    }

    #[test]
    fn maps_without_uvs_are_dropped() {
        let png = super::texture::tests::png_2x2();
        for on in ["Bump", "NormalMap"] {
            let m = parse(&ascii(&textured_on(on, None, false, vec![])), &|_| Some(png.clone())).unwrap();
            let mesh = &m.meshes[0];
            assert!(mesh.uvs.is_none() && mesh.surface.bump_map.is_none() && mesh.surface.normal_map.is_none(), "{on}");
        }
    }

    #[test]
    fn an_embedded_picture_wins_over_the_sidecar() {
        let embedded = super::texture::tests::png(3, 1, [9, 8, 7, 255]);
        let sidecar = super::texture::tests::png_2x2();
        let side = |name: &str| (name == "tex.png").then(|| sidecar.clone());
        let m = parse(&binary(&textured_file(Some(embedded))), &side).unwrap();
        let tex = m.meshes[0].texture.as_ref().expect("texture");
        assert_eq!((tex.image.width, tex.image.height), (3, 1));
        // The binary file alone, with no sidecar, still textures.
        let m = parse(&binary(&textured_file(None)), &side).unwrap();
        assert_eq!(m.meshes[0].texture.as_ref().unwrap().image.width, 2);
    }

    #[test]
    fn unit_scale_and_up_axis_are_converted() {
        // Metres (100 cm per unit): a 1-unit box is 100 cm.
        let m = parse(&binary(&box_file(1, 100.0, 0.0, 1.0)), &|_| None).unwrap();
        assert!(close(size(&m), [100.0, 100.0, 100.0]), "{:?}", size(&m));
        // Millimetres.
        let m = parse(&ascii(&box_file(1, 0.1, 0.0, 1.0)), &|_| None).unwrap();
        assert!(close(size(&m), [0.1, 0.1, 0.1]), "{:?}", size(&m));
        // Z up: the box's depth (along Z in the file) becomes its height.
        let m = parse(&ascii(&box_file(2, 1.0, 0.0, 3.0)), &|_| None).unwrap();
        assert!(close(size(&m), [1.0, 3.0, 1.0]), "{:?}", size(&m));
    }

    #[test]
    fn files_load_by_extension_and_get_a_thumbnail() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("Box.FBX");
        std::fs::write(&path, binary(&box_file(1, 1.0, 0.0, 1.0))).unwrap();
        assert_eq!(super::super::load(&path, "FBX").unwrap().triangle_count(), 12);
        let img = super::super::raster::thumbnail(&path, "fbx").expect("a drawn thumbnail");
        assert!(img.pixels().any(|p| p[3] == 255 && p[0] > p[1]), "drawn in the red material");
    }

    #[test]
    fn empty_scene_is_an_error_not_a_panic() {
        let e = parse(&ascii(&[header(), settings(1, 1.0)]), &|_| None).unwrap_err();
        assert!(e.0.contains("no triangles"), "{e}");
        assert!(parse(&binary(&[header(), settings(1, 1.0)]), &|_| None).is_err());
    }

    #[test]
    fn corrupt_and_truncated_files_fail_cleanly() {
        assert!(parse(b"", &|_| None).is_err());
        assert!(parse(b"not an fbx at all", &|_| None).is_err());
        // An OBJ is not read as FBX.
        assert!(parse(b"v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n", &|_| None).is_err());
        let whole = binary(&box_file(1, 1.0, 0.0, 1.0));
        for cut in [30, whole.len() / 3, whole.len() / 2, whole.len() - 20] {
            assert!(parse(&whole[..cut], &|_| None).is_err(), "cut at {cut}");
        }
        // An array claiming four billion doubles fails quickly.
        let mut huge = whole.clone();
        let at = huge.windows(4).position(|w| w == b"Vert").unwrap() + 8;
        assert_eq!(huge[at], b'd');
        huge[at + 1..at + 5].copy_from_slice(&u32::MAX.to_le_bytes());
        let t = std::time::Instant::now();
        assert!(parse(&huge, &|_| None).is_err());
        assert!(t.elapsed() < std::time::Duration::from_secs(5));
        // Random bytes after a valid header.
        let mut junk = whole[..27].to_vec();
        let mut x = 0x2545_f491_u32;
        junk.extend((0..4096).map(|_| {
            x ^= x << 13;
            x ^= x >> 17;
            x ^= x << 5;
            x as u8
        }));
        assert!(parse(&junk, &|_| None).is_err());
    }
}