159 lines
3.9 KiB
Markdown
159 lines
3.9 KiB
Markdown
# SplatMap
|
|
|
|
A mobile + web app where users record videos of real-world locations, which are processed into 3D Gaussian Splats and surfaced on a map. At street-level zoom the map transitions into a live 3D splat rendering of that location. Users can create public challenges to send others to specific regions for recording.
|
|
|
|
## Stack
|
|
|
|
- **Mobile** — React Native + Vision Camera + Mapbox
|
|
- **Web map** — Cesium.js + gaussian-splats-3d
|
|
- **Backend** — Django + GeoDjango + PostGIS
|
|
- **Queue** — Celery + Redis
|
|
- **Splatting pipeline** — COLMAP + gsplat on RunPod
|
|
- **Storage** — Wasabi (S3-compatible)
|
|
- **Auth** — Authentik (OIDC)
|
|
- **Notifications** — Firebase Cloud Messaging
|
|
|
|
## Prerequisites
|
|
|
|
- Docker + Docker Compose
|
|
- Node.js 20+ (for the web frontend)
|
|
- A `.env` file (see below)
|
|
|
|
## Setup
|
|
|
|
### 1. Environment
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Open `.env` and set at minimum:
|
|
|
|
```
|
|
SECRET_KEY=<long random string>
|
|
POSTGRES_PASSWORD=<choose a password>
|
|
VITE_CESIUM_ION_TOKEN=<from cesium.com/ion — free tier required>
|
|
```
|
|
|
|
All other values can stay as defaults for local development.
|
|
|
|
> **Cesium Ion token** — register a free account at https://cesium.com/ion/ and create a token
|
|
> with default asset access. Required even in development for imagery and terrain.
|
|
|
|
### 2. Start the backend
|
|
|
|
```bash
|
|
docker compose up --build
|
|
docker compose exec web python manage.py migrate
|
|
```
|
|
|
|
### 3. Start the web frontend
|
|
|
|
The frontend is not containerised — run it locally alongside Docker.
|
|
|
|
```bash
|
|
cd web
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Frontend: http://localhost:5173 (proxies `/api` → Django at :8000)
|
|
|
|
### 4. Create a superuser
|
|
|
|
```bash
|
|
docker compose exec web python manage.py createsuperuser
|
|
```
|
|
|
|
Admin panel: http://localhost:8000/admin
|
|
|
|
## Common commands
|
|
|
|
```bash
|
|
# Start all services
|
|
docker compose up
|
|
|
|
# Start in background
|
|
docker compose up -d
|
|
|
|
# Rebuild after dependency changes
|
|
docker compose up --build
|
|
|
|
# Run migrations
|
|
docker compose exec web python manage.py migrate
|
|
|
|
# Make new migrations after model changes
|
|
docker compose exec web python manage.py makemigrations
|
|
|
|
# Open a Django shell
|
|
docker compose exec web python manage.py shell
|
|
|
|
# Open a psql shell
|
|
docker compose exec db psql -U splatmap splatmap
|
|
|
|
# View logs for a specific service
|
|
docker compose logs -f web
|
|
docker compose logs -f celery
|
|
|
|
# Stop all services
|
|
docker compose down
|
|
|
|
# Stop and remove volumes (wipes the database)
|
|
docker compose down -v
|
|
```
|
|
|
|
## Project structure
|
|
|
|
```
|
|
rcnn/
|
|
├── docker-compose.yml
|
|
├── .env.example
|
|
├── web/ ← Vite + React frontend
|
|
│ ├── package.json
|
|
│ ├── vite.config.ts
|
|
│ └── src/
|
|
│ ├── cesium/ ← Cesium viewer + camera hooks
|
|
│ ├── splat/ ← Gaussian splat layer + renderer
|
|
│ ├── challenges/ ← Challenge layer + panel + creator
|
|
│ ├── api/ ← Typed API wrappers
|
|
│ ├── store/ ← Zustand state slices
|
|
│ ├── auth/ ← Authentik OIDC
|
|
│ └── ui/ ← Shared UI components
|
|
└── backend/
|
|
├── Dockerfile
|
|
├── manage.py
|
|
├── requirements/
|
|
│ ├── base.txt
|
|
│ ├── development.txt
|
|
│ └── production.txt
|
|
├── config/
|
|
│ ├── settings/
|
|
│ │ ├── base.py
|
|
│ │ ├── development.py
|
|
│ │ └── production.py
|
|
│ ├── urls.py
|
|
│ ├── api_urls.py
|
|
│ └── celery.py
|
|
└── apps/
|
|
├── users/
|
|
├── splats/
|
|
├── challenges/
|
|
└── jobs/
|
|
```
|
|
|
|
## API
|
|
|
|
Base URL: `http://localhost:8000/api/v1/`
|
|
|
|
All endpoints require a Bearer token from Authentik. In development you can test unauthenticated endpoints directly, or pass a token via:
|
|
|
|
```
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
docker compose exec web pytest
|
|
```
|