102 lines
3.2 KiB
Markdown
102 lines
3.2 KiB
Markdown
# Saqr — PPE Safety Detection on Unitree G1
|
|
|
|
Real-time PPE compliance (helmet, vest, boots, gloves, goggles) using YOLO11n,
|
|
designed to run 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/ # python package
|
|
core/ # detection + tracking + events (shared by CLI/GUI/bridge)
|
|
apps/ # CLI entry points (saqr, detect, train, manager, view_stream)
|
|
gui/ # PySide6 desktop GUI
|
|
robot/ # G1 bridge + DDS controller
|
|
utils/ # logger
|
|
scripts/ # deploy.sh, start_saqr.sh, run_local.sh, run_robot.sh, systemd unit
|
|
config/ # logging.json
|
|
data/ # dataset/, models/ (gitignored)
|
|
runtime/ # captures/, logs/, runs/ (gitignored)
|
|
docs/ # DEPLOY.md, start.md, use_case_catalogue.pdf
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# Install the package (editable)
|
|
pip install -e .
|
|
|
|
# Local dev run (webcam)
|
|
saqr --source 0
|
|
|
|
# PySide6 GUI
|
|
pip install -e ".[gui]"
|
|
saqr-gui
|
|
|
|
# On the Unitree G1 (bridge owns the R2+X / R2+Y flow)
|
|
saqr-bridge --iface eth0 --source realsense --headless -- --stream 8080
|
|
```
|
|
|
|
Without installing, everything still works via `python -m`:
|
|
|
|
```bash
|
|
python -m saqr.apps.saqr_cli --source 0
|
|
python -m saqr.robot.bridge --iface eth0 --source realsense --headless
|
|
```
|
|
|
|
## Docs
|
|
|
|
- [docs/DEPLOY.md](docs/DEPLOY.md) — full deploy + robot setup.
|
|
- [docs/start.md](docs/start.md) — systemd auto-start workflow.
|
|
- [docs/use_case_catalogue.pdf](docs/use_case_catalogue.pdf) — PPE use-case spec.
|
|
|
|
## Data & Models
|
|
|
|
The `data/` and `runtime/` directories are excluded from git (too large).
|
|
Download them separately before training or running inference.
|
|
|
|
### `data/` — dataset and pre-trained weights
|
|
|
|
Expected contents:
|
|
|
|
```
|
|
data/
|
|
dataset/
|
|
train/{images,labels}/
|
|
valid/{images,labels}/
|
|
test/{images,labels}/
|
|
data.yaml
|
|
models/
|
|
saqr_best.pt # Saqr YOLO11n fine-tuned on PPE
|
|
saqr_last.pt
|
|
yolo11n.pt # base YOLO11n
|
|
yolo26n.pt # base YOLO26n
|
|
```
|
|
|
|
Download:
|
|
|
|
- **Dataset** (PPE, Roboflow): [testcasque/ppe-detection-qlq3d](https://universe.roboflow.com/testcasque/ppe-detection-qlq3d)
|
|
Open the Roboflow link → *Download Dataset* → format **YOLOv11** → unzip into `data/dataset/`.
|
|
- **Base YOLO weights**: [Ultralytics assets releases](https://github.com/ultralytics/assets/releases)
|
|
Grab `yolo11n.pt` (and optionally `yolo26n.pt`) into `data/models/`.
|
|
- **Saqr fine-tuned weights** (`saqr_best.pt`, `saqr_last.pt`):
|
|
Produced by training — see "Training" below. Or request from the maintainer.
|
|
|
|
Place everything under `data/` so the tree matches above.
|
|
|
|
### `runtime/` — training output (optional)
|
|
|
|
Auto-generated when you run training. Not required for inference.
|
|
Contains confusion matrices, PR curves, batch previews, and the raw weights
|
|
under `runtime/runs/train/saqr_det/weights/`.
|
|
|
|
### Training
|
|
|
|
```bash
|
|
# after placing the dataset in data/dataset/ and base weights in data/models/
|
|
python -m saqr.apps.train_cli --data data/dataset/data.yaml --weights data/models/yolo11n.pt
|
|
```
|
|
|
|
Outputs land in `runtime/runs/train/saqr_det/`. Copy the best checkpoint to
|
|
`data/models/saqr_best.pt` to use it at inference time.
|