PersonAnalysis quickstart: face recognition and body ReID
Install InsightFace 2.1, choose Cheetah, register reference photos, and match people in images or local video with the Python API.
What you will build
PersonAnalysis combines person detection, face recognition, and body re-identification (ReID). It compares people in the current image with references that you register under your own names or IDs.
This guide uses CPU inference and separates feature extraction, matching, and optional body-reference updates. Keep one instance open while processing a video so its references remain available across frames.
Before you start
- Python 3.10 or newer, preferably in a virtual environment.
- reference.jpg with exactly one clear face, scene.jpg, and a short constant-frame-rate clip.mp4 that you are authorized to process.
- Internet access for the first model download, or a complete Cheetah model package installed locally.
1. Install InsightFace 2.1
Run the following commands with the Python environment you intend to use. The base package includes NumPy, OpenCV, and the CPU version of ONNX Runtime; PersonAnalysis does not need the GUI or PrivateFrame extras.
For NVIDIA CUDA, install InsightFace first, then replace onnxruntime with onnxruntime-gpu and explicitly select CUDAExecutionProvider. See the runtime guide. PersonAnalysis supports CPU and CUDA; Cheetah does not use CoreML.
python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"2. Choose Cheetah and prepare the model files
Start with cheetah_s. Its body detector uses 320×320 inputs and it includes the same face detection and recognition models as Buffalo S. cheetah_l uses a 640×640 body detector and the face models from Buffalo L. Both include the same body ReID model and use 640×640 face detection by default.
A missing official Cheetah package downloads on first preparation. For offline use, get the complete archive from the model release and extract it into ~/.insightface/models/cheetah_s/ or cheetah_l/. Keep manifest.json, MODEL.LICENSE, and all four ONNX files together, without an extra nested package folder.
- Set name="cheetah_s" explicitly for this tutorial; the Python constructor defaults to cheetah_l.
- An existing invalid package is reported rather than replaced automatically. Repair it with the complete archive.
3. Register a reference, extract features, and match
Save the image example as person_image.py beside reference.jpg and scene.jpg, then run python person_image.py. The reference must contain exactly one usable face. Check accepted and rejected before continuing; the identity label person_001 is supplied by you.
get() accepts a decoded OpenCV BGR uint8 image and returns current observations. match() compares them with references, using an accepted face match first and body references as a fallback. Neither call changes the reference library.
The example leaves auto_update disabled. Enable it to let update() add a body reference after a reliable face match with a clear face/body association. A body-only match cannot add references, and updates never create new identities. Match the whole frame before updating it.
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. Reuse the same instance for a video
Save the next example as person_video.py beside reference.jpg and clip.mp4, then run python person_video.py. This example enables optional body-reference updates; set auto_update to False to disable them.
For a 30 FPS constant-frame-rate file, analysis_fps=2 analyzes every fifteenth frame. All frames are decoded, but only sampled frames enter the models. The rate is a limit in video time, not a promised processing speed or a playback delay. Use actual timestamps for variable-frame-rate files.
The example reads sequentially. For webcams or RTSP, the desktop workflow can keep the newest pending frame and apply an elapsed-time analysis limit.
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. Read results and tune matching
person_id is your registered ID or None. matched_by is face, body, or None; similarity is the accepted cosine similarity, not a probability of correctness. Read body_bbox, reid_feature, and face from result.observation, checking for missing values.
A face reference alone does not describe clothing. Register a known body crop with body_images, or allow qualified face matches to add body references. Body matching depends on clothing, pose, occlusion, and image quality.
Defaults include face_similarity_threshold=0.45, reid_similarity_threshold=0.85, and max_body_samples=4. Change them through PersonConfig when creating a new instance and evaluate on representative footage; see the configuration reference. These defaults are not calibrated accuracy guarantees.
- References live only in this instance's memory and are released when it closes. There is no automatic reference export, database, or restart recovery.
- Results describe the current frame. The SDK does not maintain tracks, anonymous identities, appearance durations, or event history.
- to_dict() helps save current outputs in your application; it is not a saved reference library and cannot be passed to update().
6. Try the desktop workflow
The multilingual Evaluation Studio offers Person Analysis for local videos, webcams, and RTSP, with reference photos and analysis-rate controls. Install the GUI extra below, select Cheetah S or L, and follow the GUI guide.
python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui7. Evaluate your use case and check model licensing
Try clear faces, back views, similar clothing, occlusion, and unknown people. Review incorrect matches and missed matches before choosing thresholds. Measure processing speed on the hardware and inputs you plan to use.
The SDK code is MIT licensed. Public pretrained Cheetah packages carry a non-commercial grant; commercial use of the code does not grant commercial use of the models.
Read the full API guide and model terms. For deployment and model authorization, contact InsightFace. Return to the Person Analysis overview for capabilities and model choices.
Evaluate Person Analysis for your application
Share your input sources, deployment environment and commercial requirements to discuss model licensing and integration.
Contact us