Primeros pasos con PersonAnalysis: reconocimiento facial y ReID corporal
Instala InsightFace 2.1, elige Cheetah, registra fotos de referencia y compara personas en imágenes o vídeos locales mediante la API de Python.
Qué vas a construir
PersonAnalysis combina detección de personas, reconocimiento facial y reidentificación corporal (ReID). Compara las personas de la imagen actual con referencias que registras usando tus propios nombres o identificadores.
Esta guía usa la CPU y separa la extracción de características, la comparación y la actualización opcional de referencias corporales. Mantén la misma instancia durante el vídeo para conservar las referencias entre fotogramas.
Antes de empezar
- Python 3.10 o posterior, preferiblemente en un entorno virtual.
- reference.jpg con un único rostro claro, scene.jpg y un vídeo corto clip.mp4 de frecuencia de fotogramas constante que tengas autorización para procesar.
- Conexión a Internet para la primera descarga o un paquete Cheetah completo instalado localmente.
1. Instalar InsightFace 2.1
Ejecuta estos comandos en el entorno Python que vayas a utilizar. El paquete base incluye NumPy, OpenCV y ONNX Runtime para CPU; PersonAnalysis no necesita las extensiones de GUI ni de PrivateFrame.
Para NVIDIA CUDA, instala primero InsightFace, sustituye onnxruntime por onnxruntime-gpu y selecciona CUDAExecutionProvider explícitamente. Consulta la guía del entorno de ejecución. PersonAnalysis admite CPU y CUDA; Cheetah no utiliza CoreML.
python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"2. Elegir Cheetah y preparar los modelos
Empieza con cheetah_s: utiliza entradas de 320×320 para detectar cuerpos y los mismos modelos faciales que Buffalo S. cheetah_l utiliza un detector corporal de 640×640 y los modelos faciales de Buffalo L. Ambos incluyen el mismo modelo ReID y detectan rostros con entradas de 640×640 por defecto.
Si falta el paquete oficial Cheetah, se descarga durante la primera preparación. Para trabajar sin conexión, extrae el archivo completo de la publicación de modelos en ~/.insightface/models/cheetah_s/ o cheetah_l/. Conserva manifest.json, MODEL.LICENSE y los cuatro archivos ONNX juntos, sin una carpeta adicional anidada.
- La guía especifica name="cheetah_s"; el constructor Python usa cheetah_l por defecto.
- Un paquete existente que no sea válido genera un error y no se reemplaza automáticamente. Repáralo con el archivo completo.
3. Registrar, extraer características y comparar
Guarda el ejemplo de imagen como person_image.py junto a reference.jpg y scene.jpg, y ejecuta python person_image.py. La referencia debe contener exactamente un rostro utilizable. Revisa accepted y rejected antes de continuar. person_001 es un identificador que tú asignas.
get() recibe una imagen OpenCV BGR uint8 decodificada y devuelve observaciones actuales. match() las compara con las referencias: primero acepta una coincidencia facial válida y, si no existe, prueba las referencias corporales. Ninguna de las dos llamadas modifica la biblioteca.
auto_update está desactivado en el ejemplo. Al activarlo, update() puede añadir una referencia corporal tras una coincidencia facial fiable y una asociación clara entre rostro y cuerpo. Una coincidencia solo corporal no amplía las referencias ni crea identidades. Compara todo el fotograma antes de actualizar.
import cv2
from insightface.app import PersonAnalysis
image = cv2.imread("scene.jpg")
if image is None:
raise FileNotFoundError("scene.jpg")
with PersonAnalysis(name="cheetah_s") as app:
registration = app.register("person_001", "reference.jpg")
if registration.accepted == 0:
raise ValueError(registration.rejected)
observations = app.get(image)
matches = app.match(observations)
for result in matches:
print(result.person_id, result.matched_by, result.similarity)
auto_update = False
if auto_update:
changes = app.update(matches)
print(changes.added, changes.replaced, changes.skipped)4. Reutilizar la instancia para un vídeo
Guarda el siguiente ejemplo como person_video.py junto a reference.jpg y clip.mp4, y ejecuta python person_video.py. Incluye actualizaciones corporales opcionales; cambia auto_update a False para desactivarlas.
En un vídeo constante de 30 FPS, analysis_fps=2 analiza uno de cada quince fotogramas. Se decodifican todos, pero solo las muestras pasan por los modelos. El límite se refiere al tiempo del vídeo; no garantiza velocidad de procesamiento ni espera a la reproducción. Para frecuencia variable, utiliza las marcas de tiempo reales.
Este ejemplo lee secuencialmente. Para cámaras web o RTSP, el flujo de escritorio conserva el fotograma pendiente más reciente y limita el análisis según el tiempo transcurrido.
import math
import cv2
from insightface.app import PersonAnalysis
analysis_fps = 2
auto_update = True
capture = cv2.VideoCapture("clip.mp4")
try:
if not capture.isOpened():
raise OSError("clip.mp4")
source_fps = capture.get(cv2.CAP_PROP_FPS)
if not math.isfinite(source_fps) or source_fps <= 0:
raise ValueError("CAP_PROP_FPS")
frame_step = max(1, math.ceil(source_fps / analysis_fps))
with PersonAnalysis(name="cheetah_s") as app:
registration = app.register("person_001", "reference.jpg")
if registration.accepted == 0:
raise ValueError(registration.rejected)
frame_index = -1
while True:
ok, frame = capture.read()
if not ok:
if frame_index < 0:
raise OSError("clip.mp4")
break
frame_index += 1
if frame_index % frame_step:
continue
matches = app.match(app.get(frame))
if auto_update:
app.update(matches)
for result in matches:
print(frame_index / source_fps, result.to_dict())
finally:
capture.release()5. Interpretar resultados y ajustar la comparación
person_id es tu identificador registrado o None. matched_by puede ser face, body o None; similarity es la similitud coseno aceptada, no la probabilidad de acierto. Consulta body_bbox, reid_feature y face en result.observation, comprobando si faltan valores.
Una referencia facial no describe la ropa. Registra un recorte corporal conocido con body_images o permite que coincidencias faciales válidas añadan referencias corporales. La ropa, la postura, las oclusiones y la calidad de imagen afectan a la comparación corporal.
Los valores iniciales incluyen face_similarity_threshold=0.45, reid_similarity_threshold=0.85 y max_body_samples=4. Modifícalos mediante PersonConfig al crear una instancia y evalúa vídeos representativos. Consulta la referencia de configuración; estos valores no garantizan una precisión calibrada.
- Las referencias solo residen en la memoria de esta instancia y se liberan al cerrarla. No hay exportación automática de referencias, base de datos ni recuperación tras reiniciar.
- Los resultados describen el fotograma actual. El SDK no mantiene trayectorias, identidades anónimas, duraciones de presencia ni historial de eventos.
- to_dict() permite guardar resultados actuales en tu aplicación; no guarda la biblioteca de referencias y no sirve como entrada de update().
6. Probar la aplicación de escritorio
Evaluation Studio ofrece una interfaz multilingüe para analizar vídeos locales, cámaras web y RTSP con fotos de referencia y controles de frecuencia. Instala la extensión GUI, elige Cheetah S o L y sigue la guía de la interfaz.
python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui7. Evaluar el uso y comprobar la licencia
Prueba rostros claros, vistas de espaldas, ropa similar, oclusiones y personas no registradas. Revisa las coincidencias erróneas y las omitidas antes de elegir umbrales. Mide la velocidad con el equipo y las entradas previstos.
El código del SDK tiene licencia MIT. Los paquetes públicos Cheetah preentrenados tienen una autorización no comercial; poder usar comercialmente el código no concede ese derecho sobre los modelos.
Consulta la guía completa de la API y las condiciones de los modelos. Para despliegues y autorización de modelos, contacta con InsightFace. La descripción de Person Analysis resume las funciones y opciones de modelos.
Evalúa Person Analysis para tu aplicación
Comparte tus fuentes de entrada, entorno de despliegue y requisitos comerciales para hablar de licencias de modelos e integración.
Contactar