ozone-tech_owl_prime/docs/THREE_D_REWORK_STATUS.md

3D Digital Twin Rework — Current Status

Completed Stages

✅ ЭТАП 0: Preflight

• Branch: dan_branch ✓
• Working tree: clean ✓
• 11 STL models found in input_info/extracted/Stl/ ✓

✅ ЭТАП 1: Audit Current 3D Scene

• Documented problems in docs/THREE_D_REWORK_PLAN.md:
  • Labels overcrowding (12+ labels visible simultaneously)
  • No automatic demonstration
  • Only primitive geometries (box/cylinder)
  • Fixed camera with no guided presets
  • Debug-level scene geometry
  • Non-obvious routing visualization
  • Unrealistic gate/pusher mechanics

✅ ЭТАП 2: Analyze Real 3D Models

• Model Assets Manifest: Created src/data/modelAssets.ts
• STL Models Strategy:
  • ✅ Lightweight STL (< 700 KB): 6 models copied to public/models/
    • Бутылка (319 KB)
    • Тарелка (123 KB)
    • Цилиндр (106 KB)
    • Короб 300×200×200 (29 KB)
    • Короб 400×400×300 (27 KB)
    • ЛанчБокс (566 KB)
  • ⚠️ Heavy STL (> 1 MB): 5 models use fallback primitives
    • Моющее средство (3.5 MB) → box fallback
    • Мешок (5.5 MB) → not used
    • Ручка (2.0 MB) → box fallback
    • Шлем (2.7 MB) → not used
    • Пуфик (629 KB) → cylinder fallback
  • ℹ️ Missing models: 2 items use fallback primitives
    • SKU-010: Boundary box → box fallback
    • SKU-011: Oversized round → cylinder fallback
• Manifest Stats: 6 STL (55%), 5 procedural (45%)

✅ ЭТАП 3: Use Real Models in 3D

• Created: src/components/ThreeD/STLModel.tsx
  • Uses Three.js STLLoader from three/examples
  • Centers and scales geometry automatically
  • Supports fallback on load failure
• Updated: src/components/ThreeD/Item3D.tsx
  • Loads real STL models from modelAssets manifest
  • Fallback to primitives (box/cylinder/sphere) if model unavailable
  • Suspense boundary for async loading

✅ ЭТАП 4: Create Demo Director

• Created: src/domain/demoDirector.ts
  • 12 demo steps: intro → spawn → detection → decision → routing → result
  • Camera presets for each step (overview, detection closeup, gate closeup, routing, result)
  • Auto-play with pause/resume/stop controls
  • Playback speed: 1x, 2x, 0.5x
  • Loop mode for continuous demo
  • Scenario selection support
• Step Durations: Total ~10s per full cycle
• Step-by-Step Labels: Active labels list for each step

✅ ЭТАП 5: Camera Presets (in demoDirector.ts)

• Presets defined:
  • overview: [6.2, 4.8, 6.2] → [0, 0.3, 0]
  • detectionCloseup: [-1.2, 2.5, 3.5] → [-1.2, 0.3, 0]
  • gateCloseup: [1.6, 2.0, 3.0] → [1.6, 0.3, 0]
  • routingB/C/D: dynamic based on category
  • resultB/C/D: dynamic based on category
• ⚠️ Camera transitions not yet implemented (needs Canvas camera animation)

✅ ЭТАП 6: Remove Label Clutter

• Updated: src/components/ThreeD/SceneLabels3D.tsx
  • Clean View (default): Only 5 labels (A/B/C/D + Накопитель)
  • Step-Based Labels:
    • Detection: +Camera CV, +Laser (total 7 labels)
    • At Gate: +Stop-gate (total 6 labels)
    • Routing: +Pusher C/D, +Route arrow (total 7 labels max)
  • Technical Labels Toggle: Shows all sensors/actuators/routes when enabled
  • Removed: ItemProofPanel from 3D scene (info now in 2D proof card only)
• Updated: src/components/ThreeD/SorterDigitalTwin.tsx
  • Added technicalLabelsEnabled prop
  • Added cleanView prop
  • Props passed to SceneLabels3D

✅ ЭТАП 7: Improve Geometry (Partial)

• Updated: src/components/ThreeD/Actuator3D.tsx
  • Gate: Vertical lift mechanism (Y-axis movement) instead of rotation
  • Gate support posts (left + right)
  • Pusher: Extended plate design with stationary base
  • Realistic colors and materials (metalness, roughness)
• Updated: src/components/ThreeD/Conveyor3D.tsx
  • Conveyor side guards (borders)
  • Visible rollers spaced every 1.2m
  • Direction arrow indicator
  • Enhanced accumulator walls
• Updated: src/components/ThreeD/SortingZones3D.tsx
  • Roll-cage C/D: Wireframe edges with EdgesGeometry
  • Vertical posts at corners for visual emphasis
  • Transparent body with visible frame

✅ ЭТАП 12: Tests (Partial)

• Created: src/domain/demoDirector.test.ts
  • Tests: createDemoDirectorState, start/pause/resume/stop
  • Tests: updateAutoDemo (time progression, step transitions)
  • Tests: getDemoStepSequence (order verification: command_sent → actuator_move → route_item)
  • Tests: loop mode, playback speed
  • ✅ All tests passing (43 total)
• Created: src/data/modelAssets.test.ts
  • Tests: manifest coverage for all SKU items
  • Tests: getModelAsset, getSTLAssets, getProceduralAssets
  • Tests: manifest stats (total, stl count, procedural count, percentage)
  • ✅ All tests passing

---

Remaining Work

🔄 ЭТАП 8: Real Routing in 3D

