CV / SCRFD

SCRFD 2.5G

SCRFD 2.5G balances speed and accuracy for face detection on reComputer R Series.

Size

3.84 MB

Memory

4GB+

Precision

Hailo HEF / HailoRT 4.23.x

Choose the device you're using, the set up guide and documentation will update accordingly.

Platform

Inference Engine

Getting Started

Deploy

sudo docker run --rm \
  --name cm5-hailo-scrfd-2-5g \
  --privileged \
  --net=host \
  -e PYTHONUNBUFFERED=1 \
  --device /dev/hailo0:/dev/hailo0 \
  -v /usr/lib/libhailort.so.4.23.0:/usr/lib/libhailort.so.4.23.0:ro \
  -v /usr/lib/libhailort.so:/usr/lib/libhailort.so:ro \
  ghcr.io/seeed-projects/recomputer-r20-cv/scrfd:latest \
  python web_detection.py --model_path model/scrfd_2.5g.hef --video_path video/test.mp4

REST API

Use the REST API to run inference. Copy the commands below.

Curl

curl -X POST "http://<R20_IP>:8000/api/models/scrfd/predict" \
  -F "file=@test.jpg"

Python

import requests

resp = requests.post(
    "http://<R20_IP>:8000/api/models/scrfd/predict",
    files={"file": open("test.jpg", "rb")},
    timeout=30,
)
print(resp.json())

Model Details

SCRFD on reComputer R Series (CM5 + Hailo)

SCRFD face detection with boxes, confidence scores, and five-point landmarks on the Hailo-8 accelerator.

This page is adapted from rpi5_hailo8_scrfd/README.md in reComputer-R20-CV. It targets reComputer R Series (CM5 + Hailo) with a PCIe Hailo-8 accelerator.

Hardware and Host Setup

Item	Value
Board	reComputer R Series with Raspberry Pi CM5
Accelerator	Hailo-8 M.2 over PCIe, exposed as `/dev/hailo0`
OS	Raspberry Pi OS Bookworm, aarch64
Host driver	`hailo-all` apt package
Validated HailoRT	4.23.x; host driver, firmware, native library, and Python wheel must share major.minor

bash

sudo apt update
sudo apt install hailo-all
sudo reboot

# After reboot
hailortcli fw-control identify
ls /dev/hailo0

# Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh --mirror Aliyun
sudo systemctl enable docker
sudo systemctl start docker

Run With Demo Video

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 \
  --device /dev/hailo0:/dev/hailo0 \
  -v /usr/lib/libhailort.so.4.23.0:/usr/lib/libhailort.so.4.23.0:ro \
  -v /usr/lib/libhailort.so:/usr/lib/libhailort.so:ro \
  ghcr.io/seeed-projects/recomputer-r20-cv/scrfd:latest \
  python web_detection.py --model_path model/scrfd_500m.hef --video_path video/test.mp4

Open http://<R20_IP>:8000 to view the web preview. The image includes the module source, demo video, HailoRT Python wheel, and HEF files listed below.

The libhailort.so bind mounts intentionally come from the host. If your firmware is not 4.23.0, replace both paths with the version reported by hailortcli fw-control identify; rebuild the image if the major.minor version differs.

USB Camera Mode

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 \
  --device /dev/hailo0:/dev/hailo0 \
  --device /dev/video0:/dev/video0 \
  -v /usr/lib/libhailort.so.4.23.0:/usr/lib/libhailort.so.4.23.0:ro \
  -v /usr/lib/libhailort.so:/usr/lib/libhailort.so:ro \
  ghcr.io/seeed-projects/recomputer-r20-cv/scrfd:latest \
  python web_detection.py --model_path model/scrfd_500m.hef --camera_id 0

Switch HEF variants

Override the image default by passing a different --model_path:

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 \
  --device /dev/hailo0:/dev/hailo0 \
  -v /usr/lib/libhailort.so.4.23.0:/usr/lib/libhailort.so.4.23.0:ro \
  -v /usr/lib/libhailort.so:/usr/lib/libhailort.so:ro \
  ghcr.io/seeed-projects/recomputer-r20-cv/scrfd:latest \
  python web_detection.py --model_path model/scrfd_2.5g.hef --video_path video/test.mp4

HEF Files

HEF	Size	Notes
`scrfd_500m.hef`	3.13 MB	Lightweight face detector
`scrfd_2.5g.hef`	3.84 MB	Balanced face detector
`scrfd_10g.hef`	6.87 MB	Larger face detector

REST API

Prediction endpoint:

text

POST http://<R20_IP>:8000/api/models/scrfd/predict

Example image request:

bash

curl -X POST "http://<R20_IP>:8000/api/models/scrfd/predict" \
  -F "file=@test.jpg"

Common service endpoints:

Endpoint	Method	Purpose
`/`	GET	Web preview UI
`/api/models/scrfd/predict`	POST	Single-frame inference from uploaded image/video or current frame
`/api/video_feed`	GET	MJPEG preview stream
`/api/config`	GET / POST	Read or update runtime thresholds
`/api/video/upload`	POST	Upload a video for offline analysis
`/api/video/analyze`	POST	Start offline analysis
`/api/video/status`	GET	Poll analysis progress
`/api/video/list`	GET	List uploaded and processed videos
`/api/video/download/{filename}`	GET	Download processed output

Development Notes

Source module: src/rpi5_hailo8_scrfd/
Dockerfile: docker/hailo8/scrfd.dockerfile
Main service: web_detection.py wraps HailoRT inference, post-processing, MJPEG preview, REST prediction, and offline video analysis.
When swapping in a custom HEF, keep the output layout compatible with the module post-processing code or update post_process_hailo().

Inputs and Outputs

Input: image, video, or USB camera frame. Output: face boxes, scores, five landmarks, and annotated MJPEG preview.