ca-grow-ops-manager/docs/3D-VIEWER-ENHANCEMENT-PLAN.md

3D Facility Viewer Enhancement Plan

Overview

Two major enhancements to transform the 3D facility viewer into a comprehensive, investor-ready data visualization platform.

---

Part 1: Visual Style Refactor

Goal

Replace 3D spheres with informative 2D icons/shapes that convey plant stage and health at a glance, while adding grid overlays for human readability.

Current State

• Plants are 3D spheres with color coding
• No visible grid structure
• Stage indicated only by color

Target State

• Flat 2D icons/polygons per growth stage
• Visible row/column/tier grid lines
• Labels for navigation (R1, R2, C1, C2, T1, T2)
• Information-dense schematic view

Technical Approach

Phase 1.1: Plant Icon System

Replace sphereGeometry with stage-specific 2D shapes:

Stage	Shape	Color	Icon Concept
CLONE_IN	Small circle	#3b82f6 Blue	Seedling dot
VEGETATIVE	Leaf polygon	#22c55e Green	3-point leaf
FLOWERING	Flower polygon	#a855f7 Purple	5-petal flower
DRYING	Diamond	#f97316 Orange	Hanging diamond
CURING	Square	#92400e Brown	Jar square
HARVESTED	Circle outline	#6b7280 Gray	Empty circle

Implementation:

• Use @react-three/drei Billboard for camera-facing icons
• Create SVG paths for each stage
• Scale based on zoom level
• Add pulse animation for highlighted plants

Phase 1.2: Grid Visualization

Add visible structure lines:

• Horizontal lines for rows (labeled R1-R8)
• Vertical lines for columns (labeled C1-C10)
• Tier indicators (T1-T3 vertical markers)
• Semi-transparent to not obscure content
• Toggle on/off via UI

Phase 1.3: Section Improvements

• Section boundaries with labeled borders
• Section name prominently displayed
• Row/column count indicator
• Plant count badge

Files to Modify

• PlantSystem.tsx - Replace sphere with icon system
• SmartRack.tsx - Add grid overlay
• types.ts - Add icon type definitions
• New: PlantIcon.tsx, GridOverlay.tsx, SectionLabel.tsx

---

Part 2: Plant Data Visualization System

Goal

Create a comprehensive data card with lifecycle timeline, sensor data, and hierarchical drill-down capabilities.

Components

2.1: PlantDataCard (Main Component)

A glassmorphic panel with:

1. Header - Entity name, METRC tag, quick status badges
2. Timeline - Visual lifecycle from clone to cure
3. Vitals Grid - Health, temp, VPD, humidity gauges
4. Activity Feed - Recent events/actions
5. Actions - Quick action buttons

2.2: Lifecycle Timeline Component

SVG-animated timeline showing plant journey:

• Horizontal timeline with stage nodes
• Filled nodes for completed stages
• Animated current stage indicator
• Day count labels
• Estimated completion
• Click stages to see historical data

SVG Animation Ideas:

• Pulse effect on current stage
• Growth animation between stages
• Color gradient transitions
• Hover: expand stage details

2.3: VitalGauge Component

Radial or bar gauge for sensor readings:

• Animated fill based on value
• Color coding: Green (optimal), Yellow (warning), Red (critical)
• Sparkline showing 24h/7d trend
• Threshold markers
• Animated value counter

2.4: Drill-Down Aggregation

Levels:

Level	Data Shown	Aggregation
Plant	Individual readings	Raw values
Tier	All plants on tier	Avg/Min/Max
Section	All tiers in section	Avg/Min/Max
Room	All sections in room	Avg/Range
Floor	All rooms	Summary counts

Implementation:

• useAggregatedData(level, entityId) hook
• Calculates averages, ranges, outliers
• Returns unified data shape for PlantDataCard

2.5: Mock Data Generator

Rich, realistic demo data including:

• Stage history with dates
• Vitals: health, temperature, humidity, VPD with history
• Touch points, photos, notes, alerts
• Position data

Data Generation:

• Realistic stage duration distributions
• Seasonal temperature variations
• Circadian VPD patterns
• Random but plausible health events
• IPM schedule adherence
• Growth curve progression

---

Part 3: Implementation Phases

Sprint 1: Icon System & Grid (2-3 days)

1. Create PlantIcon component with stage shapes
2. Implement GridOverlay with row/column lines
3. Add section labels with plant counts
4. Toggle for grid visibility
5. Test rendering performance

Sprint 2: Data Card Foundation (2-3 days)

1. Create PlantDataCard shell component
2. Implement glassmorphic styling
3. Add header with entity info
4. Wire up to plant selection
5. Position card in UI (side panel or overlay)

Sprint 3: Lifecycle Timeline (1-2 days)

1. Create LifecycleTimeline component
2. SVG path animations
3. Stage click handlers
4. Day calculation logic
5. Integration with data card

Sprint 4: Vital Gauges (1-2 days)

1. Create VitalGauge component
2. Animated value display
3. Color thresholds
4. Sparkline mini-charts
5. Mock sensor data hookup

Sprint 5: Aggregation & Drill-down (Contextual Data) ✅

1. Contextual Overlays:
   • SummaryOverlay component for room and section aggregation.
   • Hover states for racks/sections showing plant counts, health, and env stats.
   • Floating "Room Summary" badges above rooms in 3D space.
2. Drill-down Interaction:
   • Hover Plant -> Show detailed PlantDataCard (persistent side panel).
   • Hover Section -> Show aggregate data.
3. Data Aggregation:
   • Implemented logic to calculate plant counts and mock environment averages.
   • Displayed aggregates in the summary overlays.

Sprint 6: Mock Data & Polish (Completed) ✅

1. Realistic Mock Data:
   • Updated getMockVitals with deterministic seeding based on Plant ID.
   • Generated realistic "history" arrays for sparklines using sine wave functions.
   • Added Batch IDs and Batch Names.
   • Added "Last Updated" timestamps.
2. UI Refinement:
   • Polished PlantDataCard with glassmorphism and animations.
   • Enhanced section grid labels with hover interactions.
   • Verified rendering and responsiveness.

---

File Structure

frontend/src/components/facility3d/

• coordinates.ts (existing)
• PlantSystem.tsx (refactor to use icons)
• PlantIcon.tsx (NEW - stage icons)
• GridOverlay.tsx (NEW - grid lines)
• SectionLabel.tsx (NEW - section info)
• PlantDataCard/
  • index.tsx
  • LifecycleTimeline.tsx
  • VitalGauge.tsx
  • ActivityFeed.tsx
  • ActionButtons.tsx
• hooks/
  • useAggregatedData.ts
  • usePlantLifecycle.ts
• mocks/
  • plantDataGenerator.ts

---

Success Criteria

1. Visual Clarity - Investors understand facility layout in <5 seconds
2. Stage Recognition - Growth stages identifiable without color dependency
3. Data Richness - All relevant plant data visible in single card
4. Performance - 60fps with 500+ plants rendered
5. Interactivity - Smooth animations, responsive drill-down
6. Realism - Mock data feels like real cultivation facility

---

Open Questions

1. Should the data card be a side panel (persistent) or overlay (modal)?
2. Preferred icon style: geometric shapes, emoji, or custom SVG illustrations?
3. Priority between "pretty" vs "informative" if tradeoffs arise?
4. Any specific Metrc fields that MUST be displayed?