# EthoVision local tracker worker

This worker runs **DeepLabCut SuperAnimal** pose estimation on your laptop's GPU and pushes results back to the EthoVision server. Pose estimation is computationally heavy, and a shared VPS is a bad place to do it — so we keep the heavy lifting on the machine that actually has the GPU (yours).

## Easiest: run the installer

Go to **Collect → Upload video → Set up tracker on this machine** in the app. That page shows the exact one-line command to paste into your terminal — with your server URL and token already filled in. The command downloads `install.sh` (or `install.ps1` on Windows) and runs it.

The installer handles: Miniconda setup (if needed) → Python 3.11 env → GPU detection → CUDA-matched PyTorch → DeepLabCut 3 + SuperAnimal → worker script → a `run.sh` / `run.bat` launcher with your credentials baked in.

Expected time: ~5 minutes on a decent connection (most of it is PyTorch — ~2 GB). Everything after "click the one-liner" is automatic.

## What you need on your laptop

- **OS:** macOS, Linux, or Windows (PowerShell).
- **GPU:** NVIDIA with driver 470+ ideal (CUDA 11.8/12.1/12.4 wheels are chosen automatically). CPU-only and Apple Silicon (MPS) work but are ~20× slower.
- **Disk:** ~5–6 GB free (Miniconda + PyTorch + DLC + model weights).
- **Network:** outbound HTTP to your EthoVision server.

## After install

Start the worker by running `bash run.sh` (macOS/Linux) or double-clicking `run.bat` (Windows). You'll see:

```
EthoVision worker · id=my-laptop · host=my-laptop · server=http://217.160.138.89:3012
Supported models: superanimal_topviewmouse, superanimal_quadruped
GPU detected: NVIDIA GeForce RTX 4090 · CUDA 12.1
> claimed job job_<uuid> for video <uuid> (superanimal_topviewmouse)
  downloaded → ~/.ethovision-worker/<uuid>/<uuid>.mp4 (28.4 MB)
  done · 15647 frames · 27 keypoints → uploaded <uuid>_full.csv
```

Leave the terminal open. The worker polls every 10 seconds and picks up whatever you queue in the app (via the **Track with DLC** button on a video tile).

## Manual install (fallback)

If the script fails or you want to install by hand:

```bash
# 1. Create env
conda create -n ethovision python=3.11 -y
conda activate ethovision

# 2. PyTorch — pick the CUDA version matching your driver.
# Run `nvidia-smi` and check the driver version in the top-right.
# For CUDA 12.1:
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 3. DeepLabCut + SuperAnimal zoo
pip install "deeplabcut[modelzoo]" requests

# 4. Sanity check
python -c "import torch; print('CUDA:', torch.cuda.is_available())"
```

Then run the worker directly:

```bash
export ETHOVISION_SERVER=http://217.160.138.89:3012
export ETHOVISION_TOKEN=<your-token>
python ethovision_worker.py
```

## Troubleshooting

- **`Unauthorized`** — the token doesn't match. Re-copy from the setup page.
- **`server unreachable`** — check you can `curl <server-url>/` from the laptop; firewall or VPN may block it.
- **`no CUDA GPU detected`** — install the CUDA-enabled PyTorch wheels (step 2 above). Running on CPU works but a 10-minute video takes ~30 min instead of ~2 min.
- **First DLC run is slow** — the SuperAnimal model weights (~400 MB) download on first use. They cache under `~/.deeplabcut/`.
- **Installer stopped halfway** — rerun it. Everything is idempotent: it reuses the conda env and skips already-installed packages.

## Files

- `install.sh` — macOS/Linux installer (bash).
- `install.ps1` — Windows installer (PowerShell).
- `ethovision_worker.py` — the worker itself.
- `requirements.txt` — minimal polling dependency (`requests`).
- `requirements-dlc.txt` — DLC + SuperAnimal zoo. Used by the installer; you rarely need to invoke directly.

## Security

The worker token grants permission to *claim and complete tracking jobs* via the worker API. It doesn't grant full app access, but don't paste it into chat logs or commit it to git. Rotate it by editing `.env.local` on the server and restarting `pm2 restart ethovision`.