Class AntelopeFaceService

java.lang.Object
com.serinity.accesscontrol.service.AntelopeFaceService
public final class AntelopeFaceService extends Object
Combined face detection + recognition service using AntelopeV2 ONNX models.
  • Detection — SCRFD (scrfd_10g_bnkps.onnx)
  • Recognition — ArcFace / GlinT R100 (glintr100.onnx)
Since:
2026-02-27 AntelopeFaceService.java
Version:
1.0
Author:
@ZouariOmar (zouariomar20@gmail.com)

  • Constructor Summary

    Constructors
    Constructor
    Description
    AntelopeFaceService(UserFaceRepository userFaceRepository)
    Creates a new face service and loads detection/recognition ONNX models.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes ONNX runtime resources used by this service.
    org.opencv.core.Mat
    cropFaceSafely(org.opencv.core.Mat frame, org.opencv.core.Rect face)
    Crops the face region from the frame, clamped to frame boundaries.
    org.opencv.core.Rect
    detectBestFace(org.opencv.core.Mat frame)
    Returns the bounding box of the largest detected face, or null.
    float[]
    extractEmbedding(org.opencv.core.Mat face)
    Extracts a 512-d L2-normalized ArcFace embedding from a face crop.
    User
    recognizeUser(org.opencv.core.Mat face)
    Detects and recognizes a face in the full frame in one call.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • AntelopeFaceService

      public AntelopeFaceService(UserFaceRepository userFaceRepository) throws Exception
      Creates a new face service and loads detection/recognition ONNX models.
      Parameters:
      userFaceRepository - repository used to fetch stored user embeddings
      Throws:
      Exception - if model loading fails

  • Method Details

    • detectBestFace

      public org.opencv.core.Rect detectBestFace(org.opencv.core.Mat frame) throws Exception
      Returns the bounding box of the largest detected face, or null.
      Parameters:
      frame - source frame to analyze
      Returns:
      largest detected face bounding box, or null
      Throws:
      Exception - if detection fails

    • cropFaceSafely

      public org.opencv.core.Mat cropFaceSafely(org.opencv.core.Mat frame, org.opencv.core.Rect face)
      Crops the face region from the frame, clamped to frame boundaries.
      Parameters:
      frame - source frame
      face - detected face rectangle
      Returns:
      cropped face matrix

    • recognizeUser

      public User recognizeUser(org.opencv.core.Mat face) throws Exception
      Detects and recognizes a face in the full frame in one call. Returns the matched User or null.
      Parameters:
      face - face crop to identify
      Returns:
      matched user, or null when no match is found
      Throws:
      Exception - if embedding extraction fails

    • extractEmbedding

      public float[] extractEmbedding(org.opencv.core.Mat face) throws Exception
      Extracts a 512-d L2-normalized ArcFace embedding from a face crop.
      Parameters:
      face - face crop to embed
      Returns:
      embedding vector
      Throws:
      Exception - if inference fails

    • close

      public void close() throws ai.onnxruntime.OrtException
      Closes ONNX runtime resources used by this service.
      Throws:
      ai.onnxruntime.OrtException - if resource cleanup fails