threers 0.0.7

Drop-in three.js replacement for Rust and WebAssembly (wgpu) — THREE.* API, scene graph, PBR, post-fx, mesh BVH, CSG, an OpenSCAD front end with a watertight exact-CSG kernel, headless render, and native media codecs
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
//! `UsdSkel` — skeletons, skinning and the animation that drives them.
//!
//! A skinned character is the one thing in USD that is not described where it
//! is used. The mesh says which skeleton binds it and which joints touch each
//! vertex; the skeleton says where the joints rest and what the mesh was bound
//! at; and a third prim, the animation, says where the joints are at each
//! frame. None of the three is much use without the other two.
//!
//! # Joints are paths, not names
//!
//! `joints = ["Root", "Root/Hip", "Root/Hip/Knee"]` is a *hierarchy* written
//! flat. The order of that list is the order every other array in the schema is
//! indexed by — bind transforms, rest transforms, the animation's channels, and
//! the per-vertex indices — so it is the one thing that must not be reordered.
//! The slashes are what says `Knee` hangs off `Hip`.
//!
//! # What is skinned where
//!
//! USD stores a bind transform per joint in *world* space and expects the
//! renderer to skin by `world * inverse(bind)`. That is the same convention
//! this crate's [`Bone`] holds, so the inverse is taken once here rather than
//! every frame.

use crate::animation::{AnimationClip, KeyframeTrack, TrackTarget};
use crate::core::{
    BufferAttribute, BufferGeometry, Bone, MorphTarget, Object3D, ObjectArena, ObjectId, Skeleton,
};
use crate::math::{Matrix4, Quaternion, Vector3};

use super::parse::{UsdLayer, UsdPrim};
use super::value::UsdValue;

/// How many joints may touch one vertex.
///
/// Four is what the shader reads and what every real-time renderer settles on.
/// A mesh authored with more keeps the four heaviest, which is what every
/// engine does with an eight-influence rig.
const INFLUENCES: usize = 4;

/// A skeleton read off a stage, with the nodes its joints became.
pub struct UsdSkeleton {
    /// The joint paths, in the order everything else indexes by.
    pub joints: Vec<String>,
    pub skeleton: Skeleton,
    /// The scene node for each joint, in the same order.
    pub nodes: Vec<ObjectId>,
}

/// Read a `Skeleton` prim, building a node per joint under `parent`.
///
/// The joints come back as real scene nodes because that is what a bone points
/// at — moving one has to move what hangs off it, which is the scene graph's
/// job rather than the skeleton's.
pub fn skeleton(prim: &UsdPrim, arena: &mut ObjectArena, parent: ObjectId) -> Option<UsdSkeleton> {
    let joints: Vec<String> = prim
        .value("joints")?
        .flat_tokens()
        .into_iter()
        .map(str::to_string)
        .collect();
    if joints.is_empty() {
        return None;
    }

    let bind = matrices(prim.value("bindTransforms"));
    let rest = matrices(prim.value("restTransforms"));

    // One node per joint, parented by what its path says.
    let mut nodes: Vec<ObjectId> = Vec::with_capacity(joints.len());
    for (i, path) in joints.iter().enumerate() {
        let mut node = Object3D::group();
        node.name = path.rsplit('/').next().unwrap_or(path).to_string();
        // The rest transform is the joint's *local* pose, which is exactly
        // what a scene node holds.
        if let Some(local) = rest.get(i) {
            let (position, quaternion, scale) = local.decompose();
            node.position = position;
            node.quaternion = quaternion;
            node.scale = scale;
        }
        let id = arena.insert(node);
        nodes.push(id);

        // A joint's parent is the joint whose path is this one's prefix.
        let owner = match path.rfind('/') {
            Some(at) => joints
                .iter()
                .position(|j| j == &path[..at])
                .map(|i| nodes[i])
                .unwrap_or(parent),
            None => parent,
        };
        arena.add_child(owner, id);
    }

    // USD's bind transforms are world space, and skinning wants their inverse.
    let bones: Vec<Bone> = nodes
        .iter()
        .enumerate()
        .map(|(i, node)| Bone {
            node: *node,
            inverse_bind: bind
                .get(i)
                .map(|m| m.invert())
                .unwrap_or_else(Matrix4::identity),
        })
        .collect();

    Some(UsdSkeleton {
        joints,
        skeleton: Skeleton::new(bones),
        nodes,
    })
}

