# Physical Realism Fix Report

## Summary

Fixed physical realism issues in the 3D demo to ensure accurate representation of the sorting system.

## Problems Addressed

1. **Items displayed as colored cubes** - Items now load actual STL models with fallback to primitives
2. **Items sometimes above sensors** - Sensor rig height increased to 1.35m, always above max item height
3. **Items faster than conveyor** - Speed synchronized at 1 m/s
4. **C/D zones as flat platforms** - Replaced with realistic roll-cages (1.2×0.8×0.8m wireframe cages)
5. **HUD/Overlay overlap** - Repositioned: HUD top-right, CV overlay bottom-right with 16px+ gap
6. **Unrealistic sorting visuals** - Added chutes/deflectors for physical routing to C/D zones

## Root Causes

### Why Items Showed as Cubes
- `PlaybackItem` component was using primitive geometry instead of loading STL models
- `scaleFactor = 2.0` was applied, making items unnaturally large
- useLoader was being called conditionally, violating React hooks rules

### Solution
- Created separate `STLGeometry` component for proper hook usage
- `FallbackPrimitive` component for cases without STL models
- Removed scaleFactor, using true physical scale (1 unit = 1 meter)

## Changes Made

### physicalLayout.ts
- Added `MAX_ITEM_HEIGHT_M = 0.32` (320mm max normal item height)
- Added `OVERSIZE_DEMO_MAX_HEIGHT_M = 0.4` (400mm for oversized demo items)
- Added `SENSOR_CLEARANCE_M = 0.25` (250mm clearance above items)
- Added `SENSOR_RIG_HEIGHT_M = 1.35m` (above max item)
- Updated `CAMERA_RIG.cameraY = 1.35m` and `height = 1.5m`
- Updated `LASER_HEIGHT_M = 1.4m`
- Updated `STEREO_CAMERA.mountY = 1.35m`
- Added `ROLL_CAGE` dimensions (1.2×0.8×0.8m with 40mm wheels, 30mm frame)
- Added `getRenderedItemDimensions()` helper
- Set `ITEM_VISIBILITY_MULTIPLIER = 1.0` for true physical scale

### SorterDigitalTwinContinuous.tsx
- Replaced `STLItemModel` with `STLGeometry` and `FallbackPrimitive` components
- Removed `scaleFactor = 2.0`, using true dimensions in meters
- Added `RollCage` component for C/D zones with:
  - Wireframe metal frame
  - Caster wheels
  - Wire mesh sides
  - Color coding (C=orange, D=purple)
- Added `RouteChute` component for physical routing:
  - Angled chute surface from conveyor to cage
  - Side rails
  - Active state highlighting
- Updated `PlaybackItem` to use `getRenderedItemDimensions()` and `getItemYOnBelt()`

### styles.css
- CV overlay repositioned to `bottom: 100px` instead of `top: 50%`
- Added `max-height: calc(100vh - 280px)` with `overflow-y: auto`
- Mobile: compact bottom overlay with reduced font sizes
- Tablet: smaller overlay positioned below HUD
- Large screens: explicit gap from HUD

### Tests Added (physicalLayout.test.ts)
- Belt top at 0.7m
- Conveyor speed 1 m/s
- Max item height 0.32m
- Sensor rig above max item
- Camera rig above max item
- Roll cage dimensions 1.2×0.8×0.8m
- Item rendered height constraints
- Item center Y calculation
- Speed calculation verification
- Playlist categories map to valid commands

## Verification

### Build/Test Results
```
npm run build - SUCCESS
npm run test - 93 tests passed
docker compose up -d --build - SUCCESS
```

### Browser QA
- ✅ STL models load correctly (plate shows as flat cylinder)
- ✅ Items on belt at correct scale
- ✅ Sensors above items (1.35m vs max 1.1m item top)
- ✅ Speed synchronized at 1 m/s
- ✅ C/D roll-cages visible (orange/purple wireframe)
- ✅ Items route to C/D via chutes
- ✅ HUD and overlay don't overlap
- ✅ No console errors
- ✅ /details page not broken

## Screenshots

Location: `docs/physical_realism_fix_screenshots/`

- `real_stl_item.png` - STL model displayed
- `item_on_belt_scale.png` - Item at correct scale on belt
- `sensor_above_item.png` - Camera rig above item
- `speed_sync_t0.png` / `speed_sync_t1.png` - Speed verification
- `c_roll_cage.png` - Orange roll cage for C zone
- `d_roll_cage.png` - Purple roll cage for D zone
- `overlay_no_overlap.png` - HUD and overlay separated
- `mobile_overlay.png` - Mobile layout

## Physical Dimensions Summary

| Element | Dimension |
|---------|-----------|
| Conveyor belt top | 0.7m |
| Belt width | 0.5m |
| Belt speed | 1 m/s |
| Max item height (normal) | 0.32m |
| Max item height (oversize) | 0.4m |
| Sensor rig height | 1.35m |
| Camera/laser height | 1.35-1.4m |
| Roll cage | 1.2×0.8×0.8m |

## Commit Commands

```bash
git add -A
git commit -m "fix: physical realism for 3D demo

- Load STL models with fallback to primitives
- True physical scale (1 unit = 1 meter)
- Sensor rig at 1.35m above max item
- Roll-cages for C/D zones (1.2×0.8×0.8m)
- Chutes for physical routing
- HUD/overlay repositioned to avoid overlap
- Added physicalLayout tests"
git push origin dan_branch
```