Crate face_verification_core 

Core types for an on-device face liveness and verification engine.

This crate is intentionally UI-agnostic and Flutter-agnostic. It is meant to be embedded from Flutter (via FFI / WASM), Tauri, native Rust apps, Cloud Run servers, or any host that can call Rust.

Module map

• challenge — six-step liveness challenge generation (face centered, smile, head turns, fingers, touch face).
• pose — per-frame validation: yaw/pitch, framing, smile score, finger count, hand-to-face distance.
• session — temporal state machine: accumulates valid frames until a stable capture is ready.
• verify — final verification across the six captured photos: same person, distinct poses, no duplicates, and NSFW gate.
• engine — ONNX inference pipeline wired to the [tract] runtime when the runtime-tract Cargo feature is enabled.
• json_bridge — &str-in / String-out wrappers around every public entry point, suitable for FFI bridges that cannot pass Rust types.
• types — shared value types (ImageInput, FrameAnalysis, VerificationThresholds, …).

Cargo features

• runtime-tract (default off) — enables the in-process ONNX runtime built on tract-onnx plus the image crate for JPEG/PNG decoding.
• server — enables the generic face_verification_server binary (axum + tokio HTTP wrappers around this crate). Implies runtime-tract.

Without any feature the crate exposes only the deterministic logic (challenge, pose, session, verify, json bridge) and trusts the host to fill FrameAnalysis from another vision pipeline.

Structs

BoundingBox

CapturedPhotoAnalysis

One of the six photos captured at the end of a liveness challenge.

FaceAnalysis

Vision result for a single face inside one frame.

FaceVerificationEngine

Headless verification engine.

FrameAnalysis

HandAnalysis

ImageInput

Encoded image bytes plus the dimensions the host already knows.

Landmarks

LivenessChallenge

A complete liveness challenge.

ModelAsset

One model file plus the metadata needed to wire it into a pipeline.

ModelBundle

A complete, swappable model set.

ModelValidation

Summary returned by ModelBundle::validate.

NsfwScores

Raw NSFW classifier probabilities (range 0..=1).

Point

PoseCheck

Result of validating one frame or one captured photo against a step.

SessionTickJsonResult

VerificationAnchorSample

VerificationAnchors

VerificationChecks

Per-check booleans returned alongside VerificationResult.

VerificationResult

VerificationSession

In-memory state for a single liveness-capture flow.

VerificationThresholds

Runtime knobs used by the liveness pipeline.

Enums

ChallengeStep

One step in a liveness challenge.

FaceVerificationError

Public error type for the core.

ModelFormat

Serialized model format accepted by the Rust runtime.

ModelRole

Role a model plays in the full image-analysis pipeline.

SessionDecision

What the session wants the host to do next.

TouchTarget

Facial target used by hand-to-face liveness checks.

Constants

EXPECTED_PHOTO_COUNT

Number of photos captured during a full liveness challenge — one per step.

FRAMES_OK_TO_CAPTURE

Consecutive valid frames required before a capture is auto-triggered.

TICK_MS

Recommended cadence for calling VerificationSession::tick from the host.

Traits

Analyzer

Strategy trait for anything that can turn raw image bytes into a FrameAnalysis. Implemented by crate::FaceVerificationEngine when the runtime-tract feature is active; hosts can also implement it on their own pipeline (e.g. a platform-native CoreML / NNAPI backend).

Functions

analyze_captured_image_json

analyze_image_json

analyze_liveness_image_json

build_bundle_with_bytes

Build a ModelBundle by merging JSON metadata with the raw model bytes.

compute_yaw

Approximate yaw angle from 68-point face landmarks.

face_distance

Euclidean (L2) distance between two embeddings.

generate_challenge_json

new_session_json

tick_session_json

validate_model_bundle_json

validate_model_bundle_with_bytes

Split-bytes variant of validate_model_bundle_json.

validate_pose

Decide whether the current frame satisfies step.

validate_pose_json

verify_captured_photos

Apply the full verification pipeline (see module-level docs) to the six captured photos and return the user-facing decision. Pure function: it never touches the network or the model bundle.

verify_captured_photos_json

verify_images_json

Type Aliases

Embedding

L2-normalised face embedding produced by the recognition model.