# usnistgov/nfiq2 architecture

> Architecture diagram of the GitHub repository usnistgov/nfiq2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/usnistgov/nfiq2
- Repository: https://github.com/usnistgov/nfiq2

## Overview

##### Main Components
- NFIQ 2 Core Library: This is primarily found inside the NFIQ2 directory (notably under “NFIQ2Algorithm” and “NFIQ2Api”) where the algorithm implementation, supporting utility functions, and API exposure reside.
- Command-Line Interface (CLI): Although built along with the library, the CLI component is conditionally compiled (enabled/disabled via the BUILD_NFIQ2_CLI flag in CMake). It integrates with the core library to provide standalone usage.
- Conformance Testing: The “conformance” directory contains expected outputs and test scripts (like diff.py) to validate functionality across builds, emphasizing an automated verification layer.
- Examples: The “examples” directory gives sample usage (e.g., example_api.cpp and images), showcasing how the API can be integrated into client applications.
- Build & Configuration Infrastructure: The CMakeLists.txt files, the “cmake” directory with its custom toolchain and build scripts, and GitHub workflows indicate a strong emphasis on portability and reproducible builds.
- External Dependencies/Submodules: These include key libraries such as digestpp, FingerJetFX OSE, OpenCV, libbiomeval, and even the NIST Fingerprint Image Resampler. These are integrated as git submodules.
- Documentation: Within the NFIQ2Algorithm/doc folder (and related man pages and configuration files) you have comprehensive documentation that explains configuration, usage, and expected command-line parameters.

##### Relationships and Interactions
- The Core Library (NFIQ2Algorithm and NFIQ2Api) forms the heart of processing—receiving fingerprint image input, calling into various quality modules (like FDA, FingerJetFX, and others) for image processing and quality scoring.
- The CLI and Example applications act as consumers of the Core Library, demonstrating its capabilities and providing user interfaces.
- Build scripts (CMake) and GitHub workflows are responsible for compiling and testing across multiple platforms, ensuring that the entire ecosystem remains robust.
- The automated conformace test suite validates that the outputs from the algorithms remain consistent with standardized expected values.
- External libraries (OpenCV, etc.) are utilized by the core processing algorithms, linking the project’s internal components with established third-party imaging and evaluation functionalities.

##### Architectural Patterns and Design Principles
- Modular Design: The clear separation between algorithm implementation, API interfaces, and quality modules suggests a modular, easily maintainable architecture.
- API Abstraction: The NFIQ2Api is clearly separated from internal algorithm implementations, improving decoupling and future extensibility.
- Configuration-Driven Build: Extensive use of CMake and script-driven workflows ensures the build process is consistent and adaptable, highlighting continuous integration and cross-platform portability.
- Test-Driven Conformance: A dedicated conformance directory underscores the importance of reproducible, benchmarked results aligning to international standards.

##### Relevant Technologies and Frameworks
- C++ as the main implementation language.
- CMake for build and configuration management.
- GitHub Actions as part of the CI/CD pipelines.
- Standard image processing libraries such as OpenCV.
- Additional third-party libraries (digestpp, FingerJetFX OSE, libbiomeval) to support diverse functions including cryptographic hashing and specialized fingerprint processing.

##### Elements
- Clear Labels: Each component should be clearly labeled (e.g., “NFIQ2 Core Library”, “Quality Modules”, “CLI”, “Conformance Tests”, “External Libraries”).
- From input fingerprint images to the core processing modules.
- From the core system to output via the CLI or API calls.
- Dependencies such as how the Core Library calls external libraries.
- Internal code modules (libraries, APIs).
- Interface layers (CLI, examples).
- Infrastructure/automation (build scripts, testing).
- Third-party dependencies.
- Annotations: Brief notes for build configurations (e.g., CMake’s role, flags such as BUILD_NFIQ2_CLI) can reinforce the purpose of each segment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input
    N["Fingerprint Image"]:::input

    %% Core Library Subgraph
    subgraph "Core Library"
        A["Algorithm Implementation"]:::core
        B["API Exposure"]:::core
    end

    %% Interfaces Subgraph
    subgraph "Interfaces"
        C["Command-Line Interface (CLI)"]:::interface
        D["Example Applications"]:::interface
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        E["digestpp"]:::external
        F["FingerJetFX OSE"]:::external
        G["libbiomeval"]:::external
        H["OpenCV"]:::external
    end

    %% Infrastructure Subgraph
    subgraph "Infrastructure"
        I["Build: CMakeLists.txt"]:::infra
        J["Build Scripts: cmake"]:::infra
        K["CI/CD: .github/workflows"]:::infra
        L["Conformance Testing"]:::infra
    end

    %% Documentation
    M["Documentation"]:::doc

    %% Relationships and Data Flow
    N -->|"processed"| A
    C -->|"calls"| A
    C -->|"calls"| B
    D -->|"calls"| B
    A -->|"integrates"| E
    A -->|"integrates"| F
    A -->|"integrates"| G
    A -->|"integrates"| H
    I -->|"builds"| A
    I -->|"builds"| B
    J -->|"builds"| A
    J -->|"builds"| B
    K -->|"triggers"| L
    L -->|"validates"| A
    L -->|"validates"| B
    B -->|"docs"| M

    %% Click Events
    click A "https://github.com/usnistgov/nfiq2/tree/master/NFIQ2/NFIQ2Algorithm"
    click B "https://github.com/usnistgov/nfiq2/tree/master/NFIQ2/NFIQ2Api"
    click L "https://github.com/usnistgov/nfiq2/tree/master/conformance"
    click D "https://github.com/usnistgov/nfiq2/tree/master/examples"
    click I "https://github.com/usnistgov/nfiq2/blob/master/CMakeLists.txt"
    click J "https://github.com/usnistgov/nfiq2/tree/master/cmake"
    click K "https://github.com/usnistgov/nfiq2/tree/master/.github/workflows"
    click M "https://github.com/usnistgov/nfiq2/tree/master/NFIQ2/NFIQ2Algorithm/doc"
    click E "https://github.com/usnistgov/nfiq2/tree/master/digestpp"
    click F "https://github.com/usnistgov/nfiq2/tree/master/fingerjetfxose"
    click G "https://github.com/usnistgov/nfiq2/tree/master/libbiomeval"
    click H "https://github.com/usnistgov/nfiq2/tree/master/opencv"

    %% Class Definitions for Colors and Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef interface fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef infra fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef doc fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef input fill:#FFFACD,stroke:#000,stroke-width:2px;
```
