face-matching-king 0.1.1

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()

# --- 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.similarity)   # e.g. 0.82  (display score, 0.0 – 1.0)
print(result.match)        # True / False
print(result.threshold)    # threshold used for this comparison

print(result.to_dict())
# {
#   "similarity": 0.82,
#   "match":      True,
#   "threshold":  0.70,
# }

---

API Reference

FaceMatcher(threshold, det_size, providers)

Parameter	Type	Description
threshold	float	Similarity cut-off for the match/no-match decision
det_size	(int, int)	Face detector input resolution (default 640×640)
providers	list[str]	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	Display similarity score in the range 0.0 – 1.0
match	bool	True if similarity >= threshold
threshold	float	Threshold used for this comparison

---

License

MIT © Raja Kaushal