110 lines
3.4 KiB
Markdown
110 lines
3.4 KiB
Markdown
# 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:
|
|
```bash
|
|
cd web-app
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Running Locally
|
|
|
|
Start the development server:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
The application will be available at `http://localhost:5173`.
|
|
|
|
### Building for Production
|
|
|
|
Build the application for deployment:
|
|
|
|
```bash
|
|
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):
|
|
```bash
|
|
./docker.sh
|
|
```
|
|
|
|
Or run locally:
|
|
```bash
|
|
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.
|