Bien démarrer avec PersonAnalysis : reconnaissance faciale et ReID corporelle
Installez InsightFace 2.1, choisissez Cheetah, enregistrez des photos de référence et comparez des personnes dans des images ou vidéos locales avec Python.
Ce que vous allez mettre en place
PersonAnalysis associe détection de personnes, reconnaissance faciale et réidentification corporelle (ReID). Les personnes présentes dans l’image sont comparées à des références enregistrées sous les noms ou identifiants de votre choix.
Ce guide utilise le CPU et sépare extraction des caractéristiques, comparaison et mise à jour facultative des références corporelles. Gardez la même instance pendant une vidéo pour conserver les références entre les images.
Avant de commencer
- Python 3.10 ou ultérieur, de préférence dans un environnement virtuel.
- reference.jpg avec un seul visage net, scene.jpg et une courte vidéo clip.mp4 à fréquence constante que vous êtes autorisé à traiter.
- Un accès Internet pour le premier téléchargement, ou un paquet Cheetah complet installé localement.
1. Installer InsightFace 2.1
Exécutez ces commandes dans l’environnement Python prévu. Le paquet de base contient NumPy, OpenCV et ONNX Runtime pour CPU. PersonAnalysis ne nécessite pas les extensions GUI ou PrivateFrame.
Pour NVIDIA CUDA, installez d’abord InsightFace, remplacez onnxruntime par onnxruntime-gpu, puis sélectionnez explicitement CUDAExecutionProvider. Consultez le guide d’exécution. PersonAnalysis prend en charge CPU et CUDA ; Cheetah n’utilise pas CoreML.
python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"2. Choisir Cheetah et préparer les modèles
Commencez par cheetah_s : son détecteur de corps utilise une entrée de 320×320 et ses modèles faciaux sont ceux de Buffalo S. cheetah_l utilise un détecteur de corps de 640×640 et les modèles faciaux de Buffalo L. Le modèle ReID est commun, et la détection faciale utilise 640×640 par défaut dans les deux paquets.
Un paquet officiel Cheetah absent est téléchargé à la première préparation. Hors ligne, récupérez l’archive complète sur la page des modèles et décompressez-la dans ~/.insightface/models/cheetah_s/ ou cheetah_l/. manifest.json, MODEL.LICENSE et les quatre fichiers ONNX doivent être au même niveau, sans dossier supplémentaire imbriqué.
- Ce guide indique explicitement name="cheetah_s" ; le constructeur Python choisit cheetah_l par défaut.
- Un paquet déjà présent mais invalide est signalé et non remplacé automatiquement. Réparez-le avec l’archive complète.
3. Enregistrer, extraire les caractéristiques et comparer
Enregistrez l’exemple image dans person_image.py à côté de reference.jpg et scene.jpg, puis lancez python person_image.py. La référence doit contenir exactement un visage exploitable. Vérifiez accepted et rejected. L’identifiant person_001 est choisi par vous.
get() accepte une image OpenCV BGR uint8 décodée et renvoie les observations actuelles. match() les compare aux références : une correspondance faciale acceptée est prioritaire, puis les références corporelles sont essayées. Ces deux appels ne modifient pas la bibliothèque.
auto_update est désactivé dans cet exemple. Une fois activé, update() peut ajouter une référence corporelle après une correspondance faciale fiable et une association visage-corps sans ambiguïté. Une correspondance corporelle seule n’ajoute aucune référence et ne crée aucune identité. Comparez toute l’image avant de mettre à jour.
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. Réutiliser la même instance pour une vidéo
Enregistrez l’exemple suivant dans person_video.py à côté de reference.jpg et clip.mp4, puis lancez python person_video.py. La mise à jour facultative des références corporelles est activée ; définissez auto_update sur False pour la désactiver.
Pour une vidéo à 30 FPS constants, analysis_fps=2 analyse une image sur quinze. Toutes sont décodées, mais seules les images retenues passent dans les modèles. Cette limite porte sur le temps de la vidéo, sans garantir la vitesse de calcul ni attendre la lecture. Pour une fréquence variable, utilisez les horodatages réels.
Cet exemple lit les images dans l’ordre. Pour les webcams ou RTSP, le mode bureau peut conserver l’image en attente la plus récente et limiter l’analyse selon le temps écoulé.
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. Lire les résultats et régler la comparaison
person_id contient votre identifiant ou None. matched_by vaut face, body ou None ; similarity est la similarité cosinus retenue, pas une probabilité de justesse. Consultez body_bbox, reid_feature et face dans result.observation après avoir vérifié leur présence.
Une photo de visage ne décrit pas les vêtements. Enregistrez un recadrage corporel identifié avec body_images ou laissez les correspondances faciales admissibles ajouter des références. Vêtements, pose, occultation et qualité d’image influencent la comparaison corporelle.
Les valeurs par défaut comprennent face_similarity_threshold=0.45, reid_similarity_threshold=0.85 et max_body_samples=4. Modifiez-les via PersonConfig à la création d’une nouvelle instance et évaluez des vidéos représentatives. Consultez la référence des paramètres ; ces valeurs ne garantissent pas une précision calibrée.
- Les références restent dans la mémoire de cette instance et sont libérées à sa fermeture. Il n’existe ni export automatique des références, ni base de données, ni restauration après redémarrage.
- Les résultats décrivent l’image actuelle. Le SDK ne conserve ni trajectoires, ni identités anonymes, ni durées de présence, ni historique d’événements.
- to_dict() aide votre application à enregistrer les résultats actuels ; ce n’est pas une sauvegarde de la bibliothèque et son résultat ne peut pas être transmis à update().
6. Essayer l’application de bureau
Evaluation Studio propose une interface multilingue pour les vidéos locales, webcams et flux RTSP, avec photos de référence et réglage de la fréquence d’analyse. Installez l’extension GUI, choisissez Cheetah S ou L et suivez le guide de l’interface.
python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui7. Évaluer l’usage et vérifier les licences
Testez des visages nets, des vues de dos, des vêtements similaires, des occultations et des personnes non enregistrées. Examinez les correspondances erronées ou manquées avant de choisir les seuils. Mesurez la vitesse avec le matériel et les entrées prévus.
Le code du SDK est sous licence MIT. Les paquets publics Cheetah préentraînés portent une autorisation non commerciale ; l’utilisation commerciale du code n’autorise pas celle des modèles.
Consultez le guide complet de l’API et les conditions des modèles. Pour un déploiement et les autorisations, contactez InsightFace. La présentation de Person Analysis décrit les fonctions et les modèles.
Évaluer Person Analysis pour votre application
Présentez vos sources d’entrée, votre environnement de déploiement et vos besoins commerciaux pour discuter des licences et de l’intégration.
Nous contacter