@woosh/meep-engine 3.60.3 → 3.60.5

package/src/shade/renderer/animation/SKINNING_FRAME_PLAN.md

@@ -1,357 +0,0 @@
-# The skinning frame
-
-**Status:** phase 1 landed, §9 with it, both confirmed on a device. §4 is detected but not
-carried.
-
-A skinned mesh's vertices are written in a frame, and the renderer re-applies that frame. Today the
-frame is whatever the asset's mesh node happens to carry, and nothing checks that it is a frame the
-skinning pass can actually work in. This plan makes the frame the engine's, derived from the skin,
-and makes the condition it must satisfy a checked one.
-
-## 1. The defect
-
-The pipeline is two multiplications:
-
-```
-A_j(t) = joint.global(t) · inverse_bind        shader_skin_matrix_prep writes this
-M_j(t) = mesh.global⁻¹ · A_j(t)                chunk_skin_blend_mesh_local converts this to a DQ
-```
-
-`dual_quat_from_m4` builds a unit quaternion out of `sqrt(max(0, 1 ± m00 ± m11 ± m22))`. It can
-represent a rotation and a translation and nothing else, so **`M_j` must be rigid**. Whether it is
-depends on `mesh.global` — a value the exporter chose, that glTF declares meaningless for a skinned
-mesh, and that this engine neither derives nor validates.
-
-`compute_skin_world_bounds` already refuses to use `mesh.global` for exactly that reason, and says
-so in its doc comment. The skinning pass still does, and inverts it.
-
-### What it looks like when it is violated
-
-Measured on `test_assets/Michelle.glb`, in `playground/skinned_mesh_soup/__soup_blend_probe.spec.js`
-— the shader's own chunks ported to JS and run over the character's own matrices:
-
-| | |
-| --- | --- |
-| `joint.global · inverse_bind` at rest | the **identity**, for all 65 joints |
-| `mesh.global` | `0.01` scale × the file's up-axis rotation |
-| column length of `M_j` | **100.0000**, at rest and under the dance, where rigid is 1 |
-
-At rest every joint folds to the *same* matrix, `100·Rx(90°)`, whose `w` and `x` terms are both
-`1 + 100` and whose `y` and `z` both clamp to zero — the normalize recovers `Rx(90°)` by luck, and
-only the scale is lost. Output is `expected / 100` to the digit: the right character, 1/100 the
-size.
-
-Under the dance the joints' matrices differ, each loses a different amount, and the mesh comes
-apart. Mean error 121 in a mesh-local space where the body is 224 across; worst 165, on vertices
-bound to **a single joint at weight 1**, so the blend is not even involved. That is the soup.
-
-### What it is not
-
-Ruled out on the CPU, on the parsed asset, before a GPU is involved
-(`playground/skinned_mesh_soup/__soup_probe.spec.js`):
-
-- the geometry is a surface — 28 106 triangles, no degenerates, longest edge 0.093 against a 2.24
-  diagonal, every meshlet index in range;
-- the skinning attributes are sound — all 19 106 vertices land back on their rest position under
-  `joint.global · inverse_bind`, no zero-weight vertices, no out-of-range joint;
-- the source BLAS is exact — 56 211 nodes all reachable, 28 106 leaves each naming a distinct
-  triangle whose box matches to the bit, all 28 105 internal nodes exactly their children's union.
-
-Worth stating plainly: `skinned_blas_refit`'s `verify()` is structurally blind to this. It holds the
-tree's root box against the bounds chain's box, and **both derive from the clone's vertex region**.
-Vertices wrong in the same way agree with each other perfectly. A green `verify()` and a soup
-picture are consistent, and were.
-
-### The precondition as currently written is the wrong one
-
-`chunk_skin_blend_mesh_local` states it as *"the four products must be rigid, which holds whenever
-the joints and the mesh node share the scaling ancestors — the shape a glTF skin has."* Michelle's
-joints and mesh node **do** share their scaling ancestor (`Character`, carrying the 0.01), and it
-still breaks. Sharing ancestors is neither necessary nor sufficient. §2 is the condition that is.
-
-## 2. The invariant
-
-At rest, `A_j` collapses to one matrix for every joint — `compute_skin_world_bounds` already names
-it, as "the character's placement in the world". Call it `A_bind`.
-
-> **A skinned mesh's node transform is not the file's. It is the skin's bind transform:
-> `mesh.global == A_bind`.**
-
-Three consequences, each of them testable:
-
-1. `M_j(rest) = I`. The clone at rest is bit-identical to the source geometry — which `SkinnedMesh`'s
-   class doc already claims ("until bound … its vertices stay at the source's bind-pose values") and
-   today only accidentally delivers.
-2. `M_j(t) = A_bind⁻¹ · A_j(t)` — the joint's **displacement from bind**. Rigid exactly when the clip
-   rotates and translates and does not scale. That is the honest precondition of dual-quaternion
-   skinning: a property of the *animation*, not of the exporter's unit conventions.
-3. It is *checkable* — from data the engine already holds, on the CPU, once per skin.
-
-## 3. Enforcement
-
-At `register_skin`, per skinned mesh:
-
-```
-C := mesh.global⁻¹ · A_bind
-mesh.transform_local := mesh.transform_local · C
-mesh.updateMatrices()
-```
-
-- **`C` is constant.** Anything applied above both the mesh node and the joints — placement,
-  movement, re-parenting — left-multiplies `mesh.global` and `A_bind` alike and cancels. Compute it
-  once.
-- **It is idempotent.** After the correction `mesh.global == A_bind`, so a second `C` is the
-  identity. Re-registering a skin changes nothing.
-- **It is a no-op for an asset that already satisfies the invariant.** An FBX-derived model whose
-  inverse-bind matrices are authored in pre-scale space has `A_bind == mesh.global` and gets
-  `C = I`. That is the no-regression pin, and it is a test rather than an assumption.
-- For Michelle, `C = 100·R⁻¹` on `Ch03`, whose local transform is the identity today.
-
-### Why this layer
-
-The mesh node is the last node on the mesh-only path — the one place a correction reaches the mesh
-without disturbing the joints. Correcting it fixes the frame identically for the rasterizer, the
-path tracer, the TLAS instance transform, the bounds chain and the motion vectors, because all of
-them read one transform. **No shader changes. No per-vertex cost.** One matrix per skin, once.
-
-`register_skin` rather than the loader because every skin passes through it — glTF, USD, the
-editor, `instantiate_scene_bundle`, and skins built in code, which never see a loader at all.
-
-### The sharp edge
-
-Children of a skinned mesh node would inherit the correction. In this engine sockets, effect anchors
-and projectile spawns are authored as *bones*, so a skinned mesh node should have no children — but
-"should" is what got us here. The normalisation asserts it, and says which node and which children if
-it fires.
-
-### Where it is not representable
-
-`Transform64` recomposes its local from TRS components, so a correction carrying shear does not
-survive the round trip. Rather than test `C` for shear, the normalisation applies it and then
-measures the residual directly — `max |mesh.global − A_bind|` — which is the end-to-end quantity and
-catches decomposition loss, a non-agreeing skeleton and a bad `C` in one number.
-
-## 4. What no frame can fix
-
-The correction absorbs a *constant* linear part. A clip that scales a joint makes `A_j` non-rigid
-per joint and per frame, and no choice of frame fixes that. The ladder:
-
-| `A_j` | answer |
-| --- | --- |
-| rigid | DQS, unchanged. Every asset in practice. |
-| per-joint **uniform** scale | DQS with scale: factor `M_j = S(s_j) · (Rot \| t/s_j)`, DQ the rigid part, blend `s = Σ wⱼsⱼ` alongside, multiply the transformed point by `s`. One divide and one multiply per joint. |
-| **non-uniform** or sheared | a dual quaternion cannot represent it at all. Either a per-skin linear-blend path — correct, candy-wrapper on those assets only — or a hard import error. |
-
-### The detector — landed
-
-Rows 2 and 3 are contingencies rather than requirements, so neither is carried. What *is* built is
-the thing that says whether they are ever needed, and it says it without a device:
-`skin_clip_scale_conflicts`, called from `register_skin` and `register_clip` alike.
-
-The condition is sharper than this section first stated. "A clip animating a `Scale` channel on a
-joint" understates it in one direction and overstates it in another, and both matter:
-
-- a scale on the character's **own root** reaches the mesh *and* every joint, enters `mesh.global`
-  and every `joint.global` alike, and cancels out of the fold. That is how a model is made to grow
-  and it has to stay legal — a joint-targeting test would have called it clean, which is right by
-  luck, and a "does it scale anything under the skin" test would have called it broken, which is
-  wrong;
-- a scale on a node **above only some of the joints** never targets a joint at all and breaks the
-  fold exactly as a joint-targeted one does.
-
-So the question is reachability, not targeting: **a scale is safe exactly when the node carrying it
-reaches the mesh and all of the joints, or none of them.** Anything between is a conflict.
-
-Two further refinements the curves themselves settle. A channel whose curves never leave 1 is not a
-scale, whatever it targets — clips arrive unoptimized and an identity channel on a joint is noise.
-And the range comes from `animation_curve_compute_aabb`, which follows the Hermite spline between
-keys rather than reading the keys alone: a curve that leaves 1 and returns to it scales the joints
-for most of the clip, and reading its endpoints would call it flat.
-
-The report says which rung would be needed. `uniform` is true only when all three axes are driven by
-equal curves, so an axis left unanimated — a squash — reads as non-uniform, which is the safe
-direction.
-
-**Cost.** `clip_scale_channels` is asked first and is one pass over a clip's channel list with a
-`property !== Scale` early-out. A clip that scales nothing is remembered by nothing and compared
-against nothing, which is every clip a character normally carries. Only a clip that scales something
-is held in the manager's index and paired off against the registered skins, in both registration
-orders — a clip can arrive before its skin as easily as after, and neither may pass in silence.
-
-## 5. Rejected
-
-- **Patch `dual_quat_from_m4` to swallow the scale.** Moves an asset-conditioning problem into the
-  per-vertex hot loop; correct only for a uniform scale, so it still needs the check; and it leaves
-  the invariant unstated, so the next asset shape breaks it silently. The band-aid.
-- **Drop the fold; write clones in world space.** The cleanest mathematically — glTF says skinned
-  vertices are world-space and the node transform is ignored. But f32 vertex storage at world
-  coordinates costs about a millimetre of precision per ten kilometres from the origin, and it forces
-  a skinned special case into the rasterizer's uniform "apply `node.global`" path. Correctness bought
-  with a precision bug.
-- **Bake the scale into geometry at import.** Does not defend the editor's drag-and-drop or anything
-  the importer never saw; mutates geometry that content-keyed registration now keys on; costs a full
-  vertex rewrite per asset. Worth doing *additionally*, offline, so the runtime correction is a
-  no-op — not instead of it.
-
-## 6. Tiers
-
-Kept as low as they will go, for as long as they will go. Every assertion below runs without a
-device and without an asset.
-
-| tier | what it holds | file |
-| --- | --- | --- |
-| 1 — pure arithmetic | a rigid matrix has zero defect; a scaled, sheared, degenerate or reflected one is reported as it should be | `core/geom/3d/mat4/m4_rigidity_defect.spec.js` |
-| 2 — the skin, on the CPU | what each asset shape's bind transform *is*, and that the mesh node is a frame for one and not the other; the correction lands `mesh.global` on the bind transform for both; the pre-scale shape is untouched, element for element; idempotent; survives the walk; placement-invariant; children named; a skin no frame can fix is reported and left alone | `skin_bind_transform.spec.js`, `skin_normalize_mesh_frame.spec.js` |
-| 3 — the shader's own WGSL, in the emulator | a vertex lands where its skin matrix says — every joint, both bind spaces, three conversions, at rest and posed apart — plus the negative control: the same vertex on the asset's own mesh node, most of a body away | `skinning/chunk_skin_blend_mesh_local.spec.js` |
-| 2b — the clip against the skin | a scale on a joint conflicts and a scale on the character's root does not; a curve flat at 1 is not a scale and one that leaves 1 between its keys is; uniform told from squash; and the manager reports it in both registration orders | `skin_clip_scale_conflicts.spec.js` |
-| 3b — the real asset, on the CPU | the whole chain over `Michelle.glb`'s own matrices and her `SambaDance`: the folded scale, the correction, and where every sampled vertex lands, before and after | `playground/skinned_mesh_soup/__soup_blend_probe.spec.js` |
-| 4 — the browser | `?skin=bind` is a full-size character; `?skin=animated` dances | `playground/skinned_mesh_soup/` |
-
-Tier 3 is the one that would have caught this: it already ran the real chunk over a synthetic model,
-and it only ever built the one asset shape. Adding the other shape was the whole test change.
-
-**Run, on an NVIDIA RTX 4090.** Phase 1: the console reported `absorbing 99.0000 of non-rigidity the
-skinning pass could not have carried`, `?skin=bind` drew a full-size character, `?skin=animated`
-danced, and the published box came back `1.4556 × 1.6644 × 0.3872 m` — a character, not a coin.
-Then §9, whose WGSL nothing offline type-checks: compiles and runs. Then `await diagnose()` at
-`?skin=bind`, which reads the clone's vertices back off the device and holds them against the bind
-pose — **all 19 106 of them, worst error `7.96e-7`**, no wrong meshlets and no wrong vertex slots.
-That is the f32 floor of a matrix product, a quaternion conversion and a screw motion at single
-precision, and it is four orders below the smallest violation the tool can report.
-
-Held red by hand before landing: with the correction's body removed, 11 tests fail — four of them
-tier 3, and only the world-space rows. Every pre-scale row stays green, which is the no-regression
-claim stated as an experiment rather than as a hope.
-
-Measured on `Michelle.glb`, 2 486 vertices sampled, in a mesh-local space where the body is 2.24
-across:
-
-| | folded scale | mean error | worst | worst on a single-joint vertex |
-| --- | --- | --- | --- | --- |
-| bind, mesh node as the file gave it | 100.0000 | 121.2470 | 165.4281 | 165.4281 |
-| posed at 0.5 s, the same | 100.0000 | 121.6197 | 165.5332 | — |
-| bind, on the skin frame | 1.0000 | 0.0002 | 0.0016 | 0.0014 |
-| posed at 0.5 s, on the skin frame | 1.0000 | 0.0001 | 0.0062 | 0.000014 |
-| bind, skin frame **and §9** | 1.0000 | 0.0000 | 0.0000 | **0** |
-| posed at 0.5 s, skin frame and §9 | 1.0000 | 0.0001 | 0.0062 | **0.000001** |
-
-The one residual left is the blended vertices — 0.0062 at 0.76 / 0.23 across a bent joint — which is
-dual-quaternion skinning declining to be a linear blend, and is what it is for. The 0.0014 at bind
-was §9, and is gone.
-
-## 7. What landed
-
-1. `m4_rigidity_defect` — tier 1.
-2. `skin_joint_matrix`, `skin_bind_transform`, `skin_frame_defect` — the three questions, one file
-   each; `skin_test_fixtures` builds both asset shapes as scene graphs, off the hierarchy rather
-   than by hand.
-3. `skin_normalize_mesh_frame` — the correction, with the report `register_skin` logs from.
-4. `GPUAnimationManager#register_skin` calls it ahead of the bind loop, and names an asset it cannot
-   put right.
-5. Doc corrections: `chunk_skin_blend_mesh_local`'s stated precondition, `SkinnedMesh`'s class doc
-   (`transform_global` on a skinned mesh is now the engine's, and says so), and the fixture header in
-   `SkinnedMesh.spec.js` that had drawn the wrong conclusion from the right observation.
-
-Then §9, and §4's detector — `skin_clip_scale_conflicts`, with the manager keeping an index of
-skins by id and of the clips that scale anything, so the pairing runs whichever order they arrive in.
-
-Not carried: §4's rows 2 and 3 themselves. The detector is what would say they are needed.
-
-## 8. Risks
-
-- **Something reads a skinned mesh's `transform_global` expecting the file's value.**
-  `compute_skin_world_bounds` does not, and glTF says the value is meaningless for a skinned mesh.
-  After this it *means* something: the frame the mesh's vertices are expressed in. Any consumer that
-  wanted the file's node transform wanted the wrong thing.
-- **An asset whose rest pose is not its bind pose** has no single `A_bind`. The deviation number says
-  so by name rather than the engine guessing. Not seen in practice; the check is what would find it.
-- **The eighteen creature models.** Whether they satisfy the invariant today cannot be measured from
-  this repository — they are the game's. The check answers it on their first frame, which is itself
-  the argument for landing the check before the correction.
-
-## 9. Landed: `dual_quat_from_m4` was ill-conditioned near the identity
-
-Not caused by phase 1, and exposed by it. The conversion took all four quaternion components as
-
-```wgsl
-sqrt(max(0, 1 ± m00 ± m11 ± m22)) * 0.5
-```
-
-and near the identity three of those radicands are near zero. A square root turns an error of `e`
-into one of `sqrt(e)`, and it lands on the rotation *axis* rather than its angle, so it does not
-average out.
-
-Measured on Michelle after the frame correction: every folded matrix is the identity to `1.131e-6`
-(worst joint, `mixamorig:LeftUpLeg`), predicting `sqrt(3 × 1.131e-6) / 2 = 9.21e-4` per component, an
-angular error of `1.84e-3` rad, and `1.418e-3` at the worst vertex's radius. Observed: `1.402e-3` —
-a millimetre and a half on a 1.66 m character. It showed **only at bind**, because that is the one
-pose where the fold lands every joint on the identity; posed at 0.5 s the same measurement gave
-`1.4e-5`.
-
-**The fix was already in the tree.** `chunk_quat_from_m3` is Shoemake's branch-picking form —
-compute whichever component the diagonal says is largest, derive the other three by division — and
-it was written, correct, and used by nothing but a doc reference. `dual_quat_from_m4` now delegates
-its real part to it. One `sqrt` and a reciprocal instead of four `sqrt`s and a normalize, every
-branch dividing by at least 2, and the error passes through in proportion rather than as its square
-root.
-
-On Michelle: `1.402e-3` → `0` at bind, `1.4e-5` → `1e-6` posed.
-
-Three tiers, all device-free. `chunk_quat_from_m3.spec.js` is new, because delegating put a chunk
-with no spec of its own on the path of every skinned vertex: a sweep of rotations about four axes
-against what the matrix does to three off-axis probes, all four branches reached and each exact
-where it takes over, the near-identity scaling law over three decades, and a hair either side of a
-half turn. `chunk_dual_quat_from_m4.spec.js` gained the composed form of the same question and a
-case for a translation carried by a rotation that is barely there. `__soup_blend_probe.spec.js`'s
-ported chunk follows the real one, and its single-joint tolerance went from `5e-3` to `1e-5`.
-
-Held red by hand, with the four-`sqrt` form swapped back in: four tests fail. The near-identity one
-reports `0.000863` against the `8.66e-4` predicted above — three digits — and, as a bonus nobody was
-looking for, a genuine rotation of `1e-5` came back as **exactly zero**: f32 rounds the diagonal to 1,
-every radicand to 0 or 4, and the rotation is not amplified but destroyed.
-
-One consequence worth naming: the old form recovered `Rx(90°)` exactly from `100·Rx(90°)`, because
-its `w` and `x` radicands were both `1 + 100` and its `y` and `z` both clamped — the coincidence §1
-describes, where only the scale was lost and the character came out the right shape at 1/100 size.
-The branch form has no such luck, so a frame violation now looks wrong rather than small. That is the
-better failure, and the negative controls in `chunk_skin_blend_mesh_local.spec.js` still hold.
-
-### Still open
-
-`quat_from_m3` reads a matrix's upper 3×3 as a rotation, which is the same contract
-`dual_quat_from_m4` has and the same one `m4_rigidity_defect` exists to check. Nothing calls it with
-a scale on purpose now, and nothing warns if something starts to.
-
-## 10. Adversarial review
-
-Of §§1–9's own work, after it was green. Findings in the order they matter.
-
-| | severity | finding | resolution |
-| --- | --- | --- | --- |
-| A1 | **must-fix** | `transform_global` is derived and a fresh `Transform64` is the **identity**, not zeros — so a skin whose scene has never been walked answers "every joint is at the origin", and that answer passes every check in §3. The folds come out `inverse_bind_0⁻¹ × inverse_bind_j`, which on a real character differ by rigid motions and read as perfectly rigid; a correction would be computed from nothing, applied, and then confirmed by a residual whose two halves both come from the same unwalked state. The exact class of silent wrongness this whole change exists to end, reintroduced inside its own guard. | **Fixed.** `Node3D#version` is bumped by `updateMatrices` and by nothing else, so a node at version 0 has never been derived. `skin_normalize_mesh_frame` refuses before measuring, reports the nodes, and `register_skin` names one. Pinned twice: the refusal, and the premise — that an all-identity skeleton scores under `1e-6` on the defect. |
-| A2 | **must-fix** | A reflection scores **zero** on `m4_rigidity_defect`, because it is orthonormal and that is what the defect measures. So a mirrored joint passed the frame check and `quat_from_m3` would answer with a rotation, silently. The one way a fold can be unrepresentable and still look perfect. | **Fixed.** `skin_frame_defect` checks the sign of the fold's linear determinant and answers `Infinity`. A reflection the frame and every joint share cancels and never reaches it, so what does reach it is a skeleton disagreeing with itself about handedness, which no frame reconciles. |
-| A3 | should-fix | `skin_frame_defect_by_joint` — the diagnostic that says *which* joint — did not make A2's refusal, so the gate and the explanation of the gate would have disagreed about which joints were the problem. | **Fixed** alongside A2, and the test now asserts both halves: joint 0 clean, joints 1 and 2 `Infinity`. |
-| A4 | should-fix | `__soup_probe.spec.js`'s bind-pose probe compared against `mesh.transform_global × rest` — a composition the renderer *cancels* — and printed "worst bind-pose deviation 1.672182" next to a `skinned` column that was exactly right. A trap rather than a measurement, and it asserted nothing. | **Fixed.** It compares against the skin's bind transform, prints `5.65e-7`, and now asserts: no zero-weight vertices, no out-of-range joints, worst under `1e-5`. |
-| A5 | nit | `skin_normalize_mesh_frame` measured `frame_defect` before the unwalked check could reject the data it was measured from, leaving a meaningful-looking number in a report where it meant nothing. | **Fixed**: measured after the refusal, `NaN` before it, and said so in the return doc. |
-| A6 | nit | `chunk_dual_quat_from_m4`'s doc claimed "one `sqrt` and a reciprocal, against four `sqrt`s and a normalize" while keeping the normalize. | **Fixed**, and the normalize's actual job — a degenerate 3×3, where `quat_from_m3` lands on a branch whose answer has length 0.5 — is stated instead of implied. |
-| A7 | nit | `verify_clone_vertices` dereferenced an unregistered source geometry's record. | **Fixed**: reported as a verdict rather than a `TypeError`. |
-| A8 | nit | The rotation fixture in `chunk_quat_from_m3.spec.js` recomputed one cross product three times, and — found the hard way — took its axis on trust. `[0.4243, -0.5657, 0.7071]` has norm `0.99982`, and that `1.8e-4` came back out as `1.15e-4` of "disagreement" that read as a defect in the conversion for a good ten minutes. | **Fixed**: normalized in the fixture, with the incident in its doc comment so the next person does not spend the ten minutes. |
-
-### Left, with reasons
-
-- **`skin_bind_transform` takes joint 0's matrix.** In a file whose rest pose is its bind pose every
-  joint answers the same one. In a file where they differ there is no single answer, and it does not
-  matter: the frame cancels out of the rendered position entirely — `mesh.global × (mesh.global⁻¹ ×
-  A_j) = A_j` for any invertible frame — so the frame's only job is to make `M_j` *representable*, and
-  `skin_frame_defect` is what checks that. Joints disagreeing by rigid motions cost nothing.
-- **A skeleton walked, then moved, then not walked again.** Not detectable by `version`, which counts
-  walks rather than staleness. The mesh half of it *is* caught: the correction is computed from the
-  stale global but applied to the local, and the residual is measured against the live one, so it
-  fires. The joint half is the caller's contract.
-- **The `TOLERANCE` constant gates two different quantities** — a dimensionless rigidity measure and
-  a matrix distance mixing linear and translation units. Defensible at `1e-4` against a smallest real
-  violation of `99`, and splitting it would invite two numbers nobody can justify separately.
-- **No offline tier in this engine type-checks WGSL.** The emulator builds the whole skinning shader
-  from its chunk graph, which catches an undefined function and a syntax error, and that is where the
-  coverage stops. §9's `mat3x3<f32>(m[0].xyz, …)` was settled by a page load rather than by a test,
-  and the next chunk edit will be too.

package/src/shade/renderer/atmosphere/NOTES.md

@@ -1,6 +0,0 @@
-References:
-
-* https://www.shadertoy.com/view/slSXRW
-* "How Big Budget AAA Games Render Clouds" by SimonDev : https://www.youtube.com/watch?v=Qj_tK_mdRcA
-* Physically Based and Unified Volumetric Rendering in Frostbite (SIGGRAPH
-  2015) https://www.youtube.com/watch?v=ddfEnuXZijM

package/src/shade/renderer/camera/orbital/MomentumAxis.d.ts

@@ -1,76 +0,0 @@
-/**
- * One degree of freedom with **direct drive + release momentum** — the "throw"
- * model (Google Earth / Maps / Cesium), NOT a spring.
- *
- * The distinction that matters for feel:
- *   - **Position is applied directly** (`drag` moves `value` 1:1, zero lag) — so
- *     while the user is dragging, the camera tracks the input exactly. Responsive.
- *   - **Only the velocity is filtered.** Each frame the per-frame motion is pushed
- *     into a short time-windowed history; on release the average velocity over the
- *     last `windowSeconds` is taken as the throw velocity. Averaging the velocity
- *     (not the position) gives a clean, jitter-free throw without adding any lag
- *     to the live drag.
- *   - **On release it coasts**: `value += velocity·dt` with the velocity decaying
- *     exponentially (frame-rate independent), settling to a weighty stop. Grabbing
- *     it again (`engage`) cancels the coast instantly.
- *
- * Holding still before releasing naturally yields ~zero velocity (the recent
- * window fills with no-motion frames), so a deliberate slow drag stops dead while
- * a flick throws — no explicit click-vs-drag gate needed.
- *
- * Pure: no DOM, no clock. `update(dt)` is the only time input. Unit tested in
- * `MomentumAxis.spec.js`.
- *
- * @author Alex Goldring (orbital rework)
- * @copyright Company Named Limited (c) 2026
- */
-export class MomentumAxis {
-    /**
-     * @param {number} [value] initial position
-     */
-    constructor(value?: number);
-    /** Current position — read this for rendering. */
-    value: number;
-    /** Current velocity (units/second). Nonzero while coasting. */
-    velocity: number;
-    /** True while the user is actively driving this axis. */
-    engaged: boolean;
-    _pending: number;
-    _d: any[];
-    _dt: any[];
-    /** Begin direct control: cancel any coast and drop stale history. */
-    engage(): void;
-    /** Apply input immediately (1:1) and record it for velocity estimation. */
-    drag(delta: any): void;
-    /**
-     * Apply input immediately but clamp the position to [min, max]; only the
-     * motion that actually happened is recorded (so pushing into a limit builds
-     * no phantom velocity). Used for the polar/pitch limit.
-     */
-    dragClamped(delta: any, min: any, max: any): void;
-    /**
-     * End the gesture: derive the throw velocity from the recent window, then
-     * (if momentum is on) let `update` coast it out. `momentum=false` stops dead.
-     * @param {number} windowSeconds history window to average
-     * @param {boolean} [momentum=true]
-     */
-    release(windowSeconds: number, momentum?: boolean): void;
-    /** Hard reset to a position with no motion (teleport / external adopt). */
-    settle(value: any): void;
-    /**
-     * Advance one frame.
-     *  - engaged: record this frame's motion for the velocity estimate (the
-     *    position was already moved by `drag`). Returns whether it moved.
-     *  - free + coasting: integrate and exponentially decay the velocity,
-     *    snapping to rest below `stopSpeed`. Returns whether it moved.
-     *
-     * @param {number} dt seconds
-     * @param {number} decayHalfLife seconds for the coast velocity to halve
-     * @param {number} stopSpeed below this |velocity| the coast ends
-     * @returns {boolean} true if `value` changed this frame
-     */
-    update(dt: number, decayHalfLife: number, stopSpeed: number): boolean;
-    /** Average velocity over the most recent `windowSeconds` of history. */
-    _windowedVelocity(windowSeconds: any): number;
-}
-//# sourceMappingURL=MomentumAxis.d.ts.map

package/src/shade/renderer/camera/orbital/MomentumAxis.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"MomentumAxis.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/camera/orbital/MomentumAxis.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IACI;;OAEG;IACH,oBAFW,MAAM,EAehB;IAZG,kDAAkD;IAClD,cAAkB;IAClB,+DAA+D;IAC/D,iBAAiB;IACjB,yDAAyD;IACzD,iBAAoB;IAGpB,iBAAiB;IAEjB,UAAY;IACZ,WAAa;IAGjB,qEAAqE;IACrE,eAMC;IAED,2EAA2E;IAC3E,uBAGC;IAED;;;;OAIG;IACH,kDAUC;IAED;;;;;OAKG;IACH,uBAHW,MAAM,aACN,OAAO,QAYjB;IAED,2EAA2E;IAC3E,yBAOC;IAED;;;;;;;;;;;OAWG;IACH,WALW,MAAM,iBACN,MAAM,aACN,MAAM,GACJ,OAAO,CA+BnB;IAED,wEAAwE;IACxE,8CAWC;CACJ"}

