@woosh/meep-engine 3.1.0 → 3.3.0

package/src/shade/renderer/loader/usd/usd_build_scene.js

@@ -1,658 +1,658 @@
-/**
- * Converts the unified `specsByPath` intermediate representation into
- * the engine's scene graph (Node3D, Mesh, StandardShadeMaterial).
- *
- * This module is format-agnostic — it consumes the same specsByPath
- * dictionary regardless of whether the source was USDA, USDC, or USDZ.
- *
- * @see https://openusd.org/release/glossary.html#usdglossary-prim — Prim concept
- * @see https://openusd.org/release/glossary.html#usdglossary-attribute — Attribute concept
- * @see https://openusd.org/release/api/class_usd_geom_mesh.html — UsdGeomMesh schema
- * @see https://openusd.org/release/api/class_usd_preview_surface.html — UsdPreviewSurface
- *
- * @module usd_build_scene
- */
-
-import { clamp01 } from "../../../../core/math/clamp01.js";
-import { m4_allocate } from "../../../../core/geom/3d/mat4/m4_allocate.js";
-import { m4_make_rotation_x } from "../../../../core/geom/3d/mat4/m4_make_rotation_x.js";
-import { m4_make_scale } from "../../../../core/geom/3d/mat4/m4_make_scale.js";
-import { m4_multiply } from "../../../../core/geom/3d/mat4/m4_multiply.js";
-import { Attribute } from "../../geometry/Attribute.js";
-import { Geometry } from "../../geometry/Geometry.js";
-import { meshlet_geometry_build_from_geometry } from "../../geometry/meshlet_geometry_build_from_geometry.js";
-import { StandardAttributes } from "../../geometry/StandardAttributes.js";
-import { normalize_attribute } from "../../geometry/util/normalize_attribute.js";
-import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
-import { StandardShadeMaterial } from "../../material/StandardShadeMaterial.js";
-import { TransparencyMode } from "../../material/TransparencyMode.js";
-import { Mesh } from "../../scene/Mesh.js";
-import { Node3D } from "../../scene/Node3D.js";
-import { usd_compose_transform } from "./usd_compose_transform.js";
-import { usd_expand_face_varying, usd_triangulate } from "./usd_triangulate.js";
-
-
-/**
- * @typedef {Object} UsdBuildOptions
- * @property {Map<string, Uint8Array>} [assetFiles] - Map of relative paths to file data (from USDZ)
- * @property {import("./UsdExtensionRegistry.js").UsdExtensionRegistry} [extensions] - Extension registry consulted per prim
- */
-
-
-/**
- * Build engine Node3D trees from the parsed specsByPath.
- *
- * Stage metadata (upAxis, metersPerUnit) is consumed here and baked
- * into a root correction transform, so the consumer receives a Y-up,
- * meters-scale scene.
- *
- * @param {Object.<string, { specType: number, fields: Object }>} specs_by_path
- * @param {UsdBuildOptions} [options]
- * @returns {Node3D[]} Root-level nodes
- */
-export function usd_build_scene(specs_by_path, options = {}) {
-
-    const root_spec = specs_by_path["/"];
-    const root_fields = root_spec ? root_spec.fields : {};
-
-    // --- Stage metadata ---
-    // @see https://openusd.org/release/api/class_usd_geom_set_stage_up_axis.html
-    const up_axis = root_fields.upAxis || "Y";
-    // @see https://openusd.org/release/api/class_usd_geom_linear_units.html
-    const meters_per_unit = root_fields.metersPerUnit ?? 1.0;
-
-    // Build a root correction matrix that converts the source coordinate
-    // system to the engine's convention (Y-up, meters).
-    const correction = m4_allocate();
-
-    if (up_axis === "Z") {
-        // Z-up → Y-up: rotate -90° around X
-        // @see https://openusd.org/release/api/group___usd_geom_up_axis__group.html
-        m4_make_rotation_x(correction, -Math.PI / 2);
-    }
-
-    if (meters_per_unit !== 1.0) {
-        // NOTE: float64 metersPerUnit → float32 scale factor.
-        // Precision loss point for very small or very large unit ratios.
-        const s = meters_per_unit;
-
-        const scale = m4_make_scale(m4_allocate(), [s, s, s]);
-
-        m4_multiply(correction, correction, scale);
-    }
-
-    // --- Resolve materials ---
-    const materials = build_materials(specs_by_path);
-
-    // Extension registry (if provided)
-    const registry = options.extensions || null;
-
-    // --- Build prim hierarchy ---
-    const prim_children = root_fields.primChildren || [];
-    const roots = [];
-
-    // Check if correction is non-identity
-    const has_correction = up_axis === "Z" || meters_per_unit !== 1.0;
-
-    for (const child_name of prim_children) {
-        const child_path = "/" + child_name;
-        const node = build_prim(child_path, specs_by_path, materials, correction, options, registry);
-
-        if (node !== null) {
-            // Bake correction into root nodes' local transforms so that
-            // updateMatrices() propagates it correctly to global transforms
-            if (has_correction) {
-                const corrected = m4_allocate();
-                m4_multiply(corrected, correction, node.transform_local.matrix);
-                node.transform_local.fromMatrix(corrected);
-            }
-
-            roots.push(node);
-        }
-    }
-
-    // Propagate local transforms → global transforms and compute bounds
-    for (const root of roots) {
-        root.updateMatrices();
-    }
-
-    return roots;
-}
-
-
-/**
- * Recursively build a Node3D from a prim spec.
- *
- * @param {string} path
- * @param {Object} specs_by_path
- * @param {Map<string, StandardShadeMaterial>} materials
- * @param {mat4} parent_world_transform
- * @param {UsdBuildOptions} options
- * @param {import("./UsdExtensionRegistry.js").UsdExtensionRegistry|null} registry
- * @returns {Node3D|null}
- */
-function build_prim(path, specs_by_path, materials, parent_world_transform, options, registry) {
-
-    const spec = specs_by_path[path];
-
-    if (!spec || spec.specType !== 6) {
-        return null;
-    }
-
-    const fields = spec.fields;
-    const type_name = fields.typeName || "";
-    const prim_name = path.split("/").pop();
-
-    // --- Extension hook: let registered extensions handle custom prim types ---
-    if (registry) {
-        for (const ext of registry.values()) {
-            if (ext.processPrim) {
-                const result = ext.processPrim(path, fields, { specs_by_path, materials, options });
-
-                if (result !== null && result !== undefined) {
-                    return result;
-                }
-            }
-        }
-    }
-
-    // Compose local transform from xformOpOrder
-    // @see https://openusd.org/release/api/class_usd_geom_xformable.html#details
-    const local_transform = usd_compose_transform(fields, specs_by_path, path);
-
-    // Compute world transform
-    const world_transform = m4_allocate();
-    m4_multiply(world_transform, parent_world_transform, local_transform);
-
-    // Attempt to build a Mesh if this is a UsdGeomMesh
-    // @see https://openusd.org/release/api/class_usd_geom_mesh.html
-    if (type_name === "Mesh") {
-        return build_mesh_node(path, prim_name, fields, specs_by_path, materials, local_transform, world_transform, options, registry);
-    }
-
-    // Warn on unrecognized prim types that carry data we silently ignore
-    if (type_name !== "" && type_name !== "Xform" && type_name !== "Scope" && type_name !== "Material" && type_name !== "Shader") {
-        console.warn(`[USD] Unhandled prim type "${type_name}" at ${path}, treating as group node`);
-    }
-
-    // For Xform, Scope, and other grouping types, create a Node3D container
-    const node = new Node3D();
-    node.name = prim_name;
-    node.transform_local.fromMatrix(local_transform);
-
-    // Recurse into children
-    const children = fields.primChildren || [];
-
-    for (const child_name of children) {
-        const child_path = path + "/" + child_name;
-        const child = build_prim(child_path, specs_by_path, materials, world_transform, options, registry);
-
-        if (child !== null) {
-            node.addChild(child);
-        }
-    }
-
-    return node;
-}
-
-
-/**
- * Build a Mesh node from a UsdGeomMesh prim.
- *
- * @see https://openusd.org/release/api/class_usd_geom_mesh.html
- *
- * UsdGeomMesh topology is defined by:
- * - `faceVertexCounts`: int[] — number of vertices per face
- * - `faceVertexIndices`: int[] — flattened vertex indices
- * - `points`: point3f[] — vertex positions
- *
- * Primvars (per-vertex/per-face-varying data):
- * - `primvars:st` / `primvars:st:indices`: texCoord2f[] — UV coordinates
- * - `normals`: normal3f[] — can be vertex or faceVarying interpolation
- *
- * @param {string} path
- * @param {string} name
- * @param {Object} fields
- * @param {Object} specs_by_path
- * @param {Map<string, StandardShadeMaterial>} materials
- * @param {mat4} local_transform
- * @param {mat4} world_transform
- * @param {UsdBuildOptions} options
- * @param {import("./UsdExtensionRegistry.js").UsdExtensionRegistry|null} registry
- * @returns {Mesh|Node3D}
- */
-function build_mesh_node(path, name, fields, specs_by_path, materials, local_transform, world_transform, options, registry) {
-
-    // --- Read topology ---
-    const face_vertex_counts = read_attr(specs_by_path, path, "faceVertexCounts");
-    const face_vertex_indices = read_attr(specs_by_path, path, "faceVertexIndices");
-    const points_raw = read_attr(specs_by_path, path, "points");
-
-    if (!face_vertex_counts || !face_vertex_indices || !points_raw) {
-        // Not enough data to build a mesh — return as empty node
-        const node = new Node3D();
-        node.name = name;
-        node.transform_local.fromMatrix(local_transform);
-        return node;
-    }
-
-    // Validate that vertex indices are within bounds
-    const vertex_count = points_raw.length / 3;
-    for (let i = 0; i < face_vertex_indices.length; i++) {
-        if (face_vertex_indices[i] >= vertex_count || face_vertex_indices[i] < 0) {
-            console.warn(
-                `[USD] faceVertexIndices[${i}] = ${face_vertex_indices[i]} is out of bounds ` +
-                `(vertex count: ${vertex_count}) at ${path}`
-            );
-            break; // Only warn once per mesh
-        }
-    }
-
-    // points may be float64 from USDA; downcast to float32
-    // NOTE: Precision loss point — positions far from origin lose sub-mm precision
-    const points = ensure_float32(points_raw);
-
-    // --- Triangulate ---
-    // @see https://openusd.org/release/api/class_usd_geom_mesh.html#details
-    // USD meshes can have arbitrary polygons; we fan-triangulate them.
-    const { indices, face_map } = usd_triangulate(face_vertex_counts, face_vertex_indices);
-
-    // --- Gather per-vertex attributes ---
-    // Any faceVarying primvar forces flat (de-indexed) topology; the flag is
-    // tracked explicitly so every per-point attribute is re-expanded through
-    // the triangulated indices, regardless of attribute order.
-    let deindexed = false;
-
-    // Normals
-    // @see https://openusd.org/release/glossary.html#usdglossary-interpolation
-    let normal_data = null;
-    let normal_is_per_point = false;
-
-    const normals_raw = read_attr(specs_by_path, path, "normals");
-
-    if (normals_raw) {
-        const normals = ensure_float32(normals_raw);
-        const normals_interp = read_attr_interpolation(specs_by_path, path, "normals");
-
-        if (normals_interp === "faceVarying") {
-            // faceVarying: one value per face-vertex, re-index after triangulation
-            normal_data = usd_expand_face_varying(face_vertex_counts, normals, 3);
-            deindexed = true;
-        } else {
-            // vertex interpolation: one normal per point
-            normal_data = normals;
-            normal_is_per_point = true;
-        }
-    }
-
-    // UVs (primvars:st)
-    // @see https://openusd.org/release/api/class_usd_geom_primvars_a_p_i.html
-    let uv_data = null;
-    let uv_is_per_point = false;
-
-    const st_raw = read_attr(specs_by_path, path, "primvars:st");
-
-    if (st_raw) {
-        let st = ensure_float32(st_raw);
-        const st_indices = read_attr(specs_by_path, path, "primvars:st:indices");
-        const st_interp = read_attr_interpolation(specs_by_path, path, "primvars:st");
-
-        if (st_indices) {
-            // Indexed UVs — expand using the UV index array
-            st = expand_by_indices(st, st_indices, 2);
-        }
-
-        if (st_interp === "faceVarying") {
-            uv_data = usd_expand_face_varying(face_vertex_counts, st, 2);
-            deindexed = true;
-        } else {
-            uv_data = st;
-            uv_is_per_point = true;
-        }
-    }
-
-    // --- Assemble geometry ---
-    const geometry = new Geometry();
-
-    if (deindexed) {
-        // Flat topology: expand positions and every per-point attribute
-        // through the triangulated indices so all attributes agree
-        const position_data = expand_indexed_to_flat(indices, points, 3);
-        geometry.addAttribute(normalize_attribute(Attribute.from(position_data, 3, StandardAttributes.Position)));
-
-        if (normal_data !== null) {
-            const flat_normals = normal_is_per_point
-                ? expand_indexed_to_flat(indices, normal_data, 3)
-                : normal_data;
-
-            geometry.addAttribute(normalize_attribute(Attribute.from(flat_normals, 3, StandardAttributes.Normal)));
-        }
-
-        if (uv_data !== null) {
-            const flat_uvs = uv_is_per_point
-                ? expand_indexed_to_flat(indices, uv_data, 2)
-                : uv_data;
-
-            geometry.addAttribute(normalize_attribute(Attribute.from(flat_uvs, 2, StandardAttributes.TextureCoordinates0)));
-        }
-    } else {
-        // Indexed topology: all attributes are per-point
-        geometry.addAttribute(normalize_attribute(Attribute.from(points, 3, StandardAttributes.Position)));
-        geometry.index = Attribute.from(indices, 1, "index");
-
-        if (normal_data !== null) {
-            geometry.addAttribute(normalize_attribute(Attribute.from(normal_data, 3, StandardAttributes.Normal)));
-        }
-
-        if (uv_data !== null) {
-            geometry.addAttribute(normalize_attribute(Attribute.from(uv_data, 2, StandardAttributes.TextureCoordinates0)));
-        }
-    }
-
-    // --- Resolve material binding ---
-    // @see https://openusd.org/release/api/class_usd_shade_material_binding_a_p_i.html
-    const binding_path = path + ".material:binding";
-    const binding_spec = specs_by_path[binding_path];
-    let material = new StandardShadeMaterial();
-
-    if (binding_spec && binding_spec.fields.targetPaths) {
-        const mat_path = binding_spec.fields.targetPaths[0];
-
-        if (materials.has(mat_path)) {
-            material = materials.get(mat_path);
-        } else {
-            console.warn(`[USD] Material binding at ${path} references "${mat_path}" which was not found`);
-        }
-    }
-
-    // Handle doubleSided
-    // @see https://openusd.org/release/api/class_usd_geom_mesh.html
-    // doubleSided is a per-gprim flag; the bound material is shared between
-    // meshes and must not be mutated — clone it for this mesh instead
-    const double_sided = read_attr(specs_by_path, path, "doubleSided");
-    if (double_sided === true && material.draw_side !== ShadeDrawSide.Double) {
-        material = material.clone();
-        material.draw_side = ShadeDrawSide.Double;
-    }
-
-    // --- Build engine Mesh ---
-    const meshlet_geo = meshlet_geometry_build_from_geometry(geometry);
-
-    const mesh = new Mesh();
-    mesh.name = name;
-    mesh.geometry = meshlet_geo;
-    mesh.material = material;
-    mesh.transform_local.fromMatrix(local_transform);
-
-    // Recurse into children (mesh prims can have child prims)
-    const children = fields.primChildren || [];
-
-    if (children.length > 0) {
-        for (const child_name of children) {
-            const child_path = path + "/" + child_name;
-            const child = build_prim(child_path, specs_by_path, materials, world_transform, options, registry);
-
-            if (child !== null) {
-                mesh.addChild(child);
-            }
-        }
-    }
-
-    return mesh;
-}
-
-
-// =============================================================================
-// Material Building
-// =============================================================================
-
-/**
- * Build materials from UsdPreviewSurface shader prims.
- *
- * @see https://openusd.org/release/spec_usdpreviewsurface.html — UsdPreviewSurface specification
- *
- * @param {Object} specs_by_path
- * @returns {Map<string, StandardShadeMaterial>}
- */
-function build_materials(specs_by_path) {
-
-    /** @type {Map<string, StandardShadeMaterial>} */
-    const result = new Map();
-
-    for (const path in specs_by_path) {
-        const spec = specs_by_path[path];
-
-        if (spec.specType !== 6) continue;
-
-        const type_name = spec.fields.typeName;
-
-        if (type_name !== "Material") continue;
-
-        const material = build_material(path, specs_by_path);
-        result.set(path, material);
-    }
-
-    return result;
-}
-
-
-/**
- * Build a single StandardShadeMaterial from a UsdShadeMaterial prim.
- *
- * Walks the material's shader network to find UsdPreviewSurface inputs.
- *
- * @see https://openusd.org/release/spec_usdpreviewsurface.html
- *
- * @param {string} mat_path
- * @param {Object} specs_by_path
- * @returns {StandardShadeMaterial}
- */
-function build_material(mat_path, specs_by_path) {
-
-    const material = new StandardShadeMaterial();
-    material.name = mat_path.split("/").pop();
-
-    // Find the UsdPreviewSurface shader child
-    const mat_spec = specs_by_path[mat_path];
-    const children = mat_spec.fields.primChildren || [];
-
-    for (const child_name of children) {
-        const shader_path = mat_path + "/" + child_name;
-        const shader_spec = specs_by_path[shader_path];
-
-        if (!shader_spec || shader_spec.specType !== 6) continue;
-        if (shader_spec.fields.typeName !== "Shader") continue;
-
-        // Check info:id for UsdPreviewSurface
-        const info_id = read_attr(specs_by_path, shader_path, "info:id");
-
-        if (info_id !== "UsdPreviewSurface") continue;
-
-        // --- Map UsdPreviewSurface inputs to engine material ---
-        // @see https://openusd.org/release/spec_usdpreviewsurface.html#inputs
-
-        // Diffuse color
-        const diffuse = read_attr(specs_by_path, shader_path, "inputs:diffuseColor");
-        if (diffuse && Array.isArray(diffuse)) {
-            material.diffuse_color.setRGB(diffuse[0], diffuse[1], diffuse[2]);
-        }
-
-        // Metallic
-        const metallic = read_attr(specs_by_path, shader_path, "inputs:metallic");
-        if (typeof metallic === "number") {
-            material.metallic_factor = clamp01(metallic);
-        }
-
-        // Roughness
-        const roughness = read_attr(specs_by_path, shader_path, "inputs:roughness");
-        if (typeof roughness === "number") {
-            material.roughness_factor = clamp01(roughness);
-        }
-
-        // Opacity
-        const opacity = read_attr(specs_by_path, shader_path, "inputs:opacity");
-        if (typeof opacity === "number" && opacity < 1.0) {
-            material.diffuse_color.a = clamp01(opacity);
-            material.transparency_mode = TransparencyMode.Transparent;
-        }
-
-        // Emissive color
-        const emissive = read_attr(specs_by_path, shader_path, "inputs:emissiveColor");
-        if (emissive && Array.isArray(emissive)) {
-            const intensity = Math.max(emissive[0], emissive[1], emissive[2]);
-            if (intensity > 0) {
-                material.emissive_factor.setRGB(emissive[0], emissive[1], emissive[2]);
-            }
-        }
-
-        break; // Only use the first UsdPreviewSurface
-    }
-
-    return material;
-}
-
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-/**
- * Read an attribute's default value from specsByPath.
- *
- * @param {Object} specs_by_path
- * @param {string} prim_path
- * @param {string} attr_name
- * @returns {*}
- */
-function read_attr(specs_by_path, prim_path, attr_name) {
-
-    const spec = specs_by_path[prim_path + "." + attr_name];
-
-    if (!spec || !spec.fields) return undefined;
-
-    // USD value resolution: timeSamples win over default when both are authored
-    // @see https://openusd.org/release/glossary.html#usdglossary-valueresolution
-    if (spec.fields.timeSamples && spec.fields.timeSamples.values.length > 0) {
-        return spec.fields.timeSamples.values[0];
-    }
-
-    if (spec.fields.default !== undefined) {
-        return spec.fields.default;
-    }
-
-    return undefined;
-}
-
-
-/**
- * Read interpolation metadata for an attribute.
- *
- * @see https://openusd.org/release/glossary.html#usdglossary-interpolation
- *
- * @param {Object} specs_by_path
- * @param {string} prim_path
- * @param {string} attr_name
- * @returns {string} "vertex" | "faceVarying" | "uniform" | "constant"
- */
-function read_attr_interpolation(specs_by_path, prim_path, attr_name) {
-
-    const spec = specs_by_path[prim_path + "." + attr_name];
-
-    if (spec && spec.fields && spec.fields.interpolation) {
-        return spec.fields.interpolation;
-    }
-
-    // Default interpolation for most geometry attributes
-    return "vertex";
-}
-
-
-/**
- * Ensure data is Float32Array. Downcasts Float64Array if needed.
- *
- * NOTE: Precision loss point — float64 → float32 conversion.
- *
- * @param {number[]|Float32Array|Float64Array} data
- * @returns {Float32Array}
- */
-function ensure_float32(data) {
-
-    if (data instanceof Float32Array) {
-        return data;
-    }
-
-    return new Float32Array(data);
-}
-
-
-/**
- * Expand indexed data using an index array.
- *
- * @param {Float32Array} data - Source data (item_size per element)
- * @param {number[]|Int32Array} index_array - Index into data
- * @param {number} item_size - Components per element
- * @returns {Float32Array}
- */
-function expand_by_indices(data, index_array, item_size) {
-
-    const result = new Float32Array(index_array.length * item_size);
-
-    for (let i = 0; i < index_array.length; i++) {
-        const src = index_array[i] * item_size;
-
-        for (let c = 0; c < item_size; c++) {
-            result[i * item_size + c] = data[src + c];
-        }
-    }
-
-    return result;
-}
-
-
-/**
- * Expand indexed vertex data to flat (un-indexed) arrays.
- *
- * @param {Uint32Array} indices
- * @param {Float32Array} positions - Flat positions (3 per vertex)
- * @param {number} item_size
- * @returns {Float32Array}
- */
-function expand_indexed_to_flat(indices, positions, item_size) {
-
-    const result = new Float32Array(indices.length * item_size);
-
-    for (let i = 0; i < indices.length; i++) {
-        const src = indices[i] * item_size;
-
-        for (let c = 0; c < item_size; c++) {
-            result[i * item_size + c] = positions[src + c];
-        }
-    }
-
-    return result;
-}
-
-
-/**
- * Replace geometry positions with expanded (un-indexed) data and
- * optionally set normals.
- *
- * @param {Geometry} geometry
- * @param {Float32Array} expanded_positions
- * @param {Float32Array|null} expanded_normals
- */
-function replace_geometry_positions(geometry, expanded_positions, expanded_normals) {
-
-    // Remove index and replace positions
-    geometry.index = null;
-
-    const pos_attr = Attribute.from(expanded_positions, 3, StandardAttributes.Position);
-    geometry.removeAttribute(StandardAttributes.Position);
-    geometry.addAttribute(normalize_attribute(pos_attr));
-
-    if (expanded_normals) {
-        const normal_attr = Attribute.from(expanded_normals, 3, StandardAttributes.Normal);
-        geometry.removeAttribute(StandardAttributes.Normal);
-        geometry.addAttribute(normalize_attribute(normal_attr));
-    }
-}
+/**
+ * Converts the unified `specsByPath` intermediate representation into
+ * the engine's scene graph (Node3D, Mesh, StandardShadeMaterial).
+ *
+ * This module is format-agnostic — it consumes the same specsByPath
+ * dictionary regardless of whether the source was USDA, USDC, or USDZ.
+ *
+ * @see https://openusd.org/release/glossary.html#usdglossary-prim — Prim concept
+ * @see https://openusd.org/release/glossary.html#usdglossary-attribute — Attribute concept
+ * @see https://openusd.org/release/api/class_usd_geom_mesh.html — UsdGeomMesh schema
+ * @see https://openusd.org/release/api/class_usd_preview_surface.html — UsdPreviewSurface
+ *
+ * @module usd_build_scene
+ */
+
+import { clamp01 } from "../../../../core/math/clamp01.js";
+import { m4_allocate } from "../../../../core/geom/3d/mat4/m4_allocate.js";
+import { m4_make_rotation_x } from "../../../../core/geom/3d/mat4/m4_make_rotation_x.js";
+import { m4_make_scale } from "../../../../core/geom/3d/mat4/m4_make_scale.js";
+import { m4_multiply } from "../../../../core/geom/3d/mat4/m4_multiply.js";
+import { Attribute } from "../../geometry/Attribute.js";
+import { Geometry } from "../../geometry/Geometry.js";
+import { meshlet_geometry_build_from_geometry } from "../../geometry/meshlet_geometry_build_from_geometry.js";
+import { StandardAttributes } from "../../geometry/StandardAttributes.js";
+import { normalize_attribute } from "../../geometry/util/normalize_attribute.js";
+import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../../material/StandardShadeMaterial.js";
+import { TransparencyMode } from "../../material/TransparencyMode.js";
+import { Mesh } from "../../scene/Mesh.js";
+import { Node3D } from "../../scene/Node3D.js";
+import { usd_compose_transform } from "./usd_compose_transform.js";
+import { usd_expand_face_varying, usd_triangulate } from "./usd_triangulate.js";
+
+
+/**
+ * @typedef {Object} UsdBuildOptions
+ * @property {Map<string, Uint8Array>} [assetFiles] - Map of relative paths to file data (from USDZ)
+ * @property {import("./UsdExtensionRegistry.js").UsdExtensionRegistry} [extensions] - Extension registry consulted per prim
+ */
+
+
+/**
+ * Build engine Node3D trees from the parsed specsByPath.
+ *
+ * Stage metadata (upAxis, metersPerUnit) is consumed here and baked
+ * into a root correction transform, so the consumer receives a Y-up,
+ * meters-scale scene.
+ *
+ * @param {Object.<string, { specType: number, fields: Object }>} specs_by_path
+ * @param {UsdBuildOptions} [options]
+ * @returns {Node3D[]} Root-level nodes
+ */
+export function usd_build_scene(specs_by_path, options = {}) {
+
+    const root_spec = specs_by_path["/"];
+    const root_fields = root_spec ? root_spec.fields : {};
+
+    // --- Stage metadata ---
+    // @see https://openusd.org/release/api/class_usd_geom_set_stage_up_axis.html
+    const up_axis = root_fields.upAxis || "Y";
+    // @see https://openusd.org/release/api/class_usd_geom_linear_units.html
+    const meters_per_unit = root_fields.metersPerUnit ?? 1.0;
+
+    // Build a root correction matrix that converts the source coordinate
+    // system to the engine's convention (Y-up, meters).
+    const correction = m4_allocate();
+
+    if (up_axis === "Z") {
+        // Z-up → Y-up: rotate -90° around X
+        // @see https://openusd.org/release/api/group___usd_geom_up_axis__group.html
+        m4_make_rotation_x(correction, -Math.PI / 2);
+    }
+
+    if (meters_per_unit !== 1.0) {
+        // NOTE: float64 metersPerUnit → float32 scale factor.
+        // Precision loss point for very small or very large unit ratios.
+        const s = meters_per_unit;
+
+        const scale = m4_make_scale(m4_allocate(), [s, s, s]);
+
+        m4_multiply(correction, correction, scale);
+    }
+
+    // --- Resolve materials ---
+    const materials = build_materials(specs_by_path);
+
+    // Extension registry (if provided)
+    const registry = options.extensions || null;
+
+    // --- Build prim hierarchy ---
+    const prim_children = root_fields.primChildren || [];
+    const roots = [];
+
+    // Check if correction is non-identity
+    const has_correction = up_axis === "Z" || meters_per_unit !== 1.0;
+
+    for (const child_name of prim_children) {
+        const child_path = "/" + child_name;
+        const node = build_prim(child_path, specs_by_path, materials, correction, options, registry);
+
+        if (node !== null) {
+            // Bake correction into root nodes' local transforms so that
+            // updateMatrices() propagates it correctly to global transforms
+            if (has_correction) {
+                const corrected = m4_allocate();
+                m4_multiply(corrected, correction, node.transform_local.matrix);
+                node.transform_local.fromMatrix(corrected);
+            }
+
+            roots.push(node);
+        }
+    }
+
+    // Propagate local transforms → global transforms and compute bounds
+    for (const root of roots) {
+        root.updateMatrices();
+    }
+
+    return roots;
+}
+
+
+/**
+ * Recursively build a Node3D from a prim spec.
+ *
+ * @param {string} path
+ * @param {Object} specs_by_path
+ * @param {Map<string, StandardShadeMaterial>} materials
+ * @param {mat4} parent_world_transform
+ * @param {UsdBuildOptions} options
+ * @param {import("./UsdExtensionRegistry.js").UsdExtensionRegistry|null} registry
+ * @returns {Node3D|null}
+ */
+function build_prim(path, specs_by_path, materials, parent_world_transform, options, registry) {
+
+    const spec = specs_by_path[path];
+
+    if (!spec || spec.specType !== 6) {
+        return null;
+    }
+
+    const fields = spec.fields;
+    const type_name = fields.typeName || "";
+    const prim_name = path.split("/").pop();
+
+    // --- Extension hook: let registered extensions handle custom prim types ---
+    if (registry) {
+        for (const ext of registry.values()) {
+            if (ext.processPrim) {
+                const result = ext.processPrim(path, fields, { specs_by_path, materials, options });
+
+                if (result !== null && result !== undefined) {
+                    return result;
+                }
+            }
+        }
+    }
+
+    // Compose local transform from xformOpOrder
+    // @see https://openusd.org/release/api/class_usd_geom_xformable.html#details
+    const local_transform = usd_compose_transform(fields, specs_by_path, path);
+
+    // Compute world transform
+    const world_transform = m4_allocate();
+    m4_multiply(world_transform, parent_world_transform, local_transform);
+
+    // Attempt to build a Mesh if this is a UsdGeomMesh
+    // @see https://openusd.org/release/api/class_usd_geom_mesh.html
+    if (type_name === "Mesh") {
+        return build_mesh_node(path, prim_name, fields, specs_by_path, materials, local_transform, world_transform, options, registry);
+    }
+
+    // Warn on unrecognized prim types that carry data we silently ignore
+    if (type_name !== "" && type_name !== "Xform" && type_name !== "Scope" && type_name !== "Material" && type_name !== "Shader") {
+        console.warn(`[USD] Unhandled prim type "${type_name}" at ${path}, treating as group node`);
+    }
+
+    // For Xform, Scope, and other grouping types, create a Node3D container
+    const node = new Node3D();
+    node.name = prim_name;
+    node.transform_local.fromMatrix(local_transform);
+
+    // Recurse into children
+    const children = fields.primChildren || [];
+
+    for (const child_name of children) {
+        const child_path = path + "/" + child_name;
+        const child = build_prim(child_path, specs_by_path, materials, world_transform, options, registry);
+
+        if (child !== null) {
+            node.addChild(child);
+        }
+    }
+
+    return node;
+}
+
+
+/**
+ * Build a Mesh node from a UsdGeomMesh prim.
+ *
+ * @see https://openusd.org/release/api/class_usd_geom_mesh.html
+ *
+ * UsdGeomMesh topology is defined by:
+ * - `faceVertexCounts`: int[] — number of vertices per face
+ * - `faceVertexIndices`: int[] — flattened vertex indices
+ * - `points`: point3f[] — vertex positions
+ *
+ * Primvars (per-vertex/per-face-varying data):
+ * - `primvars:st` / `primvars:st:indices`: texCoord2f[] — UV coordinates
+ * - `normals`: normal3f[] — can be vertex or faceVarying interpolation
+ *
+ * @param {string} path
+ * @param {string} name
+ * @param {Object} fields
+ * @param {Object} specs_by_path
+ * @param {Map<string, StandardShadeMaterial>} materials
+ * @param {mat4} local_transform
+ * @param {mat4} world_transform
+ * @param {UsdBuildOptions} options
+ * @param {import("./UsdExtensionRegistry.js").UsdExtensionRegistry|null} registry
+ * @returns {Mesh|Node3D}
+ */
+function build_mesh_node(path, name, fields, specs_by_path, materials, local_transform, world_transform, options, registry) {
+
+    // --- Read topology ---
+    const face_vertex_counts = read_attr(specs_by_path, path, "faceVertexCounts");
+    const face_vertex_indices = read_attr(specs_by_path, path, "faceVertexIndices");
+    const points_raw = read_attr(specs_by_path, path, "points");
+
+    if (!face_vertex_counts || !face_vertex_indices || !points_raw) {
+        // Not enough data to build a mesh — return as empty node
+        const node = new Node3D();
+        node.name = name;
+        node.transform_local.fromMatrix(local_transform);
+        return node;
+    }
+
+    // Validate that vertex indices are within bounds
+    const vertex_count = points_raw.length / 3;
+    for (let i = 0; i < face_vertex_indices.length; i++) {
+        if (face_vertex_indices[i] >= vertex_count || face_vertex_indices[i] < 0) {
+            console.warn(
+                `[USD] faceVertexIndices[${i}] = ${face_vertex_indices[i]} is out of bounds ` +
+                `(vertex count: ${vertex_count}) at ${path}`
+            );
+            break; // Only warn once per mesh
+        }
+    }
+
+    // points may be float64 from USDA; downcast to float32
+    // NOTE: Precision loss point — positions far from origin lose sub-mm precision
+    const points = ensure_float32(points_raw);
+
+    // --- Triangulate ---
+    // @see https://openusd.org/release/api/class_usd_geom_mesh.html#details
+    // USD meshes can have arbitrary polygons; we fan-triangulate them.
+    const { indices, face_map } = usd_triangulate(face_vertex_counts, face_vertex_indices);
+
+    // --- Gather per-vertex attributes ---
+    // Any faceVarying primvar forces flat (de-indexed) topology; the flag is
+    // tracked explicitly so every per-point attribute is re-expanded through
+    // the triangulated indices, regardless of attribute order.
+    let deindexed = false;
+
+    // Normals
+    // @see https://openusd.org/release/glossary.html#usdglossary-interpolation
+    let normal_data = null;
+    let normal_is_per_point = false;
+
+    const normals_raw = read_attr(specs_by_path, path, "normals");
+
+    if (normals_raw) {
+        const normals = ensure_float32(normals_raw);
+        const normals_interp = read_attr_interpolation(specs_by_path, path, "normals");
+
+        if (normals_interp === "faceVarying") {
+            // faceVarying: one value per face-vertex, re-index after triangulation
+            normal_data = usd_expand_face_varying(face_vertex_counts, normals, 3);
+            deindexed = true;
+        } else {
+            // vertex interpolation: one normal per point
+            normal_data = normals;
+            normal_is_per_point = true;
+        }
+    }
+
+    // UVs (primvars:st)
+    // @see https://openusd.org/release/api/class_usd_geom_primvars_a_p_i.html
+    let uv_data = null;
+    let uv_is_per_point = false;
+
+    const st_raw = read_attr(specs_by_path, path, "primvars:st");
+
+    if (st_raw) {
+        let st = ensure_float32(st_raw);
+        const st_indices = read_attr(specs_by_path, path, "primvars:st:indices");
+        const st_interp = read_attr_interpolation(specs_by_path, path, "primvars:st");
+
+        if (st_indices) {
+            // Indexed UVs — expand using the UV index array
+            st = expand_by_indices(st, st_indices, 2);
+        }
+
+        if (st_interp === "faceVarying") {
+            uv_data = usd_expand_face_varying(face_vertex_counts, st, 2);
+            deindexed = true;
+        } else {
+            uv_data = st;
+            uv_is_per_point = true;
+        }
+    }
+
+    // --- Assemble geometry ---
+    const geometry = new Geometry();
+
+    if (deindexed) {
+        // Flat topology: expand positions and every per-point attribute
+        // through the triangulated indices so all attributes agree
+        const position_data = expand_indexed_to_flat(indices, points, 3);
+        geometry.addAttribute(normalize_attribute(Attribute.from(position_data, 3, StandardAttributes.Position)));
+
+        if (normal_data !== null) {
+            const flat_normals = normal_is_per_point
+                ? expand_indexed_to_flat(indices, normal_data, 3)
+                : normal_data;
+
+            geometry.addAttribute(normalize_attribute(Attribute.from(flat_normals, 3, StandardAttributes.Normal)));
+        }
+
+        if (uv_data !== null) {
+            const flat_uvs = uv_is_per_point
+                ? expand_indexed_to_flat(indices, uv_data, 2)
+                : uv_data;
+
+            geometry.addAttribute(normalize_attribute(Attribute.from(flat_uvs, 2, StandardAttributes.TextureCoordinates0)));
+        }
+    } else {
+        // Indexed topology: all attributes are per-point
+        geometry.addAttribute(normalize_attribute(Attribute.from(points, 3, StandardAttributes.Position)));
+        geometry.index = Attribute.from(indices, 1, "index");
+
+        if (normal_data !== null) {
+            geometry.addAttribute(normalize_attribute(Attribute.from(normal_data, 3, StandardAttributes.Normal)));
+        }
+
+        if (uv_data !== null) {
+            geometry.addAttribute(normalize_attribute(Attribute.from(uv_data, 2, StandardAttributes.TextureCoordinates0)));
+        }
+    }
+
+    // --- Resolve material binding ---
+    // @see https://openusd.org/release/api/class_usd_shade_material_binding_a_p_i.html
+    const binding_path = path + ".material:binding";
+    const binding_spec = specs_by_path[binding_path];
+    let material = new StandardShadeMaterial();
+
+    if (binding_spec && binding_spec.fields.targetPaths) {
+        const mat_path = binding_spec.fields.targetPaths[0];
+
+        if (materials.has(mat_path)) {
+            material = materials.get(mat_path);
+        } else {
+            console.warn(`[USD] Material binding at ${path} references "${mat_path}" which was not found`);
+        }
+    }
+
+    // Handle doubleSided
+    // @see https://openusd.org/release/api/class_usd_geom_mesh.html
+    // doubleSided is a per-gprim flag; the bound material is shared between
+    // meshes and must not be mutated — clone it for this mesh instead
+    const double_sided = read_attr(specs_by_path, path, "doubleSided");
+    if (double_sided === true && material.draw_side !== ShadeDrawSide.Double) {
+        material = material.clone();
+        material.draw_side = ShadeDrawSide.Double;
+    }
+
+    // --- Build engine Mesh ---
+    const meshlet_geo = meshlet_geometry_build_from_geometry(geometry);
+
+    const mesh = new Mesh();
+    mesh.name = name;
+    mesh.geometry = meshlet_geo;
+    mesh.material = material;
+    mesh.transform_local.fromMatrix(local_transform);
+
+    // Recurse into children (mesh prims can have child prims)
+    const children = fields.primChildren || [];
+
+    if (children.length > 0) {
+        for (const child_name of children) {
+            const child_path = path + "/" + child_name;
+            const child = build_prim(child_path, specs_by_path, materials, world_transform, options, registry);
+
+            if (child !== null) {
+                mesh.addChild(child);
+            }
+        }
+    }
+
+    return mesh;
+}
+
+
+// =============================================================================
+// Material Building
+// =============================================================================
+
+/**
+ * Build materials from UsdPreviewSurface shader prims.
+ *
+ * @see https://openusd.org/release/spec_usdpreviewsurface.html — UsdPreviewSurface specification
+ *
+ * @param {Object} specs_by_path
+ * @returns {Map<string, StandardShadeMaterial>}
+ */
+function build_materials(specs_by_path) {
+
+    /** @type {Map<string, StandardShadeMaterial>} */
+    const result = new Map();
+
+    for (const path in specs_by_path) {
+        const spec = specs_by_path[path];
+
+        if (spec.specType !== 6) continue;
+
+        const type_name = spec.fields.typeName;
+
+        if (type_name !== "Material") continue;
+
+        const material = build_material(path, specs_by_path);
+        result.set(path, material);
+    }
+
+    return result;
+}
+
+
+/**
+ * Build a single StandardShadeMaterial from a UsdShadeMaterial prim.
+ *
+ * Walks the material's shader network to find UsdPreviewSurface inputs.
+ *
+ * @see https://openusd.org/release/spec_usdpreviewsurface.html
+ *
+ * @param {string} mat_path
+ * @param {Object} specs_by_path
+ * @returns {StandardShadeMaterial}
+ */
+function build_material(mat_path, specs_by_path) {
+
+    const material = new StandardShadeMaterial();
+    material.name = mat_path.split("/").pop();
+
+    // Find the UsdPreviewSurface shader child
+    const mat_spec = specs_by_path[mat_path];
+    const children = mat_spec.fields.primChildren || [];
+
+    for (const child_name of children) {
+        const shader_path = mat_path + "/" + child_name;
+        const shader_spec = specs_by_path[shader_path];
+
+        if (!shader_spec || shader_spec.specType !== 6) continue;
+        if (shader_spec.fields.typeName !== "Shader") continue;
+
+        // Check info:id for UsdPreviewSurface
+        const info_id = read_attr(specs_by_path, shader_path, "info:id");
+
+        if (info_id !== "UsdPreviewSurface") continue;
+
+        // --- Map UsdPreviewSurface inputs to engine material ---
+        // @see https://openusd.org/release/spec_usdpreviewsurface.html#inputs
+
+        // Diffuse color
+        const diffuse = read_attr(specs_by_path, shader_path, "inputs:diffuseColor");
+        if (diffuse && Array.isArray(diffuse)) {
+            material.diffuse_color.setRGB(diffuse[0], diffuse[1], diffuse[2]);
+        }
+
+        // Metallic
+        const metallic = read_attr(specs_by_path, shader_path, "inputs:metallic");
+        if (typeof metallic === "number") {
+            material.metallic_factor = clamp01(metallic);
+        }
+
+        // Roughness
+        const roughness = read_attr(specs_by_path, shader_path, "inputs:roughness");
+        if (typeof roughness === "number") {
+            material.roughness_factor = clamp01(roughness);
+        }
+
+        // Opacity
+        const opacity = read_attr(specs_by_path, shader_path, "inputs:opacity");
+        if (typeof opacity === "number" && opacity < 1.0) {
+            material.diffuse_color.a = clamp01(opacity);
+            material.transparency_mode = TransparencyMode.Transparent;
+        }
+
+        // Emissive color
+        const emissive = read_attr(specs_by_path, shader_path, "inputs:emissiveColor");
+        if (emissive && Array.isArray(emissive)) {
+            const intensity = Math.max(emissive[0], emissive[1], emissive[2]);
+            if (intensity > 0) {
+                material.emissive_factor.setRGB(emissive[0], emissive[1], emissive[2]);
+            }
+        }
+
+        break; // Only use the first UsdPreviewSurface
+    }
+
+    return material;
+}
+
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Read an attribute's default value from specsByPath.
+ *
+ * @param {Object} specs_by_path
+ * @param {string} prim_path
+ * @param {string} attr_name
+ * @returns {*}
+ */
+function read_attr(specs_by_path, prim_path, attr_name) {
+
+    const spec = specs_by_path[prim_path + "." + attr_name];
+
+    if (!spec || !spec.fields) return undefined;
+
+    // USD value resolution: timeSamples win over default when both are authored
+    // @see https://openusd.org/release/glossary.html#usdglossary-valueresolution
+    if (spec.fields.timeSamples && spec.fields.timeSamples.values.length > 0) {
+        return spec.fields.timeSamples.values[0];
+    }
+
+    if (spec.fields.default !== undefined) {
+        return spec.fields.default;
+    }
+
+    return undefined;
+}
+
+
+/**
+ * Read interpolation metadata for an attribute.
+ *
+ * @see https://openusd.org/release/glossary.html#usdglossary-interpolation
+ *
+ * @param {Object} specs_by_path
+ * @param {string} prim_path
+ * @param {string} attr_name
+ * @returns {string} "vertex" | "faceVarying" | "uniform" | "constant"
+ */
+function read_attr_interpolation(specs_by_path, prim_path, attr_name) {
+
+    const spec = specs_by_path[prim_path + "." + attr_name];
+
+    if (spec && spec.fields && spec.fields.interpolation) {
+        return spec.fields.interpolation;
+    }
+
+    // Default interpolation for most geometry attributes
+    return "vertex";
+}
+
+
+/**
+ * Ensure data is Float32Array. Downcasts Float64Array if needed.
+ *
+ * NOTE: Precision loss point — float64 → float32 conversion.
+ *
+ * @param {number[]|Float32Array|Float64Array} data
+ * @returns {Float32Array}
+ */
+function ensure_float32(data) {
+
+    if (data instanceof Float32Array) {
+        return data;
+    }
+
+    return new Float32Array(data);
+}
+
+
+/**
+ * Expand indexed data using an index array.
+ *
+ * @param {Float32Array} data - Source data (item_size per element)
+ * @param {number[]|Int32Array} index_array - Index into data
+ * @param {number} item_size - Components per element
+ * @returns {Float32Array}
+ */
+function expand_by_indices(data, index_array, item_size) {
+
+    const result = new Float32Array(index_array.length * item_size);
+
+    for (let i = 0; i < index_array.length; i++) {
+        const src = index_array[i] * item_size;
+
+        for (let c = 0; c < item_size; c++) {
+            result[i * item_size + c] = data[src + c];
+        }
+    }
+
+    return result;
+}
+
+
+/**
+ * Expand indexed vertex data to flat (un-indexed) arrays.
+ *
+ * @param {Uint32Array} indices
+ * @param {Float32Array} positions - Flat positions (3 per vertex)
+ * @param {number} item_size
+ * @returns {Float32Array}
+ */
+function expand_indexed_to_flat(indices, positions, item_size) {
+
+    const result = new Float32Array(indices.length * item_size);
+
+    for (let i = 0; i < indices.length; i++) {
+        const src = indices[i] * item_size;
+
+        for (let c = 0; c < item_size; c++) {
+            result[i * item_size + c] = positions[src + c];
+        }
+    }
+
+    return result;
+}
+
+
+/**
+ * Replace geometry positions with expanded (un-indexed) data and
+ * optionally set normals.
+ *
+ * @param {Geometry} geometry
+ * @param {Float32Array} expanded_positions
+ * @param {Float32Array|null} expanded_normals
+ */
+function replace_geometry_positions(geometry, expanded_positions, expanded_normals) {
+
+    // Remove index and replace positions
+    geometry.index = null;
+
+    const pos_attr = Attribute.from(expanded_positions, 3, StandardAttributes.Position);
+    geometry.removeAttribute(StandardAttributes.Position);
+    geometry.addAttribute(normalize_attribute(pos_attr));
+
+    if (expanded_normals) {
+        const normal_attr = Attribute.from(expanded_normals, 3, StandardAttributes.Normal);
+        geometry.removeAttribute(StandardAttributes.Normal);
+        geometry.addAttribute(normalize_attribute(normal_attr));
+    }
+}