How bsi-ofiq/ofiq-project works
1. Core purpose and top-level shape
OFIQ is a C/C++ face image quality library and the reference implementation of ISO/IEC 29794-5. The repository is centered around a native quality-evaluation engine, with thin mobile bindings and sample apps on top. The main runtime artifact is the OFIQlib C++ library.
2. Native library boundary
The public C/C++ API lives under OFIQlib/include (ofiq_lib.h, ofiq_structs.h, ofiq_lib_impl.h). Internal orchestration is implemented in OFIQlib/src (OFIQImpl.cpp, OFIQInitialization.cpp). This is the boundary consumers use to initialize the engine, submit images, and receive structured quality results.
3. Execution pipeline inside the engine
The engine follows a face-analysis pipeline: image input is first normalized through utility code, then face detection runs, followed by landmark extraction, segmentation/pose estimation where needed, and finally metric computation. The output is a bundle of standardized assessments and aggregate scores rather than a single classifier result.
4. Face detection subsystem
OFIQlib/modules/detectors isolates face localization. It includes a detector abstraction plus an OpenCV SSD-based face detector implementation. This is the first major dependency boundary because downstream modules assume a detected face region before quality checks can run.
5. Landmark subsystem
OFIQlib/modules/landmarks computes facial landmarks and derived facial measurements. It includes parts extraction and face-measure helpers, plus an ADNet-based landmark implementation. These landmarks feed multiple quality measures that depend on geometry, eye/mouth state, and face-part positions.
6. Segmentation subsystem
OFIQlib/modules/segmentations performs semantic face parsing and occlusion-related segmentation. The presence of ONNXRTSegmentation indicates ONNX Runtime-backed inference is used for at least some models. These results support occlusion-prevention and head-covering metrics by identifying which facial regions are visible or obstructed.
7. Pose estimation subsystem
OFIQlib/modules/poseEstimators computes head pose, with a dedicated 3D DFA V2-based implementation. Pose is a shared dependency for several quality measures, especially those concerning frontal alignment, crop suitability, and overall capture compliance.
8. Quality measures as the main domain model
OFIQlib/modules/measures is the largest subsystem and contains one class per quality attribute, such as sharpness, exposure, illumination uniformity, eye openness/visibility, mouth closure, natural colour, background uniformity, compression artifacts, head size, inter-eye distance, single-face presence, and unified quality score. MeasureFactory and Executor indicate a pluggable, orchestrated evaluation model rather than a monolithic routine.
9. Measure dependencies and shared inputs
Most measures consume a mix of raw image data and intermediate analysis products. Geometry-based measures use landmarks and pose; occlusion and coverage measures use segmentation; image-quality measures use pixel statistics and image utilities; higher-level measures combine multiple lower-level assessments. The architecture is dataflow-driven, with shared analysis artifacts reused across measures to avoid recomputation.
10. Utility and runtime support layer
OFIQlib/modules/utils provides configuration management, session handling, error representation, image I/O, and image processing helpers. DataStreamDesktop, DataStreamAndroid, and DataStreamIOS show platform-specific image/data access boundaries, while Configuration and Session manage runtime settings and per-invocation state. This layer is the glue between platform-specific inputs and the native evaluation pipeline.
11. Mobile integration architecture
The mobile tree contains two independent app front ends: Android and iOS. Both apps present capture/image-selection UI, invoke the native OFIQ library through platform bindings, and render the resulting metric table and score view. The mobile apps are not just demos; they are separate integration layers demonstrating how the core library is embedded on each platform.
12. Android native bridge
Under mobile/lib-projects/android/ofiqlib, Kotlin classes such as OfiqLib, QualityMetrics, QualityMeasureAssessment, and InitializeResult wrap a JNI bridge implemented in src/main/cpp/ofiqlib.cpp. The Android demo app in mobile/apps/android/OFIQMobile calls this wrapper from ViewModel/UI layers and uses a camera/image workflow to feed the native engine.
13. iOS native bridge
Under mobile/lib-projects/iOS/ofiqlib, Objective-C++ wrappers expose the C++ library to Swift. The iOS app in mobile/apps/iOS/OFIQMobile uses Swift views and view models for camera/image input and result presentation, while the wrapper layer handles the native call boundary and data marshaling.
14. Verification, conformance, and assets
testing/test_conformance_table.cpp and the scripts/conformance_tests.* files support standardized conformance verification. The doc/testsets CSVs and data/tests image/expected-result sets provide ground truth for metric validation. Model assets live under data/models, and data/ofiq_config.jaxn provides runtime configuration for the library.
15. Build and delivery boundaries
The project is built with CMake at the core, with platform-specific CMake fragments for Windows, Ubuntu, Ubuntu ARM64, and macOS. Conan profiles and dependency download scripts indicate that third-party native dependencies are managed externally. CI workflows under .github/workflows build on Linux, macOS, and Windows, reinforcing that the core library is intended to be portable native code first, with mobile packaging as a second distribution path.
16. Diagramming takeaway
If you draw the architecture, the most accurate shape is: platform-specific inputs and wrappers on the outside, a single native OFIQ engine in the middle, and a set of analysis modules underneath that engine. Data enters as images, flows through detection/landmarks/segmentation/pose, then fans out into independent quality measures, and finally converges into standardized per-metric assessments plus an aggregate quality score.
Main entry points: OFIQImpl.cpp Engine core · measures Quality measures · ofiq_lib.h Public API · CMakeLists.txt Build system
Components 18
Native engine
Core C/C++ OFIQ quality library and analysis modules
- Public API · External entry point for initialization, input submission, and structured results
OFIQlib/include/ofiq_lib.h - Engine core · Orchestrates initialization and quality evaluation inside the native library
OFIQlib/src/OFIQImpl.cpp - Runtime utils · Configuration, session state, image I/O, error handling, and platform data streams
OFIQlib/modules/utils - Face detector · Detects face regions before downstream quality analysis
OFIQlib/modules/detectors - Landmarks · Extracts facial landmarks and derived facial measurements
OFIQlib/modules/landmarks - Segmentation · Performs face parsing and occlusion-aware region analysis
OFIQlib/modules/segmentations - Head pose · Computes head pose for alignment and capture-quality checks
OFIQlib/modules/poseEstimators - Quality measures · Pluggable per-attribute checks and aggregate scoring
OFIQlib/modules/measures - Measure factory · Creates the configured set of measures to execute
OFIQlib/modules/measures/MeasureFactory.h - Measure executor · Runs measures over shared analysis artifacts and collects assessments
OFIQlib/modules/measures/Executor.h
Mobile integration
Android and iOS front ends plus native bindings
- Android app · Camera and image workflow that presents OFIQ results on Android
mobile/apps/android/OFIQMobile - Android bridge · Kotlin facade plus native C++ bridge for the Android app
mobile/lib-projects/android/ofiqlib - iOS app · Camera and image workflow that presents OFIQ results on iOS
mobile/apps/iOS/OFIQMobile - iOS bridge · Swift-facing wrapper layer around the native C++ library
mobile/lib-projects/iOS/ofiqlib
Verification and build
Conformance assets, tests, and build/CI boundaries
- Conformance tests · Standardized metric validation against reference results
testing/test_conformance_table.cpp - Test assets · Images, expected results, and metric-specific CSV ground truth
doc/testsets - Models and config · Bundled runtime configuration and model files for inference
data/models - Build system · Core build scripts, platform fragments, and CI workflows
CMakeLists.txt
Connections 23
- Public API → Engine core: calls · Public API delegates into the internal engine boundary
- Engine core → Runtime utils: uses · Engine state, input loading, and errors flow through utilities
- Engine core → Face detector: detects · Face localization is the first analysis stage
- Engine core → Landmarks: extracts · Landmarks and facial measurements feed geometry-based metrics
- Engine core → Segmentation: parses · Segmentation supports occlusion and coverage checks
- Engine core → Head pose: estimates · Pose is used for alignment and compliance metrics
- Engine core → Measure factory: configures · Engine selects which measures to instantiate
- Measure factory → Measure executor: builds · Factory supplies the runnable measure set
- Measure executor → Quality measures: runs · Executor coordinates individual quality attributes
- Face detector → Quality measures: feeds · Detected face regions are shared by downstream measures
- Landmarks → Quality measures: feeds · Geometry outputs support landmark-dependent metrics
- Segmentation → Quality measures: feeds · Parsing and occlusion masks support visibility metrics
- Head pose → Quality measures: feeds · Pose estimates support frontalness and crop checks
- Android app → Android bridge: invokes · Android UI calls into the native wrapper layer
- Android bridge → Public API: binds · JNI wrapper forwards to the native library API
- iOS app → iOS bridge: invokes · iOS UI calls into the wrapper layer
- iOS bridge → Public API: binds · Objective-C++ wrapper forwards to the native library API
- Conformance tests → Quality measures: validates · Reference outputs validate individual metric behavior
- Test assets → Conformance tests: supplies · Ground-truth assets back the conformance checks
- Models and config → Engine core: loads · Runtime assets and configuration are consumed by the engine
- Build system → Public API: builds · CMake and CI boundaries assemble the native library and apps
- Build system → Android app: builds · Mobile build path includes the Android app
- Build system → iOS app: builds · Mobile build path includes the iOS app