/// The `joint` and `weight` attributes a skinned mesh needs, from the primvars
/// USD stores them in.
///
/// `elementSize` says how many influences each vertex has, and it is not
/// optional to read: the same array with an element size of two and of four
/// describes two entirely different rigs.
pub fn skin_attributes(prim: &UsdPrim, vertices: usize, geometry: &mut BufferGeometry) -> bool {
    let Some(indices) = prim
        .property("primvars:skel:jointIndices")
        .or_else(|| prim.property("skel:jointIndices"))
    else {
        return false;
    };
    let Some(weights) = prim
        .property("primvars:skel:jointWeights")
        .or_else(|| prim.property("skel:jointWeights"))
    else {
        return false;
    };

    let per_vertex = indices
        .metadata
        .iter()
        .find(|(k, _)| k == "elementSize")
        .and_then(|(_, v)| v.as_f64())
        .map(|v| v as usize)
        .filter(|v| *v > 0)
        .unwrap_or(INFLUENCES);

    let indices = indices.value.flat_f32();
    let weights = weights.value.flat_f32();
    if indices.is_empty() || indices.len() != weights.len() {
        return false;
    }

    let mut joint = vec![0.0f32; vertices * INFLUENCES];
    let mut weight = vec![0.0f32; vertices * INFLUENCES];
    for v in 0..vertices {
        let from = v * per_vertex;
        if from + per_vertex > indices.len() {
            break;
        }
        // Keep the heaviest influences when there are more than the shader
        // reads, rather than the first — dropping a 0.9 to keep a 0.05 is how
        // a limb ends up attached to the wrong bone.
        let mut pairs: Vec<(f32, f32)> = (0..per_vertex)
            .map(|k| (weights[from + k], indices[from + k]))
            .collect();
        pairs.sort_by(|a, b| b.0.total_cmp(&a.0));
        pairs.truncate(INFLUENCES);

        // Renormalise, since dropping influences loses their share — three.js's
        // `normalizeSkinWeights`, which its loaders run because the shader
        // does not normalise. That includes its answer for a vertex with no
        // weight at all, (1, 0, 0, 0): skinned by nothing, it would collapse
        // onto the mesh's origin.
        let total: f32 = pairs.iter().map(|(w, _)| *w).sum();
        for (k, (w, index)) in pairs.iter().enumerate() {
            joint[v * INFLUENCES + k] = *index;
            weight[v * INFLUENCES + k] = if total > 0.0 {
                w / total
            } else if k == 0 {
                1.0
            } else {
                0.0
            };
        }
    }

    geometry.set_attribute("joint", BufferAttribute::new(joint, INFLUENCES));
    geometry.set_attribute("weight", BufferAttribute::new(weight, INFLUENCES));
    true
}

/// Put a mesh into the space its weights were authored in.
///
/// `geomBindTransform` is where the mesh sat when it was bound, which is not
/// always where it sits now. Skipping it is invisible on a rig authored at the
/// origin and bends the character everywhere else.
pub fn apply_bind_transform(prim: &UsdPrim, geometry: &mut BufferGeometry) {
    let Some(value) = prim
        .value("primvars:skel:geomBindTransform")
        .or_else(|| prim.value("skel:geomBindTransform"))
    else {
        return;
    };
    let Some(bind) = matrices(Some(value)).into_iter().next() else {
        return;
    };
    if bind == Matrix4::identity() {
        return;
    }
    let Some(position) = geometry.get_attribute("position") else {
        return;
    };
    let moved: Vec<f32> = position
        .array
        .chunks_exact(3)
        .flat_map(|p| {
            // Column-major, as this crate stores matrices — which is the same
            // memory layout USD's row-vector convention produces, so the
            // sixteen numbers went in without rearranging.
            let m = &bind.elements;
            [
                m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12],
                m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13],
                m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14],
            ]
        })
        .collect();
    geometry.set_attribute("position", BufferAttribute::new(moved, 3));
}

