linegel Camera Controls And Rigs
A rig publishes one semantic pose, one unjittered projection, and one origin epoch per view and frame. Controls, fit solvers, authored shots, temporal jitter, and coordinate rebasing own separate state and hand off explicitly.
1. Declare owners and spaces
Assign one writer to each channel:
| Channel | Writer |
|---|---|
| semantic pose | active controls, fit solver, authored shot, or external/XR owner |
| unjittered projection | active framing or shot owner |
| transient jitter | one temporal node during render |
| render origin | large-coordinate owner at an origin epoch |
| post camera data | one scene pass and its declared consumers |
| listeners/resources/restoration | scene or view lifecycle owner |
Declare units, handedness, world up, camera parent contract, and conversions
between object, world/global, local tangent, camera-relative, view, clip, and
screen space. Camera local forward is -Z, right +X, and up +Y. Inactive
input systems emit intent; only the active semantic owner writes the camera.
Complete when: every mutable camera field, matrix, temporal resource, and listener has exactly one writer and every space crossing names its conversion.
2. Choose the framing branch
Choose from the image or measurement requirement:
| Requirement | Architecture |
|---|---|
| asset inspection | bounds-fit perspective or orthographic view plus orbit controls |
| architecture | eye/section anchors, lens shift, and constrained orbit/pan/walk |
| scientific view | reproducible pose, axes/units, and projection selected by measurement semantics |
| geospatial scale | local tangent frame plus rebased or high/low camera-relative coordinates |
| cinematography | authored pose/projection tracks with explicit cut and blend epochs |
Define the subject support points, safe frame, required depth envelope, and authored lens/projection intent. Use orthographic projection when screen scale must remain independent of depth; use perspective when foreshortening carries meaning.
Read framing and projection for asymmetric frusta, volume fitting, orthographic rules, and depth precision.
Complete when: the selected projection explains the visual or measurement requirement and the support set, safe frame, and depth envelope are explicit.
3. Solve a valid pose and projection
Build a deterministic orthonormal basis from position, target, up hint, and a
least-aligned-axis fallback. For a deep subject, project a conservative support
set rather than fitting planar width/height alone. Reject nonfinite clip
coordinates and perspective w <= 0; require negative view-space z, NDC
inside the safe frame, and every support point inside the near/far interval.
Update world and projection matrices before reading hierarchy or frustum data. Use an identity/unit-scale camera ancestry, or convert the delivered world pose through the updated inverse parent transform before assigning local pose.
When obstruction changes the camera, solve the near-plane footprint against the path and rerun safe-frame and depth feasibility. Composition and clearance must pass together.
Complete when: the delivered camera has a finite right-handed basis, finite
clip coordinates with valid w, the full support set inside the safe frame and
depth interval, and a post-obstruction recheck when obstruction is active.
4. Execute one explicit handoff
Resolve the active owner before update. A finite authored handoff captures its
start once, evaluates time from seconds, writes one positional lerp and
shortest-path quaternion slerp, and copies the exact target at completion.
An authored moving shot separately owns its path continuity, aim/up fields,
timing, safe frame, and obstruction checks.
On return to controls, reconstruct their semantic state from the delivered
pose. For OrbitControls, restore or derive target, recreate the controls to
clear latent spherical/pan/dolly state, and recreate them after changing
camera.up. Verify the first update() preserves the delivered position,
target, orientation, and projection. Pointer-look controllers reconstruct
yaw/pitch in their declared up frame and clear held input on unlock, blur,
owner change, and disposal.
Read controls and handoffs when using stock controls, blends, or authored shots.
Complete when: replay rates reach identical endpoints, the first control update has no jump, and exactly one semantic owner writes each frame.
5. Own precision and temporal history
For simulated or live subjects, consume immutable previous/current presentation samples at the render sample times, not raw fixed-step endpoints. Camera follow, culling, shadows, picking, and velocity share the same sample identity; reset them on stream or identity discontinuities.
Keep global positions in CPU double precision or an explicit high/low representation. Select ordinary-mesh high precision, chunk-local rebasing, or high/low instance data from object type and workload. Rebase only at a declared precision threshold and publish immutable previous/current global-to-render transforms together.
Key temporal state by stable camera/scene identity, projection epoch, origin epoch, render extent/DPR, MRT layout, and velocity convention. A cut, teleport, stable-identity change, incompatible projection, uncompensated rebase, extent or DPR change, or velocity-layout change increments the affected history epoch before rendering. Apply the reset to velocity, temporal AA, DOF, shadow fitting, and every reprojection cache that consumes the changed mapping.
Stock r185 TRAANode owns transient setViewOffset() jitter, expects
drawing-buffer-sized inputs, does not preserve authored view offsets, and has
no public history reset. Recreate it at an incompatible epoch; use a separately
owned or patched node when authored/tiled offsets, XR, resolution scaling, or
cross-rebase preservation are required.
Read temporal history for r185 jitter behavior and camera-relative precision for ULP gates, representation choices, and rebase ordering.
Complete when: current and previous transforms share stable identity and declared epochs, every live subject consumer shares the render-time sample identity, every discontinuity has a reset or proven compensation, and a stationary object produces no false motion across a rebase.
6. Commit, resize, and restore owned state
Write semantic pose and unjittered projection once, then update world and projection matrices. Let the temporal owner apply jitter only inside its render scope. On resize or DPR change, update camera projection, drawing-buffer-sized post resources, jitter scale, and history epoch as one transaction.
Snapshot every field the rig owns: transform, up, parent, layers, matrix
flags, full projection/view-offset state, controls state, output graph, temporal
nodes, origin buffers, and listeners. Disposal restores that snapshot, disposes
owned controls/post/storage/debug resources, and marks the render pipeline dirty
after output-node or output-conversion changes.
Read lifecycle and restoration before modifying a borrowed camera, controls instance, or render pipeline.
Complete when: resize leaves projection and temporal resources coherent, and repeated mount/dispose restores every borrowed field with no surviving listener, GPU resource, or debug object.
7. Verify the rig
Exercise the applicable workload at extreme aspect ratios, full control range, cuts and interrupted blends, projection changes, repeated rebases, resize/DPR changes, and dispose/recreate cycles. Inspect final and diagnostic frames.
Record pose/projection/origin/history owners and epochs; target view/clip/NDC; support-set envelope versus safe frame; near/far; current/previous origin; maximum relative-coordinate magnitude; controls handoff state; and active MRT and temporal resources.
Complete when: every selected branch passes its geometric, handoff, precision, reset, resize, and lifecycle criteria, and each failure localizes to one owner, space conversion, feasibility test, or history epoch.
Routing
Use $threejs-procedural-motion-systems for scene-object motion,
$threejs-scalable-real-time-shadows for shadow fitting,
$threejs-image-pipeline for post/output ownership, and
$threejs-visual-validation for fixed-view and replay evidence.