face-matching-king 0.1.0

High-accuracy face matching library for comparing faces from images, files, or base64 strings.

face-matching-king

A simple, high-accuracy face matching library for verifying whether two face images belong to the same person.

Compare faces from file paths, numpy arrays, or base64 strings with a single method call.

---

Installation

pip install face-matching-king

GPU support (CUDA): install with the gpu extra to get onnxruntime-gpu:

pip install "face-matching-king[gpu]"

---

Quick Start

from face_matching_king import FaceMatcher

matcher = FaceMatcher()  # loads InsightFace model once

# --- from file paths ---
result = matcher.match_from_path("photo.jpg", "id_card.jpg")

# --- from numpy arrays (BGR, OpenCV format) ---
import cv2
img1 = cv2.imread("photo.jpg")
img2 = cv2.imread("id_card.jpg")
result = matcher.match(img1, img2)

# --- from base64 strings (raw or data-URI) ---
result = matcher.match_from_base64(base64_str_1, base64_str_2)

print(result)
# <MatchResult MATCH | similarity=0.82 | threshold=0.25>

print(result.to_dict())
# {
#   "similarity":     0.82,
#   "raw_similarity": 0.67,
#   "match":          True,
#   "threshold":      0.25,
#   "remark":         "Recommended threshold is 0.25 ..."
# }

---

API Reference

FaceMatcher(threshold=0.25, det_size=(640,640), providers=[...])

Parameter	Type	Default	Description
threshold	float	0.25	Similarity cut-off for match/no-match
det_size	(int, int)	(640, 640)	Face detector input resolution
providers	list[str]	["CUDAExecutionProvider","CPUExecutionProvider"]	ONNX Runtime execution providers

Methods

Method	Input	Description
match(img1, img2)	np.ndarray (BGR)	Compare two OpenCV images
match_from_path(p1, p2)	str | Path	Compare two image files
match_from_base64(b1, b2)	str	Compare two base64 strings or data-URIs

All methods accept an optional threshold keyword to override the instance default for a single call.

MatchResult

Field	Type	Description
similarity	float	Human-friendly score 0.0 – 1.0
raw_similarity	float	Raw cosine similarity -1.0 – 1.0
match	bool	True if similarity >= threshold
threshold	float	Threshold used for this comparison
remark	str	Short human-readable note

---

Threshold Guide

Threshold	Use case
0.20	Very lenient – allow partial matches
0.25	Default – recommended for most ID verification
0.40	Strict – near-identical photos only

---

License

MIT © Raja Kaushal