caravels-community-simulation/README.md

Community Energy Simulation

A 3D Digital Twin application for simulating and visualizing community energy systems. This application provides an interactive 3D interface to monitor energy consumption and generation across various building types in a community.

Features

3D Digital Twin

• Interactive Scene: Explore the community with full camera controls (pan, rotate, zoom).
• Building Selection: Click on buildings to view detailed information and highlight them in the scene.
• Visual Feedback: Emissive highlighting and selection rings for selected objects.

Simulation Modes

• Simulated Mode: Runs an internal simulation with a day/night cycle, calculating energy loads based on time of day (solar generation curves, evening consumption peaks).
• Live Mode: Connects to an external backend (via Socket.io) to visualize real-time data streaming from Redis Pub/Sub.

Dynamic Configuration

• Add Buildings: Dynamically add new buildings to the scene by specifying ID, Type (house, factory, etc.), and CSV Data path.
• Adjustable Settings:
  • Simulation Speed: Control how fast time passes in simulated mode.
  • Time of Day: Visual day/night cycle.
  • Brightness & Zoom: Customize the visual experience.
  • Data Origin: Configure a base URL for loading remote CSV datasets.
  • Backend URL: Configure the Socket.io server connection for Live Mode.

Tech Stack

• Frontend Framework: Vue.js 3 + Vite
• Language: TypeScript
• 3D Library: Three.js
• State Management: Vue Composition API (Reactivity)
• Data Handling: PapaParse (CSV), Socket.io-client (Real-time)

Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

1. Navigate to the web application directory:

   cd web-app
   

2. Install dependencies:

   npm install
   

Running Locally

Start the development server:

npm run dev

The application will be available at http://localhost:5173.

Building for Production

Build the application for deployment:

npm run build

The output will be in the dist directory.

Docker Deployment

A Dockerfile and docker.sh script are provided for containerization.

To build and push the image (requires Docker login):

./docker.sh

Or run locally:

docker build -t community-simulation .
docker run -p 8080:8080 community-simulation

Usage

Connecting to Live Data

1. Ensure your backend service (Redis + Socket.io bridge) is running.
2. Open the application settings (Gear icon).
3. Select Live (Real Time) mode.
4. Enter your Backend URL (default: http://localhost:8000).
5. Save settings. The app will connect and listen for simulation:update events.

Adding Custom Buildings

1. Click the + Add Building button.
2. Enter a unique ID (e.g., "H99").
3. Select a Type (Determines the 3D model used).
4. Provide a CSV Path relative to the public/ folder or your configured Data Origin (e.g., data/my-building.csv).
5. Click Add.

Project Structure

• web-app/: Main Vue.js application source code.
  • src/components/: UI components (Modals, Overlay).
  • src/composables/: Game logic and state management (useSimulation, useCityObjects, etc.).
  • public/: Static assets (3D models, textures, CSV data).
• js/: Legacy/Prototype JavaScript files.