package/src/shade/renderer/camera/orbital/MomentumAxis.js

@@ -1,164 +0,0 @@
-const LN2 = 0.6931471805599453;
-
-/**
- * One degree of freedom with **direct drive + release momentum** — the "throw"
- * model (Google Earth / Maps / Cesium), NOT a spring.
- *
- * The distinction that matters for feel:
- *   - **Position is applied directly** (`drag` moves `value` 1:1, zero lag) — so
- *     while the user is dragging, the camera tracks the input exactly. Responsive.
- *   - **Only the velocity is filtered.** Each frame the per-frame motion is pushed
- *     into a short time-windowed history; on release the average velocity over the
- *     last `windowSeconds` is taken as the throw velocity. Averaging the velocity
- *     (not the position) gives a clean, jitter-free throw without adding any lag
- *     to the live drag.
- *   - **On release it coasts**: `value += velocity·dt` with the velocity decaying
- *     exponentially (frame-rate independent), settling to a weighty stop. Grabbing
- *     it again (`engage`) cancels the coast instantly.
- *
- * Holding still before releasing naturally yields ~zero velocity (the recent
- * window fills with no-motion frames), so a deliberate slow drag stops dead while
- * a flick throws — no explicit click-vs-drag gate needed.
- *
- * Pure: no DOM, no clock. `update(dt)` is the only time input. Unit tested in
- * `MomentumAxis.spec.js`.
- *
- * @author Alex Goldring (orbital rework)
- * @copyright Company Named Limited (c) 2026
- */
-export class MomentumAxis {
-    /**
-     * @param {number} [value] initial position
-     */
-    constructor(value = 0) {
-        /** Current position — read this for rendering. */
-        this.value = value;
-        /** Current velocity (units/second). Nonzero while coasting. */
-        this.velocity = 0;
-        /** True while the user is actively driving this axis. */
-        this.engaged = false;
-
-        // motion applied since the last per-frame sample
-        this._pending = 0;
-        // recent per-frame motion history: parallel ring of deltas + durations
-        this._d = [];
-        this._dt = [];
-    }
-
-    /** Begin direct control: cancel any coast and drop stale history. */
-    engage() {
-        this.engaged = true;
-        this.velocity = 0;
-        this._pending = 0;
-        this._d.length = 0;
-        this._dt.length = 0;
-    }
-
-    /** Apply input immediately (1:1) and record it for velocity estimation. */
-    drag(delta) {
-        this.value += delta;
-        this._pending += delta;
-    }
-
-    /**
-     * Apply input immediately but clamp the position to [min, max]; only the
-     * motion that actually happened is recorded (so pushing into a limit builds
-     * no phantom velocity). Used for the polar/pitch limit.
-     */
-    dragClamped(delta, min, max) {
-        const before = this.value;
-        let next = before + delta;
-        if (next < min) {
-            next = min;
-        } else if (next > max) {
-            next = max;
-        }
-        this.value = next;
-        this._pending += next - before;
-    }
-
-    /**
-     * End the gesture: derive the throw velocity from the recent window, then
-     * (if momentum is on) let `update` coast it out. `momentum=false` stops dead.
-     * @param {number} windowSeconds history window to average
-     * @param {boolean} [momentum=true]
-     */
-    release(windowSeconds, momentum = true) {
-        // fold the not-yet-sampled residual into the most recent frame
-        if (this._pending !== 0 && this._d.length > 0) {
-            this._d[this._d.length - 1] += this._pending;
-        }
-        this.velocity = momentum ? this._windowedVelocity(windowSeconds) : 0;
-        this.engaged = false;
-        this._pending = 0;
-        this._d.length = 0;
-        this._dt.length = 0;
-    }
-
-    /** Hard reset to a position with no motion (teleport / external adopt). */
-    settle(value) {
-        this.value = value;
-        this.velocity = 0;
-        this.engaged = false;
-        this._pending = 0;
-        this._d.length = 0;
-        this._dt.length = 0;
-    }
-
-    /**
-     * Advance one frame.
-     *  - engaged: record this frame's motion for the velocity estimate (the
-     *    position was already moved by `drag`). Returns whether it moved.
-     *  - free + coasting: integrate and exponentially decay the velocity,
-     *    snapping to rest below `stopSpeed`. Returns whether it moved.
-     *
-     * @param {number} dt seconds
-     * @param {number} decayHalfLife seconds for the coast velocity to halve
-     * @param {number} stopSpeed below this |velocity| the coast ends
-     * @returns {boolean} true if `value` changed this frame
-     */
-    update(dt, decayHalfLife, stopSpeed) {
-        if (this.engaged) {
-            this._d.push(this._pending);
-            this._dt.push(dt);
-            // bound history (defensive; ~1.5s at 60fps)
-            if (this._d.length > 90) {
-                this._d.shift();
-                this._dt.shift();
-            }
-            const moved = this._pending !== 0;
-            this._pending = 0;
-            return moved;
-        }
-
-        if (this.velocity !== 0) {
-            // Analytic integration of a decaying velocity, so the coast distance
-            // is EXACTLY frame-rate independent (forward-Euler would drift ~1%
-            // between 60 and 144 Hz). Over dt: Δx = v·τ·(1 − e^(−dt/τ)), v ·= e^(−dt/τ).
-            const tau = decayHalfLife / LN2;
-            const decay = Math.exp(-dt / tau);
-            this.value += this.velocity * tau * (1 - decay);
-            this.velocity *= decay;
-            if (Math.abs(this.velocity) <= stopSpeed) {
-                this.velocity = 0;
-            }
-            return true;
-        }
-
-        return false;
-    }
-
-    /** Average velocity over the most recent `windowSeconds` of history. */
-    _windowedVelocity(windowSeconds) {
-        let sumD = 0;
-        let sumDt = 0;
-        for (let i = this._d.length - 1; i >= 0; i--) {
-            sumD += this._d[i];
-            sumDt += this._dt[i];
-            if (sumDt >= windowSeconds) {
-                break;
-            }
-        }
-        return sumDt > 0 ? sumD / sumDt : 0;
-    }
-}

