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:

```json
{
  "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