/// The blend shapes bound to a mesh, as morph targets.
///
/// A `BlendShape` stores *offsets* from the base mesh, and usually only for the
/// vertices it touches — a smile moves the mouth and leaves the skull alone, so
/// `pointIndices` names the handful of vertices it has anything to say about.
/// A renderer wants a delta for every vertex, so the sparse form is expanded
/// here rather than left for every consumer to expand again.
pub fn blend_shapes(prim: &UsdPrim, layer: &UsdLayer, vertices: usize) -> Vec<MorphTarget> {
    // The names, which are what the animation keys its weights by, and the
    // prims that hold the offsets. The two lists run in parallel.
    let names: Vec<String> = prim
        .value("skel:blendShapes")
        .map(|v| v.flat_tokens().into_iter().map(str::to_string).collect())
        .unwrap_or_default();
    let targets: Vec<String> = prim
        .value("skel:blendShapeTargets")
        .map(|v| v.flat_tokens().into_iter().map(str::to_string).collect())
        .unwrap_or_default();

    let mut out = Vec::new();
    for (i, path) in targets.iter().enumerate() {
        // A target may be named by path or sit as a child of the mesh.
        let Some(shape) = layer
            .prim_at(path)
            .or_else(|| prim.children.iter().find(|c| Some(c.name.as_str()) == path.rsplit('/').next()))
        else {
            continue;
        };
        let offsets = shape.value("offsets").map(|v| v.flat_f32()).unwrap_or_default();
        if offsets.is_empty() {
            continue;
        }
        let indices = shape
            .value("pointIndices")
            .map(|v| v.flat_u32())
            .unwrap_or_default();

        out.push(MorphTarget {
            name: names.get(i).cloned().unwrap_or_else(|| shape.name.clone()),
            position_delta: dense(&offsets, &indices, vertices),
            normal_delta: shape
                .value("normalOffsets")
                .map(|v| v.flat_f32())
                .filter(|n| !n.is_empty())
                .map(|n| dense(&n, &indices, vertices)),
        });
    }
    out
}

/// Sparse offsets as a delta for every vertex.
fn dense(offsets: &[f32], indices: &[u32], vertices: usize) -> Vec<f32> {
    let mut out = vec![0.0; vertices * 3];
    if indices.is_empty() {
        // No index list means the offsets are for every vertex in order.
        let n = offsets.len().min(out.len());
        out[..n].copy_from_slice(&offsets[..n]);
        return out;
    }
    for (slot, vertex) in indices.iter().enumerate() {
        let (from, to) = (slot * 3, *vertex as usize * 3);
        if from + 3 > offsets.len() || to + 3 > out.len() {
            continue;
        }
        out[to..to + 3].copy_from_slice(&offsets[from..from + 3]);
    }
    out
}

/// The blend-shape weight tracks a `SkelAnimation` drives.
///
/// The animation keys *all* weights at once, in the order of its own
/// `blendShapes` list — which need not be the mesh's order, or even the same
/// set — so each weight is matched to the mesh's target by name.
pub fn blend_shape_tracks(
    anim: &UsdPrim,
    order: &[String],
    object: ObjectId,
    rate: f64,
) -> Vec<KeyframeTrack> {
    let Some(names) = anim.value("blendShapes").map(|v| {
        v.flat_tokens()
            .into_iter()
            .map(str::to_string)
            .collect::<Vec<_>>()
    }) else {
        return Vec::new();
    };
    let Some(samples) = anim.value("blendShapeWeights").and_then(|v| v.samples().map(<[_]>::to_vec))
    else {
        return Vec::new();
    };

    let mut out = Vec::new();
    for (slot, name) in names.iter().enumerate() {
        let Some(index) = order.iter().position(|n| n == name) else {
            continue;
        };
        let mut times = Vec::with_capacity(samples.len());
        let mut values = Vec::with_capacity(samples.len());
        for (time, frame) in &samples {
            let weights = frame.flat_f32();
            let Some(weight) = weights.get(slot) else {
                continue;
            };
            times.push((time / rate) as f32);
            values.push(*weight);
        }
        if times.is_empty() {
            continue;
        }
        out.push(KeyframeTrack::scalar(
            object,
            TrackTarget::MorphWeight { index },
            times,
            values,
        ));
    }
    out
}

