ozone-tech_owl_prime/docs/TWIN_GEOMETRY_ALIGNMENT.md

Twin Geometry Alignment

Goal

Keep / (continuous twin) and /details (state-machine twin) as projections of one sorter layout — same belt height, zone X/Z, sensors, gate, and category colors — without rewriting both scenes or enabling a physics engine.

What was unified

Concern	Source of truth	Consumers
Conveyor dims, BELT_TOP_Y (0.7 m), zones A/B/C/D, gate, roll cages	src/domain/physicalLayout.ts	Continuous twin, conveyorNetwork, cameras
Shared bridge + details-derived layout	src/domain/layout/sharedLayout.ts	Details TWIN_LAYOUT, route/color tokens
Category / route colors	src/domain/industrialTheme.ts → CATEGORY_COLORS	Both twins, details ROUTE_COLORS
Class route directions (B→+X, C→+Z, D→−Z)	CLASS_ROUTE_DIRECTIONS in sharedLayout	Documentation / consistency

Details twin derivation

itemMotion.ts no longer hardcodes a compact layout (beltY: 0.35, divergent X). It exports:

TWIN_LAYOUT = DETAILS_TWIN_LAYOUT  // from sharedLayout
ROUTE_COLORS = CATEGORY_COLORS
PHYSICS_ENGINE_ENABLED = false

Aligned meters (vs previous details values):

• beltY → BELT_TOP_Y (0.7)
• startX / zoneBX / zoneCZ / zoneDZ → ZONES.A/B/C/D
• cameraX / laserX / gateX → ZONES.CAMERA/LASER/GATE
• rollCageSize → ROLL_CAGE
• Progress keyframes (progressForState) unchanged — only absolute meters moved

Details scene helpers (conveyor materials, zone pads, sensor poles, label Y) use TWIN_LAYOUT.beltY or INDUSTRIAL_PALETTE so the presentation layer tracks the shared height.

Consistency test

src/domain/routeConsistency.test.ts asserts for each non-fault DEMO_PLAYLIST case:

1. classifyItem category === expectedCategory
2. Continuous playback targetCategory matches after seek
3. CATEGORY_COLORS has an entry for that category
4. getPhysicalItemPose at mid-routing has activeRoute === category and phase === 'routing'

Intentional differences (keep)

Continuous (/)	Details (/details)
Engineering HUD: measurement, events, physical surfaces from conveyorNetwork	Presentation / teaching twin: state-machine progress keyframes
Deterministic getPhysicalItemPose along network surfaces	itemPosition3D progress along a simplified X (and Z for C/D)
Light industrial floor / grid (INDUSTRIAL_PALETTE light)	Dark engineering projection of the same palette
Full B receiver spur + chutes + cage floors	Simplified zone boxes + roll-cage visuals
Ultrasonic not a separate continuous station	Details-only ultrasonicX between laser and gate
Cinematic camera / playlist director	OrbitControls + machine-state HUD chips

Motion remains state-machine / kinematic only (PHYSICS_ENGINE_ENABLED === false). Do not enable a physics engine for alignment.

How to extend

1. Change geometry in physicalLayout.ts (or zone map there).
2. Re-export / map in layout/sharedLayout.ts if details needs a new derived field.
3. Keep details keyframe ratios in itemMotion.ts unless timing intentionally changes.
4. Prefer INDUSTRIAL_PALETTE / CATEGORY_COLORS for new materials.