CV / RetinaFace

RetinaFace

reComputer RK3588

RetinaFace face detection and five-point landmark estimation accelerated by RKNN.

52 downloads

Precision

RKNN

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

Platform

Size

Inference Engine

Getting Started

Armbian 26.8.7 Gnome or newer with OTA overlayroot: Configure Docker storage before running containers to avoid overlay mount errors.

Deploy

sudo docker run --rm --privileged --net=host -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-retinaface:latest \
  python web_service.py --platform rk3588 --model_dir /app/model --camera_id -1 --host 0.0.0.0 --port 8000

REST API

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

Curl

curl http://localhost:8080/v1/chat/completions -d '{
  "model": "retinaface-rknn",
  "messages": [{"role": "user", "content": "Hello"}]
}'

Python

import requests

resp = requests.post(
    "http://localhost:8080/v1/chat/completions",
    json={"model": "retinaface-rknn", "messages": [{"role": "user", "content": "Hello"}]},
)
print(resp.json())

Model Details

Armbian 26.8.7 Gnome or newer with OTA overlayroot: Configure Docker storage before running containers to avoid overlay mount errors.

Quick Start

1. Install Docker

Run the following commands on the development board to install Docker:

bash

# Download installation script
curl -fsSL https://get.docker.com -o get-docker.sh
# Install using Aliyun mirror source
sudo sh get-docker.sh --mirror Aliyun
# Start Docker and enable auto-start on boot
sudo systemctl enable docker
sudo systemctl start docker

2. Run the Project (One command, dual-mode preview)

This page documents the RetinaFace service in reComputer-RK-CV. It detects faces and five facial landmarks with RKNN acceleration and provides image, camera, local-video, and uploaded-video modes.

Model Information

Property	Value
Active model	`model/retinaface_mobile.rknn`
Packaged alternative	`model/retinaface_resnet50.rknn`
Input	`320 x 320` letterboxed RGB
Output	Face box, confidence, and five landmarks
NMS	Fixed IoU threshold of `0.5`

Step A: Pull Images

bash

sudo docker pull ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-retinaface:latest
sudo docker pull ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-retinaface:latest

Step B: Run with One Click

For RK3576:

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-retinaface:latest \
  python web_service.py --platform rk3576 --model_dir /app/model \
  --camera_id -1 --host 0.0.0.0 --port 8000

For RK3588:

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-retinaface:latest \
  python web_service.py --platform rk3588 --model_dir /app/model \
  --camera_id -1 --host 0.0.0.0 --port 8000

Open http://<BOARD_IP>:8000 or /docs. Map /dev/videoN and use --camera_id N for a camera, or pass --video video/test.mp4 for local video.

🔌 API Documentation

1. Face Detection Interface (Predict)

Endpoint: POST /api/models/retinaface/predict

Request Parameters (Multipart/Form-Data):

file: Image file to analyze.
threshold: Optional per-request face confidence threshold from 0 to 1; defaults to the current service configuration.

Usage Examples:

bash

curl -X POST "http://<BOARD_IP>:8000/api/models/retinaface/predict" \
  -F "file=@test.jpg" -F "threshold=0.5"

Each result includes confidence, box as [x1,y1,x2,y2], and five landmarks.

Response Format (JSON):

json

{
  "success": true,
  "model": "retinaface",
  "result": {
    "count": 1,
    "faces": [
      {
        "confidence": 0.96,
        "box": [120, 80, 310, 290],
        "landmarks": [[166, 145], [255, 144], [210, 190], [176, 232], [247, 231]]
      }
    ]
  }
}

2. System Configuration Interface (Config)

Get Current Configuration

Endpoint: GET /api/config

Update System Configuration

Endpoint: POST /api/config
Request Body (JSON): {"threshold":0.5}

The configured threshold applies to preview and video processing. A request-level threshold overrides it for one image.

The generic topk configuration field is reserved for service compatibility and is not used. NMS uses a fixed IoU threshold of 0.5.

Endpoint	Purpose
`GET /api/health`	Platform, model names, and readiness.
`GET /api/video_feed`	Latest face boxes and landmarks as MJPEG.
`POST /api/video/upload`	Upload an MP4.
`POST /api/video/analyze`	Analyze an uploaded `filename`.
`GET /api/video/status`	Progress and errors.
`GET /api/video/list`	Uploaded and generated MP4 files.
`GET /api/video/download/{filename}`	Download a result.

The upstream constructor currently loads retinaface_mobile.rknn explicitly. Using retinaface_resnet50.rknn requires changing task_runtime.py and verifying the same three-output layout; it cannot be selected only by a Docker command parameter. Frames are letterboxed to 320 x 320, converted from BGR to RGB, decoded with prior boxes and five landmarks, restored to source-image coordinates, filtered by confidence, and processed with NMS.

3. Command Line Arguments

Argument	Default	Description
`--platform`	Required	`rk3576` or `rk3588`.
`--model_dir`	`model`	RetinaFace RKNN files and `test.jpg`.
`--camera_id`	`-1`	Camera index; `-1` disables capture.
`--video`, `--video_path`	None	Looping local video; overrides the camera.
`--host` / `--port`	`0.0.0.0` / `8000`	Service address and port.

RKNN_LOG_LEVEL=0 hides confirmed harmless static-shape initialization messages. Remove it when diagnosing RKNN startup.

Real-time Video Stream Interface (Video Feed)

Get the latest annotated MJPEG stream for browser preview:

Endpoint: GET /api/video_feed
Example Usage: <img src="http://<BOARD_IP>:8000/api/video_feed">

🛠️ Developer Guide (Production Recommendations)

Build Local Images

bash

docker build -f docker/rk3576/retinaface.dockerfile \
  -t rk3576-retinaface:local src/rk3576_retinaface

docker build -f docker/rk3588/retinaface.dockerfile \
  -t rk3588-retinaface:local src/rk3588_retinaface

Inputs and Outputs

Input: image, video frame, or camera frame. Output: face boxes, confidence scores, and five landmarks.