/// The `SkelAnimation` a mesh's blend-shape weights come from: the
/// `skel:animationSource` of the skeleton its `skel:skeleton` binds. This is
/// how a mesh with blend shapes and no joints is bound (and how this crate's
/// exporter writes one).
pub fn bound_animation<'a>(mesh: &UsdPrim, layer: &'a UsdLayer) -> Option<&'a UsdPrim> {
    let skeleton = layer.prim_at(mesh.value("skel:skeleton")?.as_str()?)?;
    animation_source(skeleton, layer)
}

/// The blend-shape weights an animation holds at rest — its default value, or
/// its first sample — in the order of `order` (the mesh's targets), matched by
/// name; zero for a target the animation does not name.
pub fn blend_shape_weights(anim: &UsdPrim, order: &[String]) -> Vec<f32> {
    let mut out = vec![0.0; order.len()];
    let names: Vec<String> = anim
        .value("blendShapes")
        .map(|v| v.flat_tokens().into_iter().map(str::to_string).collect())
        .unwrap_or_default();
    let Some(value) = anim.value("blendShapeWeights") else {
        return out;
    };
    let weights = match value.samples() {
        Some(samples) => samples.first().map(|(_, v)| v.flat_f32()).unwrap_or_default(),
        None => value.flat_f32(),
    };
    for (slot, name) in names.iter().enumerate() {
        if let (Some(index), Some(w)) = (order.iter().position(|n| n == name), weights.get(slot)) {
            out[index] = *w;
        }
    }
    out
}

/// A `SkelAnimation` as tracks on the joint nodes it names.
///
/// The animation names its own joints, and they need not be the skeleton's in
/// the same order — or even all of them — so each channel is matched by name
/// rather than by position.
pub fn animation(
    prim: &UsdPrim,
    skeleton: &UsdSkeleton,
    rate: f64,
    name: &str,
) -> Option<AnimationClip> {
    let joints: Vec<String> = prim
        .value("joints")?
        .flat_tokens()
        .into_iter()
        .map(str::to_string)
        .collect();

    let mut tracks = Vec::new();
    let mut duration = 0.0f32;
    for (slot, joint) in joints.iter().enumerate() {
        let Some(node) = skeleton
            .joints
            .iter()
            .position(|j| j == joint)
            .map(|i| skeleton.nodes[i])
        else {
            continue;
        };

        if let Some((times, values)) = channel(prim, "translations", slot, 3) {
            duration = duration.max(times.last().copied().unwrap_or(0.0) as f32);
            tracks.push(KeyframeTrack::vector(
                node,
                TrackTarget::Position,
                times.iter().map(|t| (t / rate) as f32).collect(),
                values
                    .chunks_exact(3)
                    .map(|v| Vector3::new(v[0], v[1], v[2]))
                    .collect(),
            ));
        }
        if let Some((times, values)) = channel(prim, "rotations", slot, 4) {
            duration = duration.max(times.last().copied().unwrap_or(0.0) as f32);
            tracks.push(KeyframeTrack::quaternion(
                node,
                TrackTarget::Quaternion,
                times.iter().map(|t| (t / rate) as f32).collect(),
                values
                    // USD writes the real part first; this one takes it last.
                    .chunks_exact(4)
                    .map(|q| Quaternion::new(q[1], q[2], q[3], q[0]))
                    .collect(),
            ));
        }
        if let Some((times, values)) = channel(prim, "scales", slot, 3) {
            tracks.push(KeyframeTrack::vector(
                node,
                TrackTarget::Scale,
                times.iter().map(|t| (t / rate) as f32).collect(),
                values
                    .chunks_exact(3)
                    .map(|v| Vector3::new(v[0], v[1], v[2]))
                    .collect(),
            ));
        }
    }

    if tracks.is_empty() {
        return None;
    }
    Some(AnimationClip::new(
        name,
        (duration as f64 / rate) as f32,
        tracks,
    ))
}

