infer_uniface_search

Search for matching faces in an image database using UniFace library. This algorithm performs one-to-many face matching - given a reference face image, it finds and highlights matching faces in a search image containing multiple people. UniFace is a lightweight production-ready face analysis library built on ONNX Runtime, combining face detection and recognition models (ArcFace/AdaFace).

🚀 Use with Ikomia API

1. Install Ikomia API

We strongly recommend using a virtual environment. If you're not sure where to start, we offer a tutorial here.

pip install ikomia

2. Create your workflow

from ikomia.dataprocess.workflow import Workflow

# Init your workflow
wf = Workflow()

# Set input images
# Input 0: Reference image (single face to search for)
wf.set_image_input(url="https://raw.githubusercontent.com/yakhyo/uniface/refs/heads/main/assets/einstien.png", index=0)
# Input 2: Search image (image with multiple faces)
wf.set_image_input(url="https://raw.githubusercontent.com/yakhyo/uniface/refs/heads/main/assets/scientists.png", index=2)

# Add face search algorithm
searcher = wf.add_task(name="infer_uniface_search", auto_connect=True)

# Run the workflow
wf.run()

# Get object detection output with bounding boxes
img_out =searcher.get_output(2)
obj_detect_out = searcher.get_output(1)
display(img_out.get_image_with_graphics(obj_detect_out))

☀️ Use with Ikomia Studio

Ikomia Studio offers a friendly UI with the same features as the API.

• If you haven't started using Ikomia Studio yet, download and install it from this page.
• For additional guidance on getting started with Ikomia Studio, check out this blog post.

📝 Set algorithm parameters

from ikomia.dataprocess.workflow import Workflow

# Init your workflow
wf = Workflow()

# Set input images
wf.set_image_input(url="https://raw.githubusercontent.com/yakhyo/uniface/refs/heads/main/assets/einstien.png", index=0)
wf.set_image_input(url="https://raw.githubusercontent.com/yakhyo/uniface/refs/heads/main/assets/scientists.png", index=2)

# Add face search algorithm
searcher = wf.add_task(name="infer_uniface_search", auto_connect=True)

searcher.set_parameters({
    "detector_name": "retinaface",
    "conf_thres": "0.5",
    "nms_thres": "0.4",
    "recognizer_name": "arcface",
    "similarity_threshold": "0.6",
    "top_k": "5"
})

# Run the workflow
wf.run()

# Get results
img_out =searcher.get_output(2)
obj_detect_out = searcher.get_output(1)
display(img_out.get_image_with_graphics(obj_detect_out))

Parameters

• detector_name (str, default="retinaface"): Face detection model to use. Options: "retinaface", "yolov5face", "scrfd", "yolov8face".
• conf_thres (float, default="0.5"): Object detection confidence threshold.
• nms_thres (float, default="0.4"): Non-maximum suppression threshold.
• recognizer_name (str, default="arcface"): Face recognition model to use. Options: "arcface", "adaface", "mobileface", "sphereface".
• similarity_threshold (float, default="0.6"): Threshold for determining if a face matches the reference. Only faces with similarity above this threshold will be highlighted as matches.
• top_k (int, default="5"): Maximum number of top matches to consider and evaluate against the similarity threshold.

Note: parameter key and value should be in string format when added to the dictionary.

🔍 Explore algorithm outputs

Every algorithm produces specific outputs, yet they can be explored them the same way using the Ikomia API. For a more in-depth understanding of managing algorithm outputs, please refer to the documentation.

from ikomia.dataprocess.workflow import Workflow

# Init your workflow
wf = Workflow()

# Set input images
wf.set_image_input(url="https://raw.githubusercontent.com/yakhyo/uniface/refs/heads/main/assets/einstien.png", index=0)
wf.set_image_input(url="https://github.com/yakhyo/uniface/blob/main/assets/scientists.png?raw=trueg", index=2)

# Add face search algorithm
searcher = wf.add_task(name="infer_uniface_search", auto_connect=True)

# Run the workflow
wf.run()

# Get object detection output
detection_output = searcher.get_output(1)
print(f"Number of matches found: {len(detection_output.get_objects())}")

# Iterate over all outputs
for output in searcher.get_outputs():
    # Print information
    print(output)
    # Export it to JSON
    output.to_json()

💻 How it works

The algorithm performs one-to-many face matching in these steps:

1. Face Detection: Detects faces in both the reference image and the search image using the selected detector model (RetinaFace, YOLOv5Face, SCRFD, or YOLOv8Face).
2. Reference Embedding: Extracts a face embedding (feature vector) from the reference face using the selected recognizer model (ArcFace, AdaFace, MobileFace, or SphereFace).
3. Search Embeddings: Extracts face embeddings from all detected faces in the search image.
4. Similarity Computation: Computes cosine similarity between the reference embedding and each face in the search image.
5. Match Filtering: Ranks faces by similarity and highlights only those exceeding the similarity threshold (up to top_k matches).

The similarity score ranges from -1 to 1, where higher values indicate greater similarity. Only faces with similarity scores above the threshold are marked as matches. A threshold of 0.6 is commonly used, but you can adjust this based on your use case (higher for stricter matching, lower for more lenient matching).

🔗 Related algorithms

• infer_uniface_detection - Face detection using UniFace
• infer_uniface_verification - Face verification (1:1 matching) using UniFace