PersonAnalysis: Einstieg in Gesichtserkennung und Körper-ReID
Installieren Sie InsightFace 2.1, wählen Sie Cheetah, registrieren Sie Referenzfotos und gleichen Sie Personen in Bildern oder lokalen Videos über die Python-API ab.
Was Sie umsetzen
PersonAnalysis verbindet Personenerkennung, Gesichtserkennung und die Wiedererkennung anhand des Körpers (ReID). Personen im aktuellen Bild werden mit Referenzen verglichen, denen Sie selbst Namen oder IDs zuweisen.
Dieser Leitfaden nutzt die CPU und trennt Merkmalsextraktion, Abgleich und optionale Aktualisierung der Körperreferenzen. Verwenden Sie für ein Video dieselbe Instanz, damit die Referenzen zwischen den Bildern erhalten bleiben.
Vor dem Start
- Python 3.10 oder neuer, möglichst in einer virtuellen Umgebung.
- reference.jpg mit genau einem klaren Gesicht, scene.jpg und ein kurzes Video clip.mp4 mit konstanter Bildrate, für dessen Verarbeitung Sie berechtigt sind.
- Internetzugang für den ersten Modelldownload oder ein vollständig lokal installiertes Cheetah-Paket.
1. InsightFace 2.1 installieren
Führen Sie die Befehle in der vorgesehenen Python-Umgebung aus. Das Basispaket enthält NumPy, OpenCV und ONNX Runtime für die CPU. PersonAnalysis benötigt weder die GUI- noch die PrivateFrame-Erweiterung.
Für NVIDIA CUDA installieren Sie zuerst InsightFace, ersetzen anschließend onnxruntime durch onnxruntime-gpu und wählen CUDAExecutionProvider ausdrücklich aus. Folgen Sie dem Leitfaden zur Laufzeitumgebung. PersonAnalysis unterstützt CPU und CUDA; Cheetah verwendet kein CoreML.
python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"2. Cheetah auswählen und Modelle vorbereiten
Beginnen Sie mit cheetah_s: Der Körperdetektor verwendet 320×320 Pixel, die Gesichtsmodelle entsprechen Buffalo S. cheetah_l verwendet einen Körperdetektor mit 640×640 Pixeln und die Gesichtsmodelle von Buffalo L. Beide enthalten dasselbe ReID-Modell und verwenden standardmäßig 640×640 Pixel für die Gesichtserkennung durch den Detektor.
Ein fehlendes offizielles Cheetah-Paket wird bei der ersten Vorbereitung heruntergeladen. Für den Offlinebetrieb entpacken Sie das vollständige Archiv aus der Modellveröffentlichung unter ~/.insightface/models/cheetah_s/ oder cheetah_l/. manifest.json, MODEL.LICENSE und alle vier ONNX-Dateien müssen direkt in diesem Ordner liegen.
- Dieses Beispiel setzt name="cheetah_s" ausdrücklich; der Python-Konstruktor verwendet standardmäßig cheetah_l.
- Ein vorhandenes ungültiges Paket wird gemeldet und nicht automatisch ersetzt. Reparieren Sie es mit dem vollständigen Archiv.
3. Referenz registrieren, Merkmale extrahieren und abgleichen
Speichern Sie das Bildbeispiel als person_image.py neben reference.jpg und scene.jpg und starten Sie python person_image.py. Das Referenzfoto muss genau ein verwendbares Gesicht enthalten. Prüfen Sie accepted und rejected. person_001 ist eine von Ihnen vergebene ID.
get() nimmt ein dekodiertes OpenCV-Bild im Format BGR uint8 entgegen und liefert aktuelle Beobachtungen. match() vergleicht sie mit Referenzen: Ein akzeptierter Gesichtsabgleich hat Vorrang, danach werden Körperreferenzen versucht. Beide Aufrufe lassen die Referenzbibliothek unverändert.
auto_update ist hier ausgeschaltet. Wenn aktiviert, ergänzt update() nur nach einem zuverlässigen Gesichtsabgleich und einer eindeutigen Zuordnung von Gesicht und Körper eine Körperreferenz. Ein reiner Körperabgleich erweitert die Bibliothek nicht und erzeugt keine neuen Identitäten. Gleichen Sie zuerst das gesamte Bild ab und aktualisieren Sie danach.
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. Für Videos dieselbe Instanz wiederverwenden
Speichern Sie das folgende Beispiel als person_video.py neben reference.jpg und clip.mp4 und starten Sie python person_video.py. Hier sind optionale Körperaktualisierungen aktiviert; mit auto_update=False schalten Sie sie aus.
Bei einem Video mit konstanten 30 FPS analysiert analysis_fps=2 jedes fünfzehnte Bild. Alle Bilder werden dekodiert, aber nur ausgewählte Bilder durchlaufen die Modelle. Die Begrenzung bezieht sich auf die Videozeit und garantiert weder Verarbeitungsgeschwindigkeit noch Wiedergabe in Echtzeit. Bei variabler Bildrate sind echte Zeitstempel erforderlich.
Das Beispiel liest sequenziell. Für Webcams und RTSP kann der Desktop-Ablauf das neueste wartende Bild behalten und die Analyse anhand der tatsächlich verstrichenen Zeit begrenzen.
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. Ergebnisse lesen und den Abgleich einstellen
person_id enthält Ihre registrierte ID oder None. matched_by ist face, body oder None. similarity bezeichnet die akzeptierte Kosinusähnlichkeit und ist keine Wahrscheinlichkeit für ein korrektes Ergebnis. Prüfen Sie body_bbox, reid_feature und face in result.observation vor Verwendung auf fehlende Werte.
Ein Gesichtsfoto beschreibt keine Kleidung. Registrieren Sie einen bekannten Körperausschnitt über body_images oder erlauben Sie passende Gesichtsabgleiche als Quelle neuer Körperreferenzen. Kleidung, Haltung, Verdeckung und Bildqualität beeinflussen den Körperabgleich.
Die Standardwerte sind unter anderem face_similarity_threshold=0.45, reid_similarity_threshold=0.85 und max_body_samples=4. Ändern Sie sie beim Erstellen einer neuen Instanz über PersonConfig und prüfen Sie repräsentative Aufnahmen. Die Konfigurationsreferenz erläutert die Parameter; die Standardwerte garantieren keine kalibrierte Genauigkeit.
- Referenzen liegen nur im Arbeitsspeicher dieser Instanz und werden beim Schließen freigegeben. Es gibt keinen automatischen Referenzexport, keine Datenbank und keine Wiederherstellung nach einem Neustart.
- Ergebnisse beschreiben das aktuelle Bild. Das SDK verwaltet keine Bewegungsspuren, anonymen Identitäten, Aufenthaltszeiten oder Ereignisverläufe.
- to_dict() dient zum Speichern aktueller Ausgaben in Ihrer Anwendung. Es sichert keine Referenzbibliothek und liefert keine gültige Eingabe für update().
6. Desktop-Anwendung ausprobieren
Das mehrsprachige Evaluation Studio unterstützt lokale Videos, Webcams und RTSP mit Referenzfotos und einstellbarer Analysehäufigkeit. Installieren Sie die GUI-Erweiterung, wählen Sie Cheetah S oder L und folgen Sie dem GUI-Leitfaden.
python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui7. Anwendungsfall bewerten und Modelllizenz prüfen
Testen Sie klare Gesichter, Rückenansichten, ähnliche Kleidung, Verdeckungen und unbekannte Personen. Prüfen Sie falsche und fehlende Zuordnungen vor der Wahl von Schwellenwerten. Messen Sie die Geschwindigkeit auf der vorgesehenen Hardware mit Ihren Eingaben.
Der SDK-Code steht unter der MIT-Lizenz. Öffentliche vortrainierte Cheetah-Pakete haben eine nichtkommerzielle Lizenz. Die kommerzielle Nutzung des Codes berechtigt nicht automatisch zur kommerziellen Nutzung der Modelle.
Lesen Sie die API-Anleitung und die Modellbedingungen. Für Bereitstellung und Modelllizenzen kontaktieren Sie InsightFace. Die Personenanalyse-Übersicht erläutert Funktionen und Modellwahl.
Person Analysis für Ihre Anwendung evaluieren
Teilen Sie uns Ihre Eingabequellen, Einsatzumgebung und kommerziellen Anforderungen mit, um Modelllizenzen und Integration zu besprechen.
Kontakt aufnehmen