# bsi-ofiq/ofiq-project architecture

> Architecture diagram of the GitHub repository bsi-ofiq/ofiq-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bsi-ofiq/ofiq-project
- Repository: https://github.com/bsi-ofiq/ofiq-project

## Overview

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: [`OFIQlib/src/OFIQImpl.cpp`](https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/src/OFIQImpl.cpp) (Engine core), [`OFIQlib/modules/measures`](https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/measures) (Quality measures), [`OFIQlib/include/ofiq_lib.h`](https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/include/ofiq_lib.h) (Public API), [`CMakeLists.txt`](https://github.com/bsi-ofiq/ofiq-project/blob/main/CMakeLists.txt) (Build system)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["Native engine"]
  node_api["Public API<br/>C/C++ headers<br/>[ofiq_lib.h]"]
  node_core["Engine core<br/>C++ runtime<br/>[OFIQImpl.cpp]"]
  node_utils["Runtime utils<br/>support layer"]
  node_detectors["Face detector<br/>localization module"]
  node_landmarks["Landmarks<br/>geometry module"]
  node_segmentations["Segmentation<br/>parsing module"]
  node_pose["Head pose<br/>pose module"]
  node_measures["Quality measures<br/>metric suite"]
  node_measure_factory["Measure factory<br/>measure registry<br/>[MeasureFactory.h]"]
  node_measure_executor["Measure executor<br/>orchestrator<br/>[Executor.h]"]
end

subgraph group_mobile["Mobile integration"]
  node_android_app["Android app<br/>Kotlin UI"]
  node_android_bridge["Android bridge<br/>JNI wrapper"]
  node_ios_app["iOS app<br/>Swift UI"]
  node_ios_bridge["iOS bridge<br/>ObjC++ wrapper"]
end

subgraph group_verification["Verification and build"]
  node_conformance["Conformance tests<br/>verification suite"]
  node_testsets["Test assets<br/>ground truth"]
  node_models[("Models and config<br/>assets")]
  node_build["Build system<br/>CMake/CI<br/>[CMakeLists.txt]"]
end

node_api -->|"calls"| node_core
node_core -->|"uses"| node_utils
node_core -->|"detects"| node_detectors
node_core -->|"extracts"| node_landmarks
node_core -->|"parses"| node_segmentations
node_core -->|"estimates"| node_pose
node_core -->|"configures"| node_measure_factory
node_measure_factory -->|"builds"| node_measure_executor
node_measure_executor -->|"runs"| node_measures
node_detectors -.->|"feeds"| node_measures
node_landmarks -.->|"feeds"| node_measures
node_segmentations -.->|"feeds"| node_measures
node_pose -.->|"feeds"| node_measures
node_android_app -->|"invokes"| node_android_bridge
node_android_bridge -->|"binds"| node_api
node_ios_app -->|"invokes"| node_ios_bridge
node_ios_bridge -->|"binds"| node_api
node_conformance -->|"validates"| node_measures
node_testsets -.->|"supplies"| node_conformance
node_models -.->|"loads"| node_core
node_build -.->|"builds"| node_api
node_build -.->|"builds"| node_android_app
node_build -.->|"builds"| node_ios_app

click node_api "https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/include/ofiq_lib.h"
click node_core "https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/src/OFIQImpl.cpp"
click node_utils "https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/utils"
click node_detectors "https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/detectors"
click node_landmarks "https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/landmarks"
click node_segmentations "https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/segmentations"
click node_pose "https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/poseEstimators"
click node_measures "https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/measures"
click node_measure_factory "https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/modules/measures/MeasureFactory.h"
click node_measure_executor "https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/modules/measures/Executor.h"
click node_android_app "https://github.com/bsi-ofiq/ofiq-project/tree/main/mobile/apps/android/OFIQMobile"
click node_android_bridge "https://github.com/bsi-ofiq/ofiq-project/tree/main/mobile/lib-projects/android/ofiqlib"
click node_ios_app "https://github.com/bsi-ofiq/ofiq-project/tree/main/mobile/apps/iOS/OFIQMobile"
click node_ios_bridge "https://github.com/bsi-ofiq/ofiq-project/tree/main/mobile/lib-projects/iOS/ofiqlib"
click node_conformance "https://github.com/bsi-ofiq/ofiq-project/blob/main/testing/test_conformance_table.cpp"
click node_testsets "https://github.com/bsi-ofiq/ofiq-project/tree/main/doc/testsets"
click node_models "https://github.com/bsi-ofiq/ofiq-project/tree/main/data/models"
click node_build "https://github.com/bsi-ofiq/ofiq-project/blob/main/CMakeLists.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_core,node_utils,node_detectors,node_landmarks,node_segmentations,node_pose,node_measures,node_measure_factory,node_measure_executor toneBlue
class node_android_app,node_android_bridge,node_ios_app,node_ios_bridge toneAmber
class node_conformance,node_testsets,node_models,node_build toneMint
```

## Components

### Native engine

Core C/C++ OFIQ quality library and analysis modules

- [Public API](https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/include/ofiq_lib.h): C/C++ headers · External entry point for initialization, input submission, and structured results · `OFIQlib/include/ofiq_lib.h`
- [Engine core](https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/src/OFIQImpl.cpp): C++ runtime · Orchestrates initialization and quality evaluation inside the native library · `OFIQlib/src/OFIQImpl.cpp`
- [Runtime utils](https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/utils): support layer · Configuration, session state, image I/O, error handling, and platform data streams · `OFIQlib/modules/utils`
- [Face detector](https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/detectors): localization module · Detects face regions before downstream quality analysis · `OFIQlib/modules/detectors`
- [Landmarks](https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/landmarks): geometry module · Extracts facial landmarks and derived facial measurements · `OFIQlib/modules/landmarks`
- [Segmentation](https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/segmentations): parsing module · Performs face parsing and occlusion-aware region analysis · `OFIQlib/modules/segmentations`
- [Head pose](https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/poseEstimators): pose module · Computes head pose for alignment and capture-quality checks · `OFIQlib/modules/poseEstimators`
- [Quality measures](https://github.com/bsi-ofiq/ofiq-project/tree/main/OFIQlib/modules/measures): metric suite · Pluggable per-attribute checks and aggregate scoring · `OFIQlib/modules/measures`
- [Measure factory](https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/modules/measures/MeasureFactory.h): measure registry · Creates the configured set of measures to execute · `OFIQlib/modules/measures/MeasureFactory.h`
- [Measure executor](https://github.com/bsi-ofiq/ofiq-project/blob/main/OFIQlib/modules/measures/Executor.h): orchestrator · 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](https://github.com/bsi-ofiq/ofiq-project/tree/main/mobile/apps/android/OFIQMobile): Kotlin UI · Camera and image workflow that presents OFIQ results on Android · `mobile/apps/android/OFIQMobile`
- [Android bridge](https://github.com/bsi-ofiq/ofiq-project/tree/main/mobile/lib-projects/android/ofiqlib): JNI wrapper · Kotlin facade plus native C++ bridge for the Android app · `mobile/lib-projects/android/ofiqlib`
- [iOS app](https://github.com/bsi-ofiq/ofiq-project/tree/main/mobile/apps/iOS/OFIQMobile): Swift UI · Camera and image workflow that presents OFIQ results on iOS · `mobile/apps/iOS/OFIQMobile`
- [iOS bridge](https://github.com/bsi-ofiq/ofiq-project/tree/main/mobile/lib-projects/iOS/ofiqlib): ObjC++ wrapper · 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](https://github.com/bsi-ofiq/ofiq-project/blob/main/testing/test_conformance_table.cpp): verification suite · Standardized metric validation against reference results · `testing/test_conformance_table.cpp`
- [Test assets](https://github.com/bsi-ofiq/ofiq-project/tree/main/doc/testsets): ground truth · Images, expected results, and metric-specific CSV ground truth · `doc/testsets`
- [Models and config](https://github.com/bsi-ofiq/ofiq-project/tree/main/data/models): assets · Bundled runtime configuration and model files for inference · `data/models`
- [Build system](https://github.com/bsi-ofiq/ofiq-project/blob/main/CMakeLists.txt): CMake/CI · Core build scripts, platform fragments, and CI workflows · `CMakeLists.txt`

## Connections

- 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
