InspireFace SDK

The InspireFace Android Example is a reference implementation using CameraX and the InspireFace SDK (v1.2.0). It serves as a feature menu for testing various face-related capabilities. The app uses a global model selector (e.g., Pikachu or Megatron) which determines the loaded model and isolates all face features, crops, and identity data into separate storage paths.

Key features included in the example:

• Liveness Detection: Supports both Silent (RGB anti-spoofing) and Action (cooperative challenges like blinking or head shaking) modes.
• Face Recognition & Management: 1:1 comparison, 1:N search, and CRUD operations for identities.
• Face Tracking & Attributes: 106-point dense landmark detection and analysis of age, gender, expression, and mask state.
• Pose Recognition: Real-time detection of head poses with history tracking.

InspireFace is a cross-platform face recognition SDK written in C/C++. It provides a comprehensive suite of facial analysis capabilities including:

• Face Detection & Tracking: High-precision detection and real-time tracking.
• Face Recognition: Feature extraction and comparison.
• Landmark Detection: Accurate localization of facial landmarks.
• Face Attributes: Recognition of age, gender, and emotion.
• Liveness Detection: Both silent and cooperative liveness detection.
• Mask Detection: Capability to detect if a face is wearing a mask.
• Quality Assessment: Evaluation of face image quality.
• Pose Estimation: Estimation of face pose angles.

To successfully implement Action Liveness (cooperative challenges), three specific conditions must be met in the session configuration:

1. Detection Mode: Must use DETECT_MODE_LIGHT_TRACK. Other modes rebuild tracked faces every frame, preventing the temporal window required for actions from accumulating.
2. Interaction Enablement: enableInteractionLiveness must be set to true during session creation.
3. Quality Enablement: enableFaceQuality must be set to true during session creation. This loads the pose model; without it, yaw/pitch values remain 0, and actions like 'shake' or 'head raise' will not trigger.

InspireFace provides two optional tracking modes depending on your performance and accuracy requirements:

1. Tracking by Landmark: A high-speed mode with average accuracy. It is optimized for portrait mode (e.g., mobile phone front camera) and is best suited for tracking a small number of faces (1-5 faces).
2. Tracking by Detection: A high-accuracy mode with lower speed. It currently implements the bytetrack algorithm (based on the DeepSORT implementation).

A critical design pattern in this example is pre-rotating the NV21 buffer on the Java side before passing it to the SDK.

Why this is necessary:

• The SDK (up to v1.2.3) crops RGB-liveness input using the formula: rotated upright full frame + un-rotated face rect.
• Passing standard Android rotation constants (90/270) to the SDK misplaces the crop and corrupts silent-liveness scores.
• Solution: Pre-rotate the buffer to an upright orientation and always pass CAMERA_ROTATION_0 to the SDK. This ensures all SDK output coordinates land directly in display orientation, requiring only a simple front-camera mirror for overlays.

The application implements model-isolated storage to ensure that data from different models (e.g., Pikachu vs Megatron) never overlap. When switching models, the app switches to a different native database, crop directory, and metadata set.

Storage structure per model:

files/face_hub/[MODEL_NAME]/features.db
files/face_hub/[MODEL_NAME]/crops/
shared_prefs/face_records_[MODEL_NAME].xml

InspireFace supports a wide range of platforms and hardware backends:

• Linux (CPU): ARMv7, ARMv8, x86/x86_64.
• Linux (Rockchip NPU): ARMv7 (RV1109/RV1126, RV1103/RV1106) and ARMv8 (RK3566/RK3568, RK3588).
• Linux (GPU): x86_64 with NVIDIA-GPU (via CUDA or MNN_CUDA).
• MacOS: Intel and Apple Silicon (supporting CPU, Metal, and ANE).
• iOS: ARM (supporting CPU, Metal, and ANE).
• Android: ARMv7, ARMv8, and x86_64. Also supports Rockchip NPU (RK3566/RK3568, RK3588).

If you are using a self-compiled dynamic library, follow these steps:

1. Install dependencies: loguru, tqdm, and opencv-python.
2. Copy your compiled dynamic library (libInspireFace.so) to the appropriate system architecture directory within the inspireface/modules/core/ path.
3. Run the setup script to install the package.

# 1. Install dependencies
pip install loguru tqdm opencv-python

# 2. Copy the compiled dynamic library to the corresponding system architecture directory
cp YOUR_BUILD_DIR/libInspireFace.so inspireface/modules/core/SYSTEM/CORE_ARCH/

# 3. Install the Python package
python setup.py install

To build and run the InspireFace Android Example, ensure your environment meets the following requirements:

• JDK: Version 17 (required by AGP 8.6.1).
• IDE: Android Studio Ladybug or newer (uses Gradle 8.7 wrapper).
• Network: Access to google(), mavenCentral(), and jitpack.io (the SDK and model packs are hosted on JitPack).
• Hardware: An ARM-based Android device running Android 7.0 (API 24) or newer.
• Architecture Support: The SDK supports arm64-v8a and armeabi-v7a. Note: x86/x86_64 emulators and Intel-only ChromeOS devices are not supported because they cannot run the native face engine.
• Android 15 Compatibility: The native libraries are aligned for Android 15's 16 KB page-size devices.

To build and install the Android example app on a connected device or emulator, use the Gradle wrapper from the project root.

Note: The first time you launch the app, the feature launch will be slower because the bundled model packs are being unpacked from the application assets.

./gradlew :app:installDebug

The recommended way to install the InspireFace Python API is using pip.

pip install inspireface

After the build and reorganize_structure step, the output is organized into a clean hierarchy based on architecture. Instead of having architecture folders containing all files, the files are grouped by their purpose (lib, sample, test) and then sub-divided by architecture.

Target Structure:

<BUILD_FOLDER_PATH>/
├── lib/
│   ├── arm64-v8a/
│   └── armeabi-v7a/
├── sample/
│   ├── arm64-v8a/
│   └── armeabi-v7a/
├── test/
│   ├── arm64-v8a/
│   └── armeabi-v7a/
└── version.txt