package/src/shade/renderer/camera/orbital/OrbitalCameraConfig.d.ts

@@ -1,45 +0,0 @@
-/**
- * Merge overrides over the defaults to produce a controller config.
- * @param {Partial<typeof ORBITAL_CAMERA_FEEL_DEFAULTS>} [overrides]
- * @returns {typeof ORBITAL_CAMERA_FEEL_DEFAULTS}
- */
-export function createOrbitalCameraConfig(overrides?: Partial<typeof ORBITAL_CAMERA_FEEL_DEFAULTS>): typeof ORBITAL_CAMERA_FEEL_DEFAULTS;
-/**
- * Ready-made "Precision" profile: no inertia — the camera stops the instant you
- * release (direct mouse-delta control, can stop on a pixel), the Maya/CAD
- * convention.
- * @param {Partial<typeof ORBITAL_CAMERA_FEEL_DEFAULTS>} [overrides]
- * @returns {typeof ORBITAL_CAMERA_FEEL_DEFAULTS}
- */
-export function createPrecisionProfile(overrides?: Partial<typeof ORBITAL_CAMERA_FEEL_DEFAULTS>): typeof ORBITAL_CAMERA_FEEL_DEFAULTS;
-/**
- * Tunable "feel" parameters for the orbital camera, shared by the control core
- * ({@link OrbitalCameraRig}) and the input adapter ({@link OrbitalCameraInput}).
- * One frozen source of truth so the two layers can never disagree.
- *
- * The model is **direct drive + release momentum** (a "throw", like Google Earth
- * / Cesium), NOT a smoothed-target spring. While dragging, the camera follows
- * input 1:1 (no lag, fully responsive). On release the recent input velocity is
- * carried forward and decays exponentially — the weighty follow-through. See
- * {@link MomentumAxis}.
- *
- * Defaults grounded in the competitor survey:
- *   - `momentumDecayHalfLife` ≈ Cesium spin inertia (tau 2.5 → half-life 0.28 s).
- *   - `velocityWindow` ≈ Mapbox's 160 ms release-velocity window (a touch shorter).
- *   - `zoomStep` 0.9 multiplicative per notch ≈ three.js `pow(0.95, zoomSpeed)`.
- */
-export const ORBITAL_CAMERA_FEEL_DEFAULTS: Readonly<{
-    momentumEnabled: true;
-    momentumDecayHalfLife: 0.1;
-    velocityWindow: 0.1;
-    momentumStopSpeed: 0.012;
-    rotateSpeed: 1;
-    panSpeed: 1;
-    zoomStep: 0.9;
-    invertWheel: false;
-    minPolar: 0.000001;
-    maxPolar: number;
-    flyToDuration: 0.35;
-    maxDt: 0.1;
-}>;
-//# sourceMappingURL=OrbitalCameraConfig.d.ts.map

package/src/shade/renderer/camera/orbital/OrbitalCameraConfig.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"OrbitalCameraConfig.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/camera/orbital/OrbitalCameraConfig.js"],"names":[],"mappings":"AA+CA;;;;GAIG;AACH,sDAHW,QAAQ,mCAAmC,CAAC,GAC1C,mCAAmC,CAI/C;AAED;;;;;;GAMG;AACH,mDAHW,QAAQ,mCAAmC,CAAC,GAC1C,mCAAmC,CAI/C;AAjED;;;;;;;;;;;;;;;GAeG;AACH;;;;;;;;;;;;;GA6BG"}