FaceDetector class

A complete face detection and analysis system using TensorFlow Lite models.

This class orchestrates four TensorFlow Lite models to provide comprehensive facial analysis:

Face detection with 6 keypoints (eyes, nose, mouth, tragions)
468-point face mesh for detailed facial geometry
Iris landmark detection with 76 points per eye (71 eye mesh + 5 iris keypoints)
Face embedding for identity vectors (192-dimensional)

All inference runs in a background isolate, ensuring the UI thread is never blocked during detection.

Usage

// One-step construction
final detector = await FaceDetector.create();

// Or two-step, if you need to configure between construction and init
final detector = FaceDetector();
await detector.initialize();

// Detect faces with full mesh and iris tracking
final faces = await detector.detectFacesFromBytes(
  imageBytes,
  mode: FaceDetectionMode.full,
);

// Clean up when done
await detector.dispose();

Detection Modes

FaceDetectionMode.fast: Basic detection with 6 keypoints only
FaceDetectionMode.standard: Adds 468-point face mesh
FaceDetectionMode.full: Adds iris tracking (default, most detailed)

Lifecycle

Create instance with FaceDetector()
Call initialize to load TensorFlow Lite models
Check isReady to verify models are loaded
Call detectFacesFromBytes to analyze images
Call dispose when done to free resources

Constructors

FaceDetector(): Creates a new face detector instance.

Properties

hashCode → int: The hash code for this object.
no setterinherited
isEmbeddingReady → bool: Returns true if the embedding model is loaded and ready.
no setter
isReady → bool: Returns true if all models are loaded and ready for inference.
no setter
isSegmentationReady → bool: Returns true if the segmentation model is loaded and ready.
no setter
minFaceSize → double: Minimum face size a detection must have to be returned, expressed as face width divided by image width (0.0 to 1.0), matching Google ML Kit's minFaceSize.
no setter
minScore → double: Minimum detection confidence (0.0 to 1.0) a face must have to be returned.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

