# Saqr — PPE Safety Detection on Unitree G1

Real-time PPE compliance (helmet, vest, boots, gloves, goggles) using YOLO11n.
Runs on a Unitree G1 humanoid with an Intel RealSense D435I. On UNSAFE the
robot speaks a warning and plays the `reject` arm action.

## Layout

```
Saqr/
├── core/           # detection + tracking + events (shared by CLI/GUI/bridge)
├── apps/           # CLI modules (saqr_cli, detect_cli, train_cli, manager_cli, view_stream)
├── gui/            # PySide6 desktop GUI (dev-machine only)
├── robot/          # G1 bridge + DDS controller
├── utils/          # logger, config loader
├── scripts/
│   ├── start_saqr.sh         # the single entry point
│   ├── saqr-bridge.service   # systemd unit (wraps start_saqr.sh)
│   └── deploy.sh             # push code dev machine → robot
├── config/         # logging.json, core_config.json, robot_config.json
├── data/           # dataset/, models/          (gitignored)
├── runtime/        # captures/, runs/           (gitignored)
├── logs/           # per-module .log files      (gitignored)
├── docs/           # DEPLOY.md, start.md, use_case_catalogue.pdf
├── pyproject.toml
└── README.md
```

The project root is auto-detected from `core/paths.py::PROJECT_ROOT` — drop
the `Saqr/` folder anywhere on disk and the code finds itself. Override
with `SAQR_ROOT=/custom/path` if needed.

## Run

The project only runs through **[scripts/start_saqr.sh](scripts/start_saqr.sh)**
(directly or under the `saqr-bridge` systemd unit):

```bash
# On the robot:
sudo systemctl start saqr-bridge       # production
# or
~/Saqr/scripts/start_saqr.sh           # foreground / debug
```

Then on the wireless remote:
- **R2 + X** → start detection
- **R2 + Y** → stop detection

See [docs/DEPLOY.md](docs/DEPLOY.md) for first-time deploy and
[docs/start.md](docs/start.md) for the systemd workflow.

## Deploy

From the dev machine:
```bash
scripts/deploy.sh            # rsync + pip install -e . in the robot's conda env
scripts/deploy.sh --ip …     # custom robot IP
```

## Configure

All tunable values live in JSON — no code edits needed:

- [config/core_config.json](config/core_config.json) — detection, tracking,
  camera, stream, training.
- [config/robot_config.json](config/robot_config.json) — bridge, TTS,
  phrases, arm actions, deploy, start_saqr defaults.
- [config/logging.json](config/logging.json) — log levels per category.

Precedence: **env var > config JSON > code fallback**. Most defaults can be
overridden via env vars without editing the files (`CONDA_ENV`,
`SAQR_SOURCE`, `STREAM_PORT`, `DDS_IFACE`, `ROBOT_IP`, …).

After editing any JSON:
```bash
sudo systemctl restart saqr-bridge
```

## Data & Models

`data/` and `runtime/` are gitignored (too large). Download separately:

- **Dataset**: [testcasque/ppe-detection-qlq3d](https://universe.roboflow.com/testcasque/ppe-detection-qlq3d)
  → YOLOv11 format → unzip to `data/dataset/`.
- **Base weights**: [Ultralytics releases](https://github.com/ultralytics/assets/releases)
  → `yolo11n.pt` into `data/models/`.
- **Saqr fine-tuned weights** (`saqr_best.pt`): produced by training — see
  [docs/DEPLOY.md](docs/DEPLOY.md).

## Training (dev machine, off-path)

Training is done on a workstation, not on the robot. It's a one-off, not
part of the normal run flow:

```bash
python -m apps.train_cli --epochs 100 --batch 16
# best weights land at data/models/saqr_best.pt; deploy with scripts/deploy.sh
```