# Getting Started with Python API

# Prerequisites

Python >= 3.10
NumPy

# Installation

pip install realeyes.face_verification

# Quick Start Example

import realeyes.face_verification as fvl
import cv2

verifier = fvl.FaceVerifier('model/model.realZ')

image1 = cv2.imread('image1.jpg')[:, :, ::-1]  # OpenCV reads BGR, we need RGB
image2 = cv2.imread('image2.jpg')[:, :, ::-1]

faces1 = verifier.detect_faces(image1)
faces2 = verifier.detect_faces(image2)

embeddings1 = [verifier.embed_face(face) for face in faces1]
embeddings2 = [verifier.embed_face(face) for face in faces2]

for i, e1 in enumerate(embeddings1):
    for j, e2 in enumerate(embeddings2):
        if verifier.compare_faces(e1, e2).similarity > 0.3:
            print(f'{faces1[i]} from image 1 and {faces2[j]} from image 2 are the same person!')

# Common Patterns

# Image Format

The Python API expects images as NumPy arrays (numpy.ndarray of uint8) in RGB format with shape (height, width, channels). If you use OpenCV (which loads BGR), convert with:

rgb_image = cv2.imread('photo.jpg')[:, :, ::-1]

# 3rd Party Face Detector

You can create Face objects from a 3rd party face detector by providing the image and landmarks:

face = fvl.Face(
    image=rgb_image,
    landmarks=[
        fvl.Point2d(x=100.0, y=120.0),  # left eye
        fvl.Point2d(x=160.0, y=120.0),  # right eye
        fvl.Point2d(x=130.0, y=155.0),  # nose tip
        fvl.Point2d(x=105.0, y=180.0),  # left mouth corner
        fvl.Point2d(x=155.0, y=180.0),  # right mouth corner
    ],
    bbox=fvl.BoundingBox(x=80, y=90, width=100, height=120),
    confidence=0.95
)
embedding = verifier.embed_face(face)

# Detection Quality

Check the quality of a detection before embedding:

for face in faces:
    if face.detection_quality() == fvl.DetectionQuality.Good:
        embedding = verifier.embed_face(face)

# Next Steps

Python API Reference