detectFaces(Uint8List imageBytes, {FaceDetectionMode mode = FaceDetectionMode.full}) → Future<List<Face>>: Deprecated alias for detectFacesFromBytes.
detectFacesFromBytes(Uint8List imageBytes, {FaceDetectionMode mode = FaceDetectionMode.full}) → Future<List<Face>>: Detects faces in encoded image bytes and returns detailed results.
detectFacesFromCameraFrame(CameraFrame frame, {FaceDetectionMode mode = FaceDetectionMode.full, int? maxDim}) → Future<List<Face>>: Detects faces directly from a CameraFrame produced by prepareCameraFrame.
detectFacesFromCameraImage(Object cameraImage, {FaceDetectionMode mode = FaceDetectionMode.full, CameraFrameRotation? rotation, bool? isBgra, int? maxDim}) → Future<List<Face>>: One-call wrapper for live camera streams: takes a CameraImage-shaped object directly (any object exposing width, height, and planes with bytes / bytesPerRow / bytesPerPixel) and runs YUV packing, colour conversion, rotation, and downscale in the detection isolate - all off the UI thread.
detectFacesFromFilepath(String path, {FaceDetectionMode mode = FaceDetectionMode.full}) → Future<List<Face>>: Detects faces in an image file at path.
detectFacesFromMat(Mat image, {FaceDetectionMode mode = FaceDetectionMode.full}) → Future<List<Face>>: Detects faces in a pre-decoded cv.Mat image.
detectFacesFromMatBytes(Uint8List bytes, {required int width, required int height, int matType = 16, FaceDetectionMode mode = FaceDetectionMode.full}) → Future<List<Face>>: Detects faces from raw pixel bytes without constructing a cv.Mat first.
detectFacesFromVideo(Object video, {FaceDetectionMode mode = FaceDetectionMode.full}) → Future<List<Face>>: Detects faces directly from a live <video> element. Web-only.
detectFacesWithSegmentation(Uint8List imageBytes, {FaceDetectionMode mode = FaceDetectionMode.full, IsolateOutputFormat outputFormat = IsolateOutputFormat.float32, double binaryThreshold = 0.5}) → Future<DetectionWithSegmentationResult>: Detects faces and generates segmentation mask in parallel.
detectFacesWithSegmentationFromCameraFrame(CameraFrame frame, {FaceDetectionMode mode = FaceDetectionMode.full, IsolateOutputFormat outputFormat = IsolateOutputFormat.float32, double binaryThreshold = 0.5, int? maxDim}) → Future<DetectionWithSegmentationResult>: Detects faces and generates a segmentation mask in parallel from a CameraFrame, with all OpenCV work off the UI thread.
detectFacesWithSegmentationFromMat(Mat image, {FaceDetectionMode mode = FaceDetectionMode.full, IsolateOutputFormat outputFormat = IsolateOutputFormat.float32, double binaryThreshold = 0.5}) → Future<DetectionWithSegmentationResult>: Detects faces and generates segmentation mask in parallel from a cv.Mat.
dispose() → Future<void>: Releases all resources held by the detector.
eyeRoisFromMesh(List<Point> meshAbs) → List<AlignedRoi>: Extracts aligned eye regions of interest from face mesh landmarks.
getFaceEmbedding(Face face, Uint8List imageBytes) → Future<Float32List>: Generates a face embedding (identity vector) for a detected face.
getFaceEmbeddingFromFilepath(Face face, String path) → Future<Float32List>: Generates a face embedding from an image file at path.
getFaceEmbeddingFromMat(Face face, Mat image) → Future<Float32List>: Generates a face embedding from a pre-decoded cv.Mat image.
getFaceEmbeddingFromMatBytes(Face face, Uint8List bytes, {required int width, required int height, int matType = 16}) → Future<Float32List>: Generates a face embedding from raw pixel bytes without constructing a cv.Mat.
getFaceEmbeddings(List<Face> faces, Uint8List imageBytes) → Future<List<Float32List?>>: Generates face embeddings for multiple detected faces.
getSegmentationMask(Uint8List imageBytes, {IsolateOutputFormat outputFormat = IsolateOutputFormat.float32, double binaryThreshold = 0.5}) → Future<SegmentationMask>: Segments an image to separate foreground (people) from background.
getSegmentationMaskFromCameraFrame(CameraFrame frame, {IsolateOutputFormat outputFormat = IsolateOutputFormat.float32, double binaryThreshold = 0.5, int? maxDim}) → Future<SegmentationMask>: Segments a CameraFrame to separate foreground from background, deferring YUV→BGR colour conversion and rotation to the segmentation isolate.
getSegmentationMaskFromMat(Mat image, {IsolateOutputFormat outputFormat = IsolateOutputFormat.float32, double binaryThreshold = 0.5}) → Future<SegmentationMask>: Segments a pre-decoded cv.Mat image to separate foreground from background.
getSegmentationMaskFromVideo(Object video) → Future<SegmentationMask>: Runs segmentation on a live <video> frame. Web-only.
initialize({FaceDetectionModel model = FaceDetectionModel.backCamera, PerformanceConfig performanceConfig = const PerformanceConfig(), int meshPoolSize = 3, bool withSegmentation = false, SegmentationConfig? segmentationConfig, bool useCompiledModel = false, Set<Accelerator> accelerators = const {Accelerator.gpu, Accelerator.cpu}, Precision precision = Precision.fp16, double minScore = 0.0, double minFaceSize = 0.0, bool useLiteRt = false, String liteRtAccelerator = 'auto'}) → Future<void>: Loads the face detection, face mesh, iris landmark, and embedding models and prepares the interpreters for inference in a background isolate.
initializeSegmentation({SegmentationConfig? config, Set<Accelerator>? accelerators, Precision? precision}) → Future<void>: Initializes the optional segmentation model.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
splitMeshesIfConcatenated(List<Point> meshPts) → List<List<Point>>: Splits a concatenated list of mesh points into individual face meshes.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

compareFaces(Float32List a, Float32List b) → double: Compares two face embeddings and returns a cosine similarity score.
create({FaceDetectionModel model = FaceDetectionModel.backCamera, PerformanceConfig performanceConfig = const PerformanceConfig(), int meshPoolSize = 3, bool withSegmentation = false, SegmentationConfig? segmentationConfig, bool useCompiledModel = false, Set<Accelerator> accelerators = const {Accelerator.gpu, Accelerator.cpu}, Precision precision = Precision.fp16, double minScore = 0.0, double minFaceSize = 0.0, bool useLiteRt = false, String liteRtAccelerator = 'auto'}) → Future<FaceDetector>: Creates and initializes a face detector in one step.
faceDistance(Float32List a, Float32List b) → double: Computes the Euclidean distance between two face embeddings.

Constants

modelVersion → const String: Cache-invalidation key for consumers that persist detection results.