Status: Not started
Priority: Medium (current itemMotion works but is not realistic)

TODO:

• Update src/components/ThreeD/itemMotion.ts:
  • Curved path for C/D routing (not just Z-offset)
  • Sync with Demo Director steps
  • Smooth transitions between waypoints

🔄 ЭТАП 9: Simplify ProductDemo UI + Integrate Demo Director

Status: Not started
Priority: HIGH (required for auto demo)

TODO:

• Update src/components/ProductDemoSection.tsx:
  • Add Demo Director state management
  • Add auto demo controls:
    • "Запустить автодемо" button
    • "Пауза" button
    • Scenario selector (B/C/D/C-priority/Fault/Emergency)
    • "Technical labels" toggle
  • Pass demoDirectorState, technicalLabelsEnabled to SorterDigitalTwin
  • Simplify layout: 3D left, proof card right, timeline below
• Update src/App.tsx:
  • Integrate Demo Director state
  • Sync simulation state with Demo Director steps
  • Handle auto demo lifecycle

🔄 ЭТАП 10: Mobile Behavior

Status: Existing 2D fallback OK, no changes needed
Current behavior: Mobile shows 2D fallback with explanation

🔄 ЭТАП 11: Documentation Updates

Status: Partial (THREE_D_REWORK_PLAN.md created)
TODO:

• Update README.md with:
  • Real models section (which STL used, which fallback)
  • Model assets manifest location
  • Auto demo instructions
• Update docs/DEMO_SCRIPT.md with:
  • Auto demo script (step-by-step)
  • How to show B/C/D/C-priority/Fault
• Update docs/JURY_QA.md with:
  • Q: "Why are some models procedural fallbacks?" → A: Performance (heavy STL > 1 MB)
  • Q: "How does auto demo work?" → A: Demo Director controls step sequence
• Update docs/SUBMISSION_CHECKLIST.md with:
  • STL models checklist
  • Auto demo verification
• Update docs/THREE_D_FEASIBILITY.md with:
  • Real models feasibility
  • Physics engine NOT used (as per requirements)

🔄 ЭТАП 13: Build/Test/Deploy

Status: Build ✅, Test ✅, Docker not checked
TODO:

• Run Docker rebuild: docker compose -p owl -f docker-compose.server.yml up -d --build
• Check domains: arhipovdan.ru, www.arhipovdan.ru, 127.0.0.1:3100
• Verify FPS with STL models

🔄 ЭТАП 14: Visual QA via Browser MCP

Status: Not started
Priority: HIGH (required for verification)

TODO:

• Desktop 1920×1080:
  • Verify max 5 labels in clean view
  • Verify real STL models load (bottle, plate, cylinder, box)
  • Verify auto demo runs (if implemented)
  • Verify gate/pusher movement
  • Verify route visualization
  • Verify proof panel explains decision
• Laptop 1440×900:
  • Verify responsive layout
• Mobile 390×844:
  • Verify 2D fallback active
  • Verify no horizontal scroll

---

Known Issues & Risks

Issues

1. Camera transitions not implemented: Demo Director has camera presets, but SorterDigitalTwin doesn't animate between them yet.
2. Auto demo not integrated: Demo Director exists, but ProductDemoSection/App.tsx don't use it yet.
3. ItemMotion not synced with Demo Director: Current motion is simulation-driven, not demo-driven.

Risks

1. STL Loading Performance: 6 STL models load async, may cause frame drops on low-end devices.
   • Mitigation: Suspense + fallback primitives ensure scene is never empty.
2. Auto Demo Timing: Step durations may feel too fast/slow for user.
   • Mitigation: Playback speed control (1x, 2x, 0.5x).
3. Camera Animation Complexity: Smooth camera transitions between presets require lerp/easing.
   • Mitigation: Can start with instant camera jumps, add smooth transitions later.

---

Next Immediate Steps

1. Integrate Demo Director into ProductDemoSection/App (ЭТАП 9)

   • This is the highest priority to enable auto demo
   • Required before Visual QA can verify auto demo functionality

2. Run Docker Build & Domain Checks (ЭТАП 13)

   • Verify deployment still works with new STL models

3. Visual QA Desktop (ЭТАП 14)

   • Verify STL models load correctly
   • Verify clean view labels (max 5 default)
   • Verify geometry improvements (gate lift, roll-cage wireframe)

4. Documentation Updates (ЭТАП 11)

   • Update README.md with STL models section
   • Update DEMO_SCRIPT.md with auto demo instructions
   • Update JURY_QA.md with new questions

---

Definition of Done (Progress)

• ✅ 1. Real STL models used where possible (6/11 items)
• ✅ 2. Fallback primitives for heavy/missing models (5/11 items)
• ✅ 3. Manifest documents all models (src/data/modelAssets.ts)
• ✅ 4. Labels reduced to max 5 in clean view (SceneLabels3D)
• ⚠️ 5. Technical labels toggle (prop added, but not connected to UI yet)
• ⚠️ 6. Auto demo created (Demo Director exists, but not integrated)
• ✅ 7. Gate/Pusher realistic movement (vertical lift, extended plates)
• ✅ 8. Roll-cage wireframe (C/D zones)
• ✅ 9. Conveyor realistic geometry (side guards, rollers)
• ⚠️ 10. Camera presets defined (in Demo Director, but not used yet)
• ✅ 11. Tests green (43/43 passing)
• ✅ 12. Build green (TypeScript compilation successful)
• ⚠️ 13. Docker not checked yet
• ⚠️ 14. Visual QA not performed yet
• ⚠️ 15. Docs not updated yet

Overall Progress: ~60% complete
Blockers: Auto demo integration (ЭТАП 9) is critical path for remaining work.