faktel-face/io.github.cybersafetyid.faktel.face

Package-level declarations

Types

class ArcFaceEmbedder(engine: InferenceEngine, model: ByteArray, options: SessionOptions = SessionOptions()) : FaceEmbedder

ArcFace-family embedder (e.g. MobileFaceNet trained with ArcFace loss). Model I/O contract: [1,3,112,112] RGB normalised to (v - 127.5) / 127.5, output a single embedding vector (typically 512-d).

Face

data class Face(val box: Rect, val landmarks: FaceLandmarks, val score: Double)

A detected face. Coordinates are in the pixel space of the image passed to the detector.

FaceAnalysis

data class FaceAnalysis(val faces: List<Face>, val face: Face?, val quality: FaceQualityReport?, val liveness: LivenessResult?, val issues: List<FaceIssue>)

Result of FaceAnalyzer.analyze.

FaceAnalyzer

class FaceAnalyzer(detector: FaceDetector, quality: FaceQualityAssessor = FaceQualityAssessor(), liveness: LivenessDetector? = null) : AutoCloseable

Selfie pipeline: detect -> quality gate -> optional liveness. Cheap detector runs on every frame; the heavier liveness model only runs on frames that already pass quality checks.

FaceDetector

interface FaceDetector : AutoCloseable

Finds faces in an image. Implementations must return results sorted by descending Face.score.

FaceEmbedder

interface FaceEmbedder : AutoCloseable

Turns an aligned face into a FaceEmbedding.

FaceEmbedding

class FaceEmbedding(values: FloatArray)

An L2-normalised face descriptor. Compare with FaceMatcher; never persist raw images just to re-embed.

FaceIssue

enum FaceIssue : Enum<FaceIssue>

FaceLandmarks

data class FaceLandmarks(val rightEye: Point, val leftEye: Point, val nose: Point, val rightMouth: Point, val leftMouth: Point)

The five facial landmarks produced by the detector.

FaceMatcher

class FaceMatcher(val threshold: Double = 0.3)

Decides whether two embeddings show the same person.

FaceMatchResult

data class FaceMatchResult(val similarity: Double, val isMatch: Boolean)

FaceQualityAssessor

class FaceQualityAssessor(config: FaceQualityConfig = FaceQualityConfig())

Cheap, model-free checks that decide whether a face crop is good enough for liveness or matching.

FaceQualityConfig

data class FaceQualityConfig(val minFaceWidthRatio: Double = 0.2, val minBlurScore: Double = 30.0, val minBrightness: Double = 60.0, val maxBrightness: Double = 200.0, val maxYaw: Double = 25.0, val maxPitch: Double = 25.0, val maxRoll: Double = 25.0)

Thresholds for FaceQualityAssessor. Defaults are conservative starting points; calibrate them on your target cameras before relying on them.

FaceQualityReport

data class FaceQualityReport(val face: Face, val blurScore: Double, val brightness: Double, val pose: HeadPose, val issues: List<FaceIssue>)

HeadPose

data class HeadPose(val yaw: Double, val pitch: Double, val roll: Double)

Approximate head orientation in degrees. Positive yaw = nose displaced towards the right of the image, positive pitch = looking up, positive roll = head tilted clockwise on screen.

LivenessDetector

interface LivenessDetector : AutoCloseable

Decides whether a detected face is a live person or a presentation attack (printed photo, screen replay).

LivenessResult

data class LivenessResult(val realScore: Double, val isLive: Boolean)

MiniFasNetLivenessDetector

class MiniFasNetLivenessDetector(engine: InferenceEngine, model: ByteArray, cropScale: Double = 2.7, threshold: Double = 0.5, options: SessionOptions = SessionOptions()) : LivenessDetector

Passive single-frame liveness using MiniFASNet (Apache-2.0). Model I/O contract: [1,3,80,80] BGR 0..255 in, 3 logits out where class 1 is "real".

YuNetFaceDetector

class YuNetFaceDetector(engine: InferenceEngine, model: ByteArray, config: YuNetFaceDetector.Config = Config(), options: SessionOptions = SessionOptions()) : FaceDetector

Face detector backed by YuNet (face_detection_yunet_2023mar.onnx, MIT). Model I/O contract: input float32 [1,3,640,640] BGR 0..255; outputs cls|obj|bbox|kps for strides 8, 16 and 32.

Functions

headPose

fun Face.headPose(): HeadPose

Estimates HeadPose from the landmarks of this face.