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