SETUP.md

# Backend Environment Setup

Use Python 3.12. The `.venv/` directory is disposable and ignored by git.

## macOS CPU setup

```bash
cd backend/floor-visualizer
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-mac.txt
VISUALIZER_CONFIG=visualizer.local.toml uvicorn app:app --host 0.0.0.0 --port 8002
```

## NVIDIA GPU setup

Use this on the GPU machine. This installs the CUDA 12.6 PyTorch wheels.

```bash
cd backend/floor-visualizer
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --index-url https://download.pytorch.org/whl/cu126 torch==2.7.0 torchvision==0.22.0
python -m pip install -r requirements-base.txt
VISUALIZER_CONFIG=visualizer.gpu.toml uvicorn app:app --host 0.0.0.0 --port 8002
```

The first GPU run downloads `shi-labs/oneformer_ade20k_swin_large` and the depth model into the Hugging Face cache.

## Notes

- Environment variables override TOML values, for example `SEGMENTATION_MODEL=segformer`.
- `requirements.txt` is a full freeze from an existing environment. Prefer the smaller platform files above when recreating `.venv`.