CV / RetinaFace

RetinaFace

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

6 descargas

Precisión

RKNN

Elige el dispositivo que estás usando. La guía de configuración y la documentación se actualizarán en consecuencia.

Plataforma

Tamaño

Motor de inferencia

Primeros pasos

Desplegar

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/rk3576-retinaface:latest \
  python web_service.py --platform rk3576 --model_dir /app/model --camera_id -1 --host 0.0.0.0 --port 8000

API REST

Usa la API REST para ejecutar inferencia. Copia los comandos siguientes.

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())

Detalles del modelo

Inicio rápido

1. Instalar Docker

Ejecute los siguientes comandos en la placa de desarrollo para instalar Docker:

bash

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

2. Ejecutar el proyecto (un comando y vista previa de doble modo)

Esta página documenta el servicio RetinaFace de reComputer-RK-CV. Detecta rostros y cinco puntos faciales con aceleración RKNN y ofrece modos de imagen, cámara, vídeo local y vídeo subido.

Información del modelo

Propiedad	Valor
Modelo activo	`model/retinaface_mobile.rknn`
Alternativa incluida	`model/retinaface_resnet50.rknn`
Entrada	RGB letterbox de `320 x 320`
Salida	Cuadro facial, confianza y cinco landmarks
NMS	Umbral IoU fijo de `0.5`

Paso A: Descargar las imágenes

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

Paso B: Ejecutar con un clic

Para 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

Para 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

Abra http://<BOARD_IP>:8000 o /docs. Asigne /dev/videoN y use --camera_id N para una cámara, o pase --video video/test.mp4 para vídeo local.

🔌 Documentación de la API

1. Interfaz de detección facial (Predict)

Endpoint: POST /api/models/retinaface/predict

Parámetros de solicitud (Multipart/Form-Data):

Suba file; threshold ajusta la confianza facial para esta solicitud.

Ejemplos de uso:

bash

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

Cada resultado incluye confidence, box como [x1,y1,x2,y2] y cinco landmarks. Actualice el umbral de vista previa/vídeo con POST /api/config y JSON como {"threshold":0.5}.

Formato de respuesta (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. Interfaz de configuración del sistema (Config)

Obtener la configuración actual

Endpoint: GET /api/config

Actualizar la configuración del sistema

Endpoint: POST /api/config
JSON: {"threshold":0.5}

El campo genérico topk está reservado para compatibilidad del servicio y no se usa. NMS utiliza un umbral IoU fijo de 0.5.

Endpoint	Finalidad
`GET /api/health`	Plataforma, nombres de modelos y disponibilidad.
`GET /api/video_feed`	Últimos cuadros faciales y landmarks como MJPEG.
`POST /api/video/upload`	Subir un MP4.
`POST /api/video/analyze`	Analizar un `filename` subido.
`GET /api/video/status`	Progreso y errores.
`GET /api/video/list`	Archivos MP4 subidos y generados.
`GET /api/video/download/{filename}`	Descargar un resultado.

El constructor upstream carga actualmente retinaface_mobile.rknn de forma explícita. Usar retinaface_resnet50.rknn requiere cambiar task_runtime.py y verificar la misma disposición de tres salidas; no puede seleccionarse solo con un parámetro del comando Docker. Los fotogramas se ajustan con letterbox a 320 x 320, se convierten de BGR a RGB, se decodifican con cuadros previos y cinco landmarks, se restauran a las coordenadas de origen, se filtran por confianza y se procesan con NMS.

3. Argumentos de línea de comandos

Argumento	Predeterminado	Descripción
`--platform`	Obligatorio	`rk3576` o `rk3588`.
`--model_dir`	`model`	Archivos RKNN de RetinaFace y `test.jpg`.
`--camera_id`	`-1`	Índice de cámara; `-1` deshabilita la captura.
`--video`, `--video_path`	Ninguno	Vídeo local en bucle; prevalece sobre la cámara.
`--host` / `--port`	`0.0.0.0` / `8000`	Dirección y puerto del servicio.

RKNN_LOG_LEVEL=0 oculta mensajes de inicialización de forma estática confirmados como inofensivos. Elimínelo al diagnosticar el inicio de RKNN.

Interfaz de vídeo en tiempo real (Video Feed)

Obtenga el último flujo MJPEG anotado para la vista previa en el navegador:

Endpoint: GET /api/video_feed
Ejemplo de uso: <img src="http://<BOARD_IP>:8000/api/video_feed">

🛠️ Guía para desarrolladores (recomendaciones de producción)

Compilar localmente

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

Entradas y salidas

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