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

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

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.

cd web
npm install
npm run dev

Frontend: http://localhost:5173 (proxies /api → Django at :8000)

4. Create a superuser

docker compose exec web python manage.py createsuperuser

Admin panel: http://localhost:8000/admin

Common commands

# 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

docker compose exec web pytest