Class AntelopeUtil

java.lang.Object
com.serinity.accesscontrol.util.AntelopeUtil
public final class AntelopeUtil extends Object
Utility class providing low-level helpers for the AntelopeV2 face detection and recognition pipeline.

Covers the following responsibilities:

  • Converting OpenCV Mat frames to ONNX input tensors for SCRFD (detection) and ArcFace (recognition).
  • L2-normalization and cosine-similarity of embedding vectors.
  • Serialization / deserialization of float[] embeddings to byte[] for database storage.
  • Loading ONNX model sessions from classpath resources.
  • Applying Non-Maximum Suppression (NMS) to raw bounding-box outputs.

NOTE: This class is final and cannot be instantiated.

Since:
2026-02-27
Version:
1.0
Author:
@ZouariOmar (zouariomar20@gmail.com)
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static List<org.opencv.core.Rect>
    applyNMS(List<org.opencv.core.Rect> boxes, List<Float> scores)
    Applies Non-Maximum Suppression to a list of bounding boxes.
    static float[]
    bytesToFloats(byte[] bytes)
    Deserializes a little-endian byte[] back to a float[] embedding.
    static double
    cosineSimilarity(float[] a, float[] b)
    Computes the cosine similarity between two embedding vectors.
    static float[][][][]
    detectionMatToTensor(org.opencv.core.Mat mat)
    Converts an OpenCV BGR Mat to a 4-D SCRFD detection input tensor with pixel values normalized to the range [-1, 1].
    static byte[]
    floatsToBytes(float[] floats)
    Serializes a float[] embedding to a little-endian byte[].
    static float
    iou(org.opencv.core.Rect a, org.opencv.core.Rect b)
    Computes the Intersection-over-Union (IoU) ratio between two rectangles.
    static float[]
    l2Normalize(float[] v)
    L2-normalizes a float vector in-place.
    static ai.onnxruntime.OrtSession
    loadSession(ai.onnxruntime.OrtEnvironment env, String resourcePath)
    Loads an ONNX model from the classpath into an OrtSession.
    static float[][][][]
    recognitionMatToTensor(org.opencv.core.Mat mat)
    Converts a preprocessed (RGB, 112×112) Mat to a 4-D ArcFace input tensor with pixel values normalized to [-1, 1].
    static org.opencv.core.Mat
    recognitionPreprocess(org.opencv.core.Mat face)
    Preprocesses a face crop for the ArcFace recognition model: converts BGR to RGB and resizes to 112×112.

    Methods inherited from class Object

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

  • Method Details

    • detectionMatToTensor

      public static float[][][][] detectionMatToTensor(org.opencv.core.Mat mat)
      Converts an OpenCV BGR Mat to a 4-D SCRFD detection input tensor with pixel values normalized to the range [-1, 1].
      Parameters:
      mat - the BGR image (must be the SCRFD input size, i.e. 640×640)
      Returns:
      tensor of shape [1][3][H][W] with R, G, B channel order

    • recognitionPreprocess

      public static org.opencv.core.Mat recognitionPreprocess(org.opencv.core.Mat face)
      Preprocesses a face crop for the ArcFace recognition model: converts BGR to RGB and resizes to 112×112.
      Parameters:
      face - the cropped face region as a BGR Mat
      Returns:
      RGB Mat resized to 112×112

    • recognitionMatToTensor

      public static float[][][][] recognitionMatToTensor(org.opencv.core.Mat mat)
      Converts a preprocessed (RGB, 112×112) Mat to a 4-D ArcFace input tensor with pixel values normalized to [-1, 1].
      Parameters:
      mat - the RGB 112×112 face image
      Returns:
      tensor of shape [1][3][112][112]

    • l2Normalize

      public static float[] l2Normalize(float[] v)
      L2-normalizes a float vector in-place.
      Parameters:
      v - the input vector
      Returns:
      a new array containing the L2-normalized values

    • cosineSimilarity

      public static double cosineSimilarity(float[] a, float[] b)
      Computes the cosine similarity between two embedding vectors.
      Parameters:
      a - first embedding vector
      b - second embedding vector
      Returns:
      similarity score in the range [-1, 1]; higher is more similar

    • loadSession

      public static ai.onnxruntime.OrtSession loadSession(ai.onnxruntime.OrtEnvironment env, String resourcePath) throws IOException, ai.onnxruntime.OrtException
      Loads an ONNX model from the classpath into an OrtSession. The model is copied to a temporary file before loading.
      Parameters:
      env - the ONNX Runtime environment
      resourcePath - classpath path to the .onnx model file
      Returns:
      a new OrtSession backed by the model
      Throws:
      IOException - if the resource stream cannot be read
      ai.onnxruntime.OrtException - if the ONNX Runtime fails to create the session

    • floatsToBytes

      public static byte[] floatsToBytes(float[] floats)
      Serializes a float[] embedding to a little-endian byte[].
      Parameters:
      floats - the float array to serialize
      Returns:
      byte representation suitable for database storage

    • bytesToFloats

      public static float[] bytesToFloats(byte[] bytes)
      Deserializes a little-endian byte[] back to a float[] embedding.
      Parameters:
      bytes - the raw bytes to deserialize
      Returns:
      the reconstructed float array

    • applyNMS

      public static List<org.opencv.core.Rect> applyNMS(List<org.opencv.core.Rect> boxes, List<Float> scores)
      Applies Non-Maximum Suppression to a list of bounding boxes. Boxes with IoU above NMS_THRESHOLD relative to a higher-scored box are suppressed.
      Parameters:
      boxes - candidate bounding boxes
      scores - corresponding confidence scores
      Returns:
      filtered list of kept bounding boxes

    • iou

      public static float iou(org.opencv.core.Rect a, org.opencv.core.Rect b)
      Computes the Intersection-over-Union (IoU) ratio between two rectangles.
      Parameters:
      a - first rectangle
      b - second rectangle
      Returns:
      IoU value in the range [0, 1]