ca-grow-ops-manager/specs/facility-3d-viewer.md

Facility 3D Viewer Specification

Overview

A 3D visualization tool that renders the entire facility structure showing every plant position in real-time. This replaces the complex drag-and-drop Layout Designer with a simpler, data-driven visualization.

Core Concept

Input-Based, Not Drag-and-Drop

• Facility structure is defined via forms with dimension inputs
• Rooms, tables, and sections have numeric dimensions (length × width × height)
• Positions are auto-generated based on row/column/tier configuration
• Focus is on viewing and monitoring, not layout editing

Data Model

Property
  └── Building(s)
       └── Floor(s) [dimensions: width × height]
            └── Room(s) [position: x,y | dimensions: width × height]
                 └── Section(s) [position: x,y | dimensions: width × height | rows × columns × tiers]
                      └── Position(s) [row, column, tier]
                           └── Plant (optional) [batchId, tagNumber, status]

3D Scene Structure

Camera & Controls

• Default View: Bird's eye view of selected floor
• Orbit Controls: Rotate, zoom, pan
• Floor Selector: Quick switch between floors
• Room Focus: Click room to zoom in

Visual Elements

Element	3D Representation	Interactive
Floor	Flat plane with grid	Selectable
Room	Colored box outline	Clickable, shows popup
Table/Rack	Solid platform	Clickable
Plant Position	Small sphere/cube	Hover shows details
Plant (occupied)	Green cylinder	Click for plant info
Empty Position	Gray dot	Click to assign plant

Color Coding

Room Types

• VEG: Green tint
• FLOWER: Purple tint
• MOTHER: Blue tint
• DRY: Orange tint
• CURE: Brown tint

Position Status

• EMPTY: Gray (#888)
• OCCUPIED (Healthy): Green (#22c55e)
• OCCUPIED (Needs Attention): Yellow (#eab308)
• OCCUPIED (Issue): Red (#ef4444)
• RESERVED: Blue (#3b82f6)
• DAMAGED: Dark Red (#991b1b)

UI Layout

┌─────────────────────────────────────────────────────┐
│ 3D Facility Viewer                    [Floor: ▼]   │
├─────────────┬───────────────────────────────────────┤
│             │                                       │
│  Floor      │                                       │
│  Legend     │         3D Canvas                     │
│             │         (React Three Fiber)           │
│  · VEG      │                                       │
│  · FLOWER   │                                       │
│  · MOTHER   │                                       │
│             │                                       │
├─────────────┴───────────────────────────────────────┤
│ Selected: Flower Room A > Table A1 > R3C4          │
│ Plant: GG4-001 | Batch: B001 | Stage: FLOWERING    │
└─────────────────────────────────────────────────────┘

API Requirements

GET /api/layout/floors/:id/3d

Returns complete floor data optimized for 3D rendering:

{
  "floor": {
    "id": "...",
    "name": "Upper Floor",
    "width": 4000,
    "height": 3000,
    "rooms": [
      {
        "id": "...",
        "name": "Flower Room A",
        "type": "FLOWER",
        "posX": 50,
        "posY": 50,
        "width": 900,
        "height": 700,
        "sections": [
          {
            "id": "...",
            "name": "Table A1",
            "type": "TABLE",
            "posX": 50,
            "posY": 50,
            "width": 200,
            "height": 280,
            "rows": 5,
            "columns": 8,
            "positions": [
              {
                "id": "...",
                "row": 1,
                "column": 1,
                "status": "OCCUPIED",
                "plant": {
                  "tagNumber": "GG4-001",
                  "batchId": "...",
                  "batchName": "Gorilla Glue #4 - B001",
                  "status": "ACTIVE"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Implementation Stack

• React Three Fiber: React renderer for Three.js
• @react-three/drei: Useful helpers (OrbitControls, Text, etc.)
• @react-three/postprocessing: Optional visual effects
• Zustand: State management for selections

Component Structure

<Facility3DViewer>
  <FloorSelector />
  <Canvas>
    <Camera />
    <OrbitControls />
    <Lights />
    <Floor3D>
      <Room3D> (for each room)
        <Section3D> (tables/racks)
          <Position3D> (plant spots)
        </Section3D>
      </Room3D>
    </Floor3D>
  </Canvas>
  <InfoPanel />
</Facility3DViewer>

Interactions

1. Hover Position → Show tooltip with address and status
2. Click Position → Select, show details in panel
3. Click Room → Zoom camera to room
4. Click Table → Highlight table, show section stats
5. Double-click Position → Open plant detail modal

Performance Considerations

• Use instanced meshes for positions (hundreds of objects)
• LOD (Level of Detail) for distant objects
• Frustum culling (built into Three.js)
• Lazy load position data per room

Phase 1 Implementation

1. ✅ Seed demo facility with sections and positions (DONE)
2. 🔲 Create /api/layout/floors/:id/3d endpoint
3. 🔲 Install React Three Fiber dependencies
4. 🔲 Create basic Facility3DViewer component
5. 🔲 Render floor plane with room boxes
6. 🔲 Add section rendering (tables as platforms)
7. 🔲 Render positions as spheres
8. 🔲 Add color coding by status
9. 🔲 Add click interactions
10. 🔲 Add info panel

Future Enhancements

• Real-time updates via WebSocket
• Time-lapse view of plant movements
• Heatmap overlay (temperature, humidity from sensors)
• Export 3D snapshot as image
• VR mode for walkthrough