/// One joint's channel out of an array-per-frame.
///
/// A `SkelAnimation` keys *all* joints at once — each sample is an array with
/// one entry per joint — so a single joint's curve is a column out of that,
/// not a row.
fn channel(
    prim: &UsdPrim,
    name: &str,
    slot: usize,
    lanes: usize,
) -> Option<(Vec<f64>, Vec<f32>)> {
    let value = prim.value(name)?;
    let samples = value.samples()?;
    if samples.is_empty() {
        return None;
    }

    let mut times = Vec::with_capacity(samples.len());
    let mut values = Vec::with_capacity(samples.len() * lanes);
    for (time, frame) in samples {
        let flat = frame.flat_f32();
        let from = slot * lanes;
        if from + lanes > flat.len() {
            return None;
        }
        times.push(*time);
        values.extend_from_slice(&flat[from..from + lanes]);
    }
    Some((times, values))
}

/// Whether a mesh binds to a skeleton at all.
///
/// A mesh is skinned because it *says* so, not because it happens to sit under
/// a `SkelRoot`: a rig often keeps static props in the same subtree, and they
/// must not pick up the skeleton by proximity.
pub fn binds_a_skeleton(prim: &UsdPrim) -> bool {
    prim.property("skel:skeleton").is_some()
}

/// The animation a skeleton is driven by.
pub fn animation_source<'a>(prim: &UsdPrim, layer: &'a UsdLayer) -> Option<&'a UsdPrim> {
    layer.prim_at(prim.value("skel:animationSource")?.as_str()?)
}

