Load an image, run RetinaFace, and read the boxes, landmarks and confidence scores it returns — here is the practical Python workflow you can adapt.
Scripting RetinaFace from Python is where the tool really opens up, because once you can reach the raw detections you can fold them into anything — a batch job, a labelling pipeline, or a small app of your own. This guide keeps the focus on the practical loop: input, detection, output.
Setting up your environment
Work inside a virtual environment so the project stays isolated from the rest of your system. Create one, activate it, and install the package along with a library for loading images such as OpenCV or Pillow. Keeping everything in a dedicated environment means you can reproduce the setup later and avoid version clashes with other projects on the same machine.
Loading an image and running detection
The basic loop is short. You read an image from disk into an array, pass that array to RetinaFace, and receive a structured result describing every face it found. A minimal example looks like this:
from retinaface import RetinaFace
import cv2
image = cv2.imread("group_photo.jpg")
faces = RetinaFace.detect_faces(image)
for face_id, face in faces.items():
box = face["facial_area"] # [x1, y1, x2, y2]
score = face["score"] # confidence 0..1
landmarks = face["landmarks"] # eyes, nose, mouth corners
print(face_id, score, box)That loop gives you everything: a bounding box, a confidence score and the landmark coordinates for each detected face. From here it is just a matter of deciding what to do with them.
Reading the results
Each detection carries a facial_area rectangle in pixel coordinates, a score between zero and one, and a landmarks dictionary with the positions of the eyes, nose tip and mouth corners. The box tells you where the face sits, the score tells you how much to trust it, and the landmarks let you align or crop faces consistently. Treat the score as a filter: a simple if score > 0.9 check discards the weak detections before they reach the rest of your code.
Drawing the detections
Visualising the output is the fastest way to confirm everything works. Loop over the faces, draw each rectangle onto a copy of the image, and place a small marker at each landmark. Save or display the result and you will immediately see whether the detector is behaving the way you expect on your particular images. This visual check is worth keeping in your scripts during development.
Processing many images
To handle a folder of images, wrap the detection loop in a routine that walks the directory, runs RetinaFace on each file, and writes the results somewhere structured such as JSON. Storing boxes, scores and landmarks per image gives you a clean dataset you can analyse or feed into the next stage of a pipeline without re-running detection every time.
Common adjustments
Two knobs cover most needs. Raising the confidence threshold trims false positives at the cost of missing some faint faces; lowering it does the reverse. Resizing very large images before detection speeds things up with little accuracy loss, which matters when you process thousands of files. Start with sensible defaults, then tune these two settings against your own data rather than guessing in advance.