Documentation

# Python API Reference

# Module 

import realeyes.face_verification

# Classes

# FaceVerifier

The main entry point for face detection, embedding, and verification operations.

# Constructor 

FaceVerifier(model_file: str, max_concurrency: int = 0)

Loads the model file and sets up processing.

Parameter Type Description Default
model_file str Path to the .realZ model file —
max_concurrency int Maximum allowed concurrency. 0 means automatic (all cores) 0

# Methods

# detect_faces 
def detect_faces(self, image: numpy.ndarray[numpy.uint8]) -> list[Face]

Detects faces on an image.

Parameter Type Description
image numpy.ndarray[numpy.uint8] Image in RGB format, shape (height, width, channels)

Returns: list[Face] — the detected faces.

# embed_face 
def embed_face(self, face: Face) -> list[float]

Returns the embedding vector of a detected face.

Parameter Type Description
face Face The previously detected face

Returns: list[float] — the face embedding vector.

# compare_faces 
def compare_faces(self, embedding1: list[float], embedding2: list[float]) -> Match

Compares two face embeddings.

Parameter Type Description
embedding1 list[float] Embedding of the first face
embedding2 list[float] Embedding of the second face

Returns: Match — match result with similarity score.

# get_model_name 
def get_model_name(self) -> str

Returns the name (version, etc.) of the loaded model.

Returns: str — model name.

# Module Functions

# get_sdk_version_string 

def get_sdk_version_string() -> str

Returns the version string of the SDK (not the model version).

Returns: str — SDK version string.

# Result Classes

# Face

Represents a detected face with landmarks, bounding box, and quality information.

# Constructor 

Face(image: numpy.ndarray[numpy.uint8],
     landmarks: list[Point2d],
     bbox: BoundingBox = BoundingBox(x=0, y=0, width=0, height=0),
     confidence: float = 0.0)

Creates a Face object to support 3rd party face detectors.

Parameter Type Description Default
image numpy.ndarray[numpy.uint8] Image of the face (RGB format) —
landmarks list[Point2d] Face landmarks (5 points). See landmarks specification. —
bbox BoundingBox Bounding box of the face BoundingBox(x=0, y=0, width=0, height=0)
confidence float Detection confidence score 0.0

# Methods

# bounding_box 
def bounding_box(self) -> BoundingBox

Returns: BoundingBox — the bounding box of the detected face.

# confidence 
def confidence(self) -> float

Returns: float — the detection confidence score.

# detection_quality 
def detection_quality(self) -> DetectionQuality

Returns: DetectionQuality — the detection quality of the face.

# landmarks 
def landmarks(self) -> list[Point2d]

Returns: list[Point2d] — the 5 facial landmarks.

# Point2d

2D point for landmark coordinates.

Point2d(x: float, y: float)
Attribute Type Description
x float X coordinate of the point
y float Y coordinate of the point

# BoundingBox

Bounding box for detected faces.

BoundingBox(x: int, y: int, width: int, height: int)
Attribute Type Description
x int X coordinate of the top-left corner
y int Y coordinate of the top-left corner
width int Width of the bounding box in pixels
height int Height of the bounding box in pixels

# Match

Result of face comparison.

Attribute Type Description
similarity float Similarity score between the two faces

# Enums

# DetectionQuality

Detection quality indicator.

Value Description
DetectionQuality.Good No issues detected
DetectionQuality.BadQuality Bad quality detected
DetectionQuality.MaybeRolled Face may be rolled; embeddings could be incorrect