/// Matrices out of a value, four rows at a time.
fn matrices(value: Option<&UsdValue>) -> Vec<Matrix4> {
    let Some(value) = value else {
        return Vec::new();
    };
    let numbers = value.flat_f32();
    numbers
        .chunks_exact(16)
        .map(|m| {
            let mut out = Matrix4::identity();
            out.elements.copy_from_slice(m);
            out
        })
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;
    use super::super::{parse::parse, scene::to_scene, scene::UsdScene};
    use crate::animation::TrackValues;
    use crate::core::ObjectKind;

    fn stage() -> UsdScene {
        to_scene(&parse(include_str!("testdata/skel.usda")).expect("parses"))
    }

    fn find_id(scene: &UsdScene, name: &str) -> Option<ObjectId> {
        fn walk(scene: &UsdScene, id: ObjectId, name: &str) -> Option<ObjectId> {
            let node = scene.arena.get(id)?;
            if node.name == name {
                return Some(id);
            }
            node.children.iter().find_map(|c| walk(scene, *c, name))
        }
        scene.roots.iter().find_map(|r| walk(scene, *r, name))
    }

    fn find<'a>(scene: &'a UsdScene, name: &str) -> &'a Object3D {
        fn walk<'a>(scene: &'a UsdScene, id: ObjectId, name: &str) -> Option<&'a Object3D> {
            let node = scene.arena.get(id)?;
            if node.name == name {
                return Some(node);
            }
            node.children.iter().find_map(|c| walk(scene, *c, name))
        }
        scene
            .roots
            .iter()
            .find_map(|r| walk(scene, *r, name))
            .unwrap_or_else(|| panic!("no node called {name}"))
    }

    /// A mesh that names a skeleton and carries weights is skinned, not a
    /// static mesh with some unused primvars on it.
    #[test]
    fn a_bound_mesh_becomes_skinned() {
        let scene = stage();
        let ObjectKind::SkinnedMesh(mesh) = &find(&scene, "Body").kind else {
            panic!("expected a skinned mesh, got {:?}", find(&scene, "Body").kind);
        };
        assert_eq!(mesh.skeleton.bones.len(), 3, "three joints");

        // The shader reads four influences per vertex whatever the rig has.
        let joint = mesh.geometry.get_attribute("joint").expect("joint indices");
        let weight = mesh.geometry.get_attribute("weight").expect("weights");
        assert_eq!(joint.item_size, 4);
        assert_eq!(weight.item_size, 4);
        assert_eq!(joint.count(), 4, "one per vertex");
    }

    /// The rig has two influences per vertex; the two the shader does not get
    /// are zero-weighted rather than absent, and the weights still sum to one.
    #[test]
    fn influences_are_padded_and_normalised() {
        let scene = stage();
        let ObjectKind::SkinnedMesh(mesh) = &find(&scene, "Body").kind else {
            panic!("skinned");
        };
        let joint = mesh.geometry.get_attribute("joint").unwrap();
        let weight = mesh.geometry.get_attribute("weight").unwrap();

        // Vertex 0 is 0.8 of joint 0 and 0.2 of joint 1.
        assert_eq!(&joint.array[0..2], &[0.0, 1.0]);
        assert!((weight.array[0] - 0.8).abs() < 1e-5, "{}", weight.array[0]);
        assert!((weight.array[1] - 0.2).abs() < 1e-5);
        assert_eq!(&weight.array[2..4], &[0.0, 0.0], "unused influences");

        for v in 0..joint.count() {
            let total: f32 = weight.array[v * 4..v * 4 + 4].iter().sum();
            assert!((total - 1.0).abs() < 1e-5, "vertex {v} sums to {total}");
        }
    }

    /// `joints = ["Root", "Root/Mid", "Root/Mid/Tip"]` is a hierarchy written
    /// flat: the slashes say what hangs off what.
    #[test]
    fn joint_paths_build_a_hierarchy() {
        let scene = stage();
        let root = find(&scene, "Root");
        assert_eq!(root.children.len(), 1, "Root has one child");
        let mid = scene.arena.get(root.children[0]).unwrap();
        assert_eq!(mid.name, "Mid");
        assert_eq!(mid.children.len(), 1);
        assert_eq!(scene.arena.get(mid.children[0]).unwrap().name, "Tip");

        // The rest transform is the joint's local pose.
        assert_eq!(mid.position, Vector3::new(0.0, 2.0, 0.0));
    }

    /// A bind transform is world space; skinning wants its inverse, so the
    /// inversion happens once here rather than every frame.
    #[test]
    fn bind_transforms_are_inverted_once() {
        let scene = stage();
        let ObjectKind::SkinnedMesh(mesh) = &find(&scene, "Body").kind else {
            panic!("skinned");
        };
        // The second joint binds at y = 2, so its inverse translates by -2.
        let inverse = mesh.skeleton.bones[1].inverse_bind.elements;
        assert!((inverse[13] + 2.0).abs() < 1e-5, "got {}", inverse[13]);
        // And the third at y = 4.
        assert!((mesh.skeleton.bones[2].inverse_bind.elements[13] + 4.0).abs() < 1e-5);
    }

    /// A `SkelAnimation` keys every joint at once — each sample is an array
    /// with one entry per joint — so one joint's curve is a column out of it.
    #[test]
    fn the_animation_drives_the_joints() {
        let scene = stage();
        let clip = scene
            .animations
            .iter()
            .find(|c| !c.tracks.is_empty())
            .expect("a clip");

        // Walk to `Mid` rather than scanning the arena, so the id is the one
        // the hierarchy actually placed.
        let root_id = find_id(&scene, "Root").expect("Root");
        let mid_id = scene.arena.get(root_id).unwrap().children[0];
        assert_eq!(scene.arena.get(mid_id).unwrap().name, "Mid");

        let rotation = clip
            .tracks
            .iter()
            .find(|t| t.object == mid_id && matches!(t.target, TrackTarget::Quaternion))
            .expect("Mid should have a rotation track");
        assert_eq!(rotation.times, vec![0.0, 1.0], "24 codes at 24 a second");

        let TrackValues::Quaternion(values) = &rotation.values else {
            panic!("quaternions");
        };
        // USD writes the real part first; this crate keeps it last.
        assert!((values[1].w - 0.9239).abs() < 1e-3, "w was {}", values[1].w);
        assert!((values[1].z - 0.3827).abs() < 1e-3, "z was {}", values[1].z);
    }

    /// And the same rig read from the crate form.
    #[test]
    fn the_binary_form_skins_the_same_way() {
        let binary = to_scene(
            &super::super::UsdLoader::parse_layer(include_bytes!("testdata/skel.usdc"))
                .expect("the crate parses"),
        );
        let ObjectKind::SkinnedMesh(mesh) = &find(&binary, "Body").kind else {
            panic!("expected a skinned mesh from the crate form");
        };
        assert_eq!(mesh.skeleton.bones.len(), 3);
        assert!(!binary.animations.is_empty(), "the animation survived");
    }
}

#[cfg(test)]
mod blend_tests {
    use super::super::{parse::parse, scene::to_scene};
    use crate::animation::{TrackTarget, TrackValues};

