Model packs

An InspireFace deployment needs three matching pieces: a native SDK, a resource pack and any runtime libraries required by its backend. Choose these together before tuning detection parameters.

Pick a resource pack

The model release page and the repository's command/download_models_general.sh provide the pack files. From the repository root:

bash command/download_models_general.sh Pikachu

This writes test_res/pack/Pikachu, which is enough for the first CPU example. To download every listed pack, run the script without an argument.

On Windows, use the same CPU packs. Python can download its default pack with isf.launch(). For offline use, download Pikachu from the model release and pass its local path; see Windows setup.

For iOS and macOS CPU frameworks, start with Pikachu as well. A CoreML build needs a compatible CoreML pack; changing the build flag or renaming a general pack does not convert its models. The general download script above does not provide a CoreML pack.

A pack is a file, sometimes without an extension. If you downloaded a ZIP archive, extract it first. Pass the pack file to HFLaunchInspireFace or launch(resource_path=...).

Validate before creating sessions

The 1.2.4 API includes pack validation and metadata inspection. The Python example works with the 1.2.4.post3 PyPI package:

import inspireface as isf

info = isf.validate_resource_pack("/path/to/Pikachu")
print(info)
isf.launch(resource_path="/path/to/Pikachu")

In C, use HFValidateResourcePack with HFResourcePackInfo as declared in the matching header. This checks the resource format. Install backend runtime dependencies using the target platform's guide below.

Java, Android and the Apple interfaces accept a local filesystem path to the pack. Validate it before launching the runtime. At shutdown, release all sessions before terminating the runtime.

import com.insightface.sdk.inspireface.jni.NativeTypes.HFResourcePackInfo;
import static com.insightface.sdk.inspireface.jni.Native.*;
import static com.insightface.sdk.inspireface.jni.InspireFaceException.check;

public final class PackRuntime {
    public static void launch(String path) {
        HFResourcePackInfo info = new HFResourcePackInfo();
        check(HFValidateResourcePack(path, info));
        check(HFLaunchInspireFace(path));
    }
}

import com.insightface.sdk.inspireface.InspireFace;

public final class AndroidPackRuntime {
    // Call on a worker before creating sessions; path names a local pack file.
    public static void launch(String path) {
        InspireFace.ValidateResourcePack(path);
        if (!InspireFace.GlobalLaunch(path)) {
            throw new IllegalStateException("Cannot load model pack");
        }
    }
}

#import <InspireFace/InspireFaceApple.h>

BOOL LaunchValidatedPack(NSString *path, NSError **error) {
    HFResourcePackInfo info = {0};
    if (![IFRuntime validateResourcePackAtPath:path info:&info error:error]) {
        return NO;
    }
    return [IFRuntime launchAtPath:path error:error];
}

import InspireFaceSwift

func launchValidatedPack(path: String) throws {
    var info = HFResourcePackInfo()
    try InspireFaceRuntime.validateResourcePack(path: path, info: &info)
    try InspireFaceRuntime.launch(path: path)
}

Record the SDK version, pack file and checksum with your application release. When changing the recognition model, regenerate gallery embeddings and reevaluate the comparison threshold.

Change the loaded pack

Use the reload entry point when an already initialized process needs a different pack:

In 1.2.4, existing sessions retain the resources they were created with. To switch the whole application, stop submitting frames, release the old sessions, validate and reload the new pack, then create new sessions after loading succeeds. Handle any loading error before resuming processing. Rebuild the gallery when the recognition model changes.

Android 1.2.4.post1 provides InspireFace.GlobalReload(packPath), which returns false on failure. Stop workers and close capture objects, snapshots, streams and sessions before switching, then create new sessions after loading succeeds. Use GlobalLaunch(Context, model) for the AAR’s bundled models; validate an external pack with InspireFace.ValidateResourcePack(path) first.

Download an SDK

Get and build the SDK: overview and downloads lists the 1.2.4 native release, Python package and Android dependency. Check the device and process architecture, and use matching headers, wrappers and native libraries. The native release supports the API-level-2 examples; Python 1.2.4.post3 wheels and the Android 1.2.4.post1 AAR also include this SDK version.

Build a CPU SDK

Source and common options includes the checkout, dependency initialization and complete CPU build commands. The Windows, Linux and macOS chapters cover toolchains, architecture and output checks.

Build options that affect integration

Common CMake options covers shared/static linkage, C++ headers, samples, tests and hardware backends. Platform scripts can override the defaults; use the corresponding build chapter to choose the configuration.

Target-specific builds

• Windows: MSVC x64 CPU builds, installed CMake targets and DLL deployment.
• Java: JAR, JNI libraries and host JVM checks.
• Android: NDK, ABIs, JNI and AAR packaging.
• iOS: device / simulator slices, XCFrameworks and CoreML.
• macOS: Intel / Apple Silicon frameworks, Swift modules and native libraries.
• HarmonyOS: native SDK and ArkTS HAR project.
• NVIDIA TensorRT: CUDA/TensorRT dependencies and build environments.
• Rockchip NPU: board toolchains, RKNN and RGA.
• Python packaging: replace native libraries, build wheels and verify installation.

For a failed launch, check the file path and pack/build pairing first. See Troubleshooting for the next steps.