89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
# 3D Facility Viewer Refactor Plan: "Project Panopticon"
|
|
|
|
## 1. Executive Summary
|
|
|
|
**Objective:** Transform the 3D Facility Viewer from a basic visualization tool into a comprehensive, "dead simple" interface for managing complex facility operations.
|
|
**Core Philosophy:** "Functional Realism". The interface should look premium and architectural, but every visual element must serve a data-driven purpose.
|
|
**Key Goals:**
|
|
|
|
1. **Human Readability:** Instant understanding of facility layout, plant locations, and environmental status.
|
|
2. **Temporal Visualization:** Ability to visualize data *over time* (e.g., "Show me the spread of this batch over the last 30 days").
|
|
3. **Rapid Location:** Locate any METRC-compliant plant or batch instantly with clear visual guidance.
|
|
|
|
## 2. Visual & UX Overhaul
|
|
|
|
### A. "Clean Industrial" Aesthetics
|
|
|
|
* **Move away from:** Wireframes, glowing neon lines, dark "hacker" themes.
|
|
* **Move toward:** Clean concrete textures, matte metal finishes, soft global illumination, and distinct color coding for biological vs. structural elements.
|
|
* **Lighting:** Use an HDRI environment (`preset="city"` or similar) for realistic reflections, plus soft ambient occlusion (`<ContactShadows />`) to ground objects.
|
|
|
|
### B. "Human Readable" Indicators
|
|
|
|
* **Smart Labels:** Instead of static 3D text floating in space, use `Html` overlays that scale and fade based on camera distance (LOD).
|
|
* *Close Zoom:* Show individual Plant Tags and Health Stats.
|
|
* *Medium Zoom:* Show Rack/Shelf IDs and Aggregate Health.
|
|
* *Far Zoom:* Show Room Names and Environmental Averages.
|
|
* **Beacons:** When searching for a plant, do not just snap the camera. Place a vertical "light beacon" or animated indicator over the target so the user sees *where* it is in context before zooming in.
|
|
|
|
### C. Controls & Navigation
|
|
|
|
* **Hybrid Controls:**
|
|
* **WASD + Right Click Drag:** For "gamer" style free-flight.
|
|
* **Click-to-Move:** Click any room floor to smoothly fly the camera there.
|
|
* **Double-Click:** Focus specifically on a rack or plant.
|
|
* **Tour Mode:** A "Next Issue" button to cycle the camera through all plants with "Critical" health or environmental alerts.
|
|
|
|
## 3. New Feature: "The Time Slider"
|
|
|
|
* **Concept:** A timeline interface at the bottom of the screen.
|
|
* **Function:** Dragging the slider behaves like a video scrubber.
|
|
* *Past:* Visualize historical plant positions (from `PlantLocationHistory`). See where a batch started and how it moved.
|
|
* *Present:* Live state.
|
|
* *Future (Projected):* Visualize yield forecasts or space planning (from `Yield` model).
|
|
|
|
## 4. Technical Architecture Refactor
|
|
|
|
### A. Component Decomposition
|
|
|
|
The current `Facility3DViewerPage.tsx` is becoming monolithic. We will break it down:
|
|
|
|
* `FacilityScene.tsx`: Main canvas and lighting setup.
|
|
* `FacilityWorld.tsx`: Handles the "physics" and separate rooms.
|
|
* `RoomObject.tsx`: Encapsulates a single room's logic (floor, walls, labels).
|
|
* `SmartRack.tsx`: Manages a single rack/section, including its tiers and labels.
|
|
* `PlantSystem.tsx`: Optimized `InstancedMesh` system for rendering thousands of plants efficiently.
|
|
|
|
### B. Data & State Management
|
|
|
|
* **Zustand Store:** Move 3D state (selected plant, camera target, visualization mode, timeline position) out of React `useState` and into a global store for better performance and access outside the canvas.
|
|
* **React Query:** Use for fetching standard API data.
|
|
* **Optimized History Fetching:** New API endpoint needed: `GET /api/facilities/:id/history-snapshot?date=ISO_DATE` to fetch the state of the facility at a specific point in time.
|
|
|
|
## 5. Implementation Phases
|
|
|
|
### Phase 1: The "Visual Foundation" (Current Priority)
|
|
|
|
* [x] Split code into smaller components.
|
|
* [x] Implement "Clean Industrial" materials and lighting. *(Using Environment preset="city", ContactShadows)*
|
|
* [x] Fix the camera controller to be "smooth yet precise". *(CameraControls with WASD + mouse)*
|
|
* [ ] Add "LOD" (Level of Detail) labels that fade in/out. *(Future enhancement)*
|
|
|
|
### Phase 2: "Search & Locate" (Locating Plants) ✅ COMPLETE
|
|
|
|
* [x] Build the "Search Sidebar" with fuzzy search for Tags/Batches. *(PlantSearch.tsx)*
|
|
* [x] Implement the "Beacon" visual indicator system. *(Beacon.tsx - animated light beam)*
|
|
* [x] Add "Highlight Mode": Dim the entire facility *except* the search results. *(dimMode + highlightedTags)*
|
|
|
|
### Phase 3: "The Time Machine"
|
|
|
|
* [ ] Implement the UI Slider component.
|
|
* [ ] Create backend endpoint for historical snapshots.
|
|
* [ ] Wire up the slider to update plant positions dynamically.
|
|
|
|
## 6. Review Request
|
|
|
|
Does this plan align with your vision for "dead simple" and "human readable"? specifically:
|
|
|
|
1. Is the **Time Slider** a desired feature for "complex data over time"?
|
|
2. Do you agree with the **"Clean Industrial"** aesthetic direction?
|