Pipeline Reference

The UFME biometric pipeline is a sequence of pure, composable functions connected by async queues. Each stage declares the context keys it requires (reads) and produces (writes). The pipeline runner selects only the declared keys for each stage’s payload — stages never see the full context.

Optional stages (marked optional) are wired into the pipeline only when the corresponding ONNX model file is present at startup. Absent model = stage silently omitted.

Pipeline order

[super_resolution] → receive → detect → align → [head_pose] →
pad → mad → [deepfake] → quality → extract → [age] → [face_attributes] →
route → respond

DELETE operations are routed directly from receive to route, bypassing all image-processing stages.

Stage reference

1. Super-resolution `[optional]`

Model: realesrgan_x4plus.onnx

Upscales the raw probe image 4x before face detection. Intended for low-resolution surveillance captures where the face occupies fewer than ~80px. Uses tiled inference (512px tiles, 10px overlap blending) to bound peak memory.

	Keys
Requires	`image_bytes`
Produces	`image_bytes` (replaced with 4x upscaled JPEG)
Gate	None — failures are non-fatal; original bytes passed through

2. Receive

Parses the inbound HTTP payload into a plain dict. Validates against XXE and billion-laughs patterns (64 KB prolog limit). Enforces a 50 MB payload size limit.

	Keys
Requires	— (reads from HTTP envelope)
Produces	`operation`, `image_bytes`, `request_id`, `subject_id` (when present), `partition`, `metadata`
Gate	DELETE → `route_q`; all others → `detect_q` (or `sr_q` when SR stage present)

3. Detect

Locates the face and five landmark points using SCRFD_10G. Returns a bounding box and landmark coordinates.

	Keys
Requires	`image_bytes`
Produces	`detection` (bounding box, score, 5-point landmarks)
Gate	None (`queue_out = align_q`)
Failure	No face detected → `{"ok": False, "error": "no_face"}` → routed to `respond_q`

4. Align

Applies an affine transform using the 5-point landmarks to produce a 112×112 pixel normalised face crop. Drops image_bytes from the context after this stage — raw imagery is never present downstream (privacy by structure).

	Keys
Requires	`image_bytes`, `detection`
Produces	`crop` (112×112 RGB uint8)
Drops	`image_bytes`
Gate	None (`queue_out = head_pose_q` or `pad_q`)

5. Head pose `[optional]`

Model: head_pose_resnet18.onnx

Estimates head orientation from the aligned crop using a ResNet-18 rotation matrix model. Outputs pitch, yaw, and roll in degrees. The yaw gate rejects extreme-profile faces that are unprocessable by downstream biometric stages.

	Keys
Requires	`crop`
Produces	`head_pose` (`{pitch, yaw, roll}` in degrees)
Gate	`\|yaw\| > max_head_pose_yaw` (default 45°) → `respond_q`; otherwise → `pad_q`

6. PAD (Presentation Attack Detection)

Model: MiniFASNetV2.onnx

Assesses whether the face is a physical or digital presentation attack. Measurement only — the gate is a separate pure function. ISO 30107-3 compliant for Level 1 print/replay attacks.

	Keys
Requires	`crop`
Produces	`pad` (`{spoof_score: float, attack_type: str}`)
Gate	`spoof_score > pad_spoof_score` (default 0.85) → `respond_q`; otherwise → `mad_q`

7. MAD (Morphing Attack Detection)

Model: mad_selfmad_hrnet_w18.onnx (SelfMAD HRNet-W18)

Detects morphed document photos at enrolment. Measurement only — the gate is separate. Runs on the aligned crop (single-image, no reference required).

	Keys
Requires	`crop`
Produces	`morphing` (`{morph_score: float}`)
Gate	`morph_score > mad_morph_score` (default 0.75) → `respond_q`; otherwise → `deepfake_q` (or `quality_q`)

8. Deepfake detection `[optional]`

Model: deepfake_vit_q.onnx (ViT-base quantised)

Binary genuine/deepfake classifier. Produces a fake probability score. Measurement only — the gate is separate.

	Keys
Requires	`crop`
Produces	`deepfake` (`{fake_score: float}`)
Gate	`fake_score > deepfake_fake_score` (default 0.50) → `respond_q`; otherwise → `quality_q`

9. Quality

Model: ediffiqa_tiny.onnx (eDifFIQA Tiny)

Measures face image quality using a MobileFaceNet-based model. ISO/IEC 29794-5 aligned. Measurement only — the gate is separate.

	Keys
Requires	`crop`
Produces	`quality` (`{score: float}`)
Gate	`score < quality_min_score` (default 0.40) → `respond_q`; otherwise → `extract_q`

10. Extract

Model: w600k_r50.onnx (ArcFace ResNet-50, or w600k_mbf.onnx for mask-aware)

Produces a 512-dim L2-normalised face embedding. Drops crop from the context after this stage.

	Keys
Requires	`crop`
Produces	`embedding` (512-dim float32, L2-normalised), `model_id`
Drops	`crop`
Gate	None (`queue_out = age_q` or `route_q`)

11. Age estimation `[optional]`

Model: genderage.onnx (InsightFace genderage, age head)

Produces an age estimate in years from the aligned crop.

	Keys
Requires	`crop`
Produces	`age` (`{years: float}`)
Gate	None — non-fatal; failures pass through silently

12. Face attributes `[optional]`

Model: genderage.onnx (InsightFace genderage, gender head)

Produces a gender classification from the aligned crop.

	Keys
Requires	`crop`
Produces	`face_attributes` (`{gender: "male" \| "female", gender_confidence: float}`)
Gate	None — non-fatal; failures pass through silently

13. Route

Dispatches to the operation-specific orchestrator queue based on the operation key.

	Keys
Requires	`operation`
Produces	—
Gate	`SEARCH` → `search_q`; `VERIFY` → `verify_q`; `ENROL` → `enrol_q`; `DELETE` → `delete_q`

14. Respond

Formats the accumulated context into the outbound XML response. Serialises all present metadata fields (quality score, spoof score, age, head pose, attributes) into the response envelope.

	Keys
Requires	`result`, `request_id`, `operation`
Produces	— (writes to HTTP response)
Gate	None — terminal stage

Gate logic summary

Gate	Threshold key	Reject condition	HTTP status
Head pose	`thresholds.max_head_pose_yaw`	`\|yaw\| > threshold`	422
PAD	`thresholds.pad_spoof_score`	`spoof_score > threshold`	451
MAD	`thresholds.mad_morph_score`	`morph_score > threshold`	422
Deepfake	`thresholds.deepfake_fake_score`	`fake_score > threshold`	422
Quality	`thresholds.quality_min_score`	`score < threshold`	422

All thresholds are configurable in config.toml or via environment variables. See Configuration Reference.

Context key lifecycle

Key	Introduced by	Dropped by	Present in response
`image_bytes`	receive	align	no
`detection`	detect	—	no
`crop`	align	extract	no
`head_pose`	head_pose stage	—	yes (optional)
`pad`	pad stage	—	yes
`morphing`	mad stage	—	yes
`deepfake`	deepfake stage	—	yes (optional)
`quality`	quality stage	—	yes
`embedding`	extract	—	no
`age`	age stage	—	yes (optional)
`face_attributes`	face_attributes stage	—	yes (optional)
`result`	orchestrator	—	yes