    /// A blend shape stores offsets from the base mesh, usually for only the
    /// vertices it touches. A renderer wants a delta per vertex, so the sparse
    /// form is expanded — and expanding it wrongly moves the wrong face.
    #[test]
    fn sparse_offsets_land_on_the_vertices_they_name() {
        let scene = to_scene(&parse(include_str!("testdata/blend.usda")).expect("parses"));
        let (_, morphs) = scene
            .morph_targets
            .iter()
            .find(|(name, _)| name == "Face")
            .expect("the face has blend shapes");
        assert_eq!(morphs.targets.len(), 2);

        // `Smile` names points 2 and 3 of a four-point quad.
        let smile = morphs.targets.iter().find(|t| t.name == "smile").expect("smile");
        assert_eq!(smile.position_delta.len(), 4 * 3, "one delta per vertex");
        assert_eq!(&smile.position_delta[0..6], &[0.0; 6], "points 0 and 1 unmoved");
        assert_eq!(smile.position_delta[7], 0.5, "point 2 moved up");
        assert_eq!(smile.position_delta[10], 0.5, "point 3 moved up");

        // `Frown` names no indices, so its offsets are for every vertex in
        // order.
        let frown = morphs.targets.iter().find(|t| t.name == "frown").expect("frown");
        assert_eq!(frown.position_delta.len(), 4 * 3);
        assert_eq!(frown.position_delta[1], -0.5);
        assert_eq!(frown.position_delta[10], -0.5);

        // And they are on the geometry the renderers draw, as three.js morph
        // attributes: relative, named, influences sized to them.
        let face = scene
            .arena
            .nodes
            .values()
            .find(|n| n.name == "Face")
            .expect("the face");
        let (geometry, influences, dictionary) = match &face.kind {
            crate::core::ObjectKind::SkinnedMesh(m) => {
                (&m.geometry, &m.morph_influences, &m.morph_target_dictionary)
            }
            crate::core::ObjectKind::Mesh(m) => {
                (&m.geometry, &m.morph_influences, &m.morph_target_dictionary)
            }
            _ => panic!("a mesh"),
        };
        assert!(geometry.morph_targets_relative);
        let targets = &geometry.morph_attributes["position"];
        assert_eq!(targets.len(), 2);
        let s = dictionary["smile"];
        assert_eq!(targets[s].array[7], 0.5);
        assert_eq!(influences.len(), 2);
    }

    /// The weights are animated, and the animation keys all of them at once —
    /// so one shape's curve is a column out of the samples.
    #[test]
    fn blend_shape_weights_become_tracks() {
        let scene = to_scene(&parse(include_str!("testdata/blend.usda")).unwrap());
        let tracks: Vec<&crate::animation::KeyframeTrack> = scene
            .animations
            .iter()
            .flat_map(|c| &c.tracks)
            .filter(|t| matches!(t.target, TrackTarget::MorphWeight { .. }))
            .collect();
        assert_eq!(tracks.len(), 2, "one track per shape");

        let smile = tracks
            .iter()
            .find(|t| matches!(t.target, TrackTarget::MorphWeight { index: 0 }))
            .expect("a track for the first shape");
        assert_eq!(smile.times, vec![0.0, 1.0], "24 codes at 24 a second");
        let TrackValues::Scalar(values) = &smile.values else {
            panic!("scalars");
        };
        // Smile goes 0 -> 1 while frown goes 1 -> 0.
        assert_eq!(values, &vec![0.0, 1.0]);

        let frown = tracks
            .iter()
            .find(|t| matches!(t.target, TrackTarget::MorphWeight { index: 1 }))
            .unwrap();
        let TrackValues::Scalar(values) = &frown.values else {
            panic!("scalars");
        };
        assert_eq!(values, &vec![1.0, 0.0]);
    }

    /// And the same rig out of the crate form.
    #[test]
    fn blend_shapes_survive_the_binary_form() {
        let binary = to_scene(
            &super::super::UsdLoader::parse_layer(include_bytes!("testdata/blend.usdc"))
                .expect("the crate parses"),
        );
        let (_, morphs) = binary
            .morph_targets
            .iter()
            .find(|(name, _)| name == "Face")
            .expect("blend shapes from the crate");
        assert_eq!(morphs.targets.len(), 2);
        assert_eq!(morphs.targets[0].position_delta[7], 0.5);
    }
}