API recipes

#include <inspireface/inspireface.hpp>

int32_t extract_aligned(inspire::Session& session,
                        inspirecv::FrameProcess& frame,
                        inspire::FaceTrackWrap& face,
                        inspire::FaceEmbedding& embedding) {
    inspirecv::Image aligned;
    session.GetFaceAlignmentImage(frame, face, aligned);
    if (aligned.Empty()) return HERR_SESS_REC_EXTRACT_FAILURE;
    // aligned can also be inspected or saved with aligned.Write(...).
    return session.FaceFeatureExtractWithAlignmentImage(aligned, embedding);
}

The image and embedding own their storage. GetFaceAlignmentImage returns void, so check the output image before passing it to extraction.

Enable recognition on the session first. Pass a valid token from this source image and an open IFFeatureBuffer; the caller owns both. The helper closes its crop and temporary stream and reports errors through BOOL/NSError. To save the crop, call [crop writeToFile:path error:&error] before closing it.

#import <InspireFace/InspireFaceApple.h>

static BOOL ExtractAligned(IFSession *session, IFImageStream *source,
                           HFFaceBasicToken token, IFFeatureBuffer *output,
                           NSError **error) {
    IFImageBitmap *crop = [session alignmentBitmapFromStream:source token:token error:error];
    if (crop == nil) return NO;
    IFImageStream *aligned = nil;
    @try {
        aligned = [crop snapshotStreamWithRotation:HF_CAMERA_ROTATION_0 error:error];
        if (aligned == nil) return NO;
        return [session extractAlignedFeatureFromStream:aligned
            into:output.borrowedFeature error:error];
    } @finally {
        if (aligned != nil) [aligned closeWithError:NULL];
        [crop closeWithError:NULL];
    }
}

Use a session with .recognition, a token from the current source image and an open FaceFeatureBuffer. snapshotStream explicitly copies the crop’s pixels. The helper closes temporary resources even when extraction throws; the caller closes the output buffer later. Use try crop.write(toFile: path) to save the crop before closing it.

import InspireFaceSwift

func extractAligned(session: FaceSession, source: ImageStream,
                    token: FaceToken, into output: FaceFeatureBuffer) throws {
    let crop = try session.alignmentBitmap(from: source, token: token)
    defer { try? crop.close() }
    let aligned = try crop.snapshotStream(rotation: .degrees0)
    defer { try? aligned.close() }
    try session.extractAlignedFeature(from: aligned, into: output.borrowedFeature)
}

// session, stream and faces come from the same detection call.
static android.graphics.Bitmap alignedFace(
        com.insightface.sdk.inspireface.base.Session session,
        com.insightface.sdk.inspireface.base.ImageStream stream,
        com.insightface.sdk.inspireface.base.MultipleFaceData faces) {
    if (faces == null || faces.detectedNum != 1) {
        throw new IllegalArgumentException("Expected exactly one face");
    }
    android.graphics.Bitmap aligned = InspireFace.GetFaceAlignmentImage(
            session, stream, faces.tokens[0]);
    if (aligned == null) throw new IllegalStateException("Alignment failed");
    return aligned;
}

Import com.insightface.sdk.inspireface.InspireFace. Display or save the returned bitmap, and release the original ImageStream after processing. For recognition, call ExtractFaceFeature(session, stream, token), which handles alignment and extraction together.

The caller keeps a recognition-enabled Session, the original ImageStream and its detection result alive. Pass one of that result's faces to this helper; it closes only the crop and stream it creates.

import { ImageStream, Session, TrackedFace } from '@hyperinspire/inspireface';

function extractAligned(session: Session, image: ImageStream,
                        face: TrackedFace): Float32Array {
  const crop = session.getFaceAlignmentImage(image, face);
  try {
    const aligned = ImageStream.fromBitmap(crop);
    try {
      return session.extractFeatureFromAlignmentImage(aligned);
    } finally {
      aligned.close();
    }
  } finally {
    crop.close();
  }
}

Use crop.getData() before closing the bitmap to read its pixels, dimensions and channel count. The crop uses BGR pixels; convert them to the format expected by the application's image display or encoder. The standard HAR build uses memory-based image operations. For ordinary recognition, session.extractFeature(image, face) performs alignment and extraction in one call.

Use session.face_feature_extract(image, face) for recognition; it handles alignment and extraction together. For a diagnostic overlay, obtain five-point landmarks with get_face_five_key_points. To save the aligned image itself, use the C, C++, Objective-C, Swift or Android examples above.

Pass the raw cosine result from comparison. Check BOOL/NSError before using the converted display value. Configure the shared curve with setSimilarityConverter:error: during application setup.

#import <InspireFace/InspireFaceApple.h>

static BOOL PrintDisplayScore(float cosine, NSError **error) {
    HFSimilarityConverterConfig config = {0};
    float display = 0;
    if (![IFFeatureBuffer getSimilarityConverter:&config error:error] ||
        ![IFFeatureBuffer convertSimilarity:cosine percentage:&display error:error]) return NO;
    NSLog(@"cosine=%.4f display=%.4f range=[%.2f, %.2f]",
        cosine, display, config.outputMin, config.outputMax);
    return YES;
}

This function throws on failure. Use FaceFeatureBuffer.setSimilarityConverter(_:) to change the shared curve during application setup; keep the raw cosine value for matching.

import InspireFaceSwift

func printDisplayScore(cosine: Float) throws {
    var config = HFSimilarityConverterConfig()
    var display: Float = 0
    try FaceFeatureBuffer.getSimilarityConverter(&config)
    try FaceFeatureBuffer.convert(similarity: cosine, percentage: &display)
    print("cosine=\(cosine) display=\(display) range=[\(config.outputMin), \(config.outputMax)]")
}

import { InspireFace } from '@hyperinspire/inspireface';

// cosine is the raw result of InspireFace.compareFeatures(first, second).
function printDisplayScore(cosine: number): void {
  const config = InspireFace.getSimilarityConverter();
  const display = InspireFace.similarityToPercentage(cosine);
  console.info(`cosine=${cosine} display=${display} ` +
    `range=[${config.outputMin}, ${config.outputMax}]`);
}

To adjust the curve during application setup, pass a SimilarityConverterConfig to InspireFace.updateSimilarityConverter(config).

#include <inspireface/component_version.h>
#include <iostream>

void print_diagnostics() {
    std::cout << inspire::GetDiagnosticInfo() << '\n';
    auto cv = inspire::GetComponentVersion(inspire::ComponentType::INSPIRECV);
    if (cv.IsVersionKnown()) {
        std::cout << "InspireCV " << cv.GetVersionString() << '\n';
    }
}

For a numeric status from a C++ operation, the C HFGetErrorMessage helper is also available to C++ callers by including <inspireface.h>.

Queries work before model launch. First read the required buffer capacity, including the null terminator. On an SDK failure, NSError.domain is IFErrorDomain, code preserves the C HResult. Record both fields and include localizedDescription when diagnostic text is available. Check BOOL or nil at each call site.

#import <InspireFace/InspireFaceApple.h>
#include <stdlib.h>

static BOOL PrintDiagnostics(NSError **error) {
    HInt32 required = 0;
    if (![IFDiagnostics getDiagnosticInformation:NULL capacity:0
        requiredSize:&required error:error]) return NO;
    if (required <= 0) return IFCheck(HERR_INVALID_PARAM, error);
    char *buffer = calloc((size_t)required, 1);
    if (buffer == NULL) return IFCheck(HERR_INVALID_PARAM, error);
    BOOL ok = [IFDiagnostics getDiagnosticInformation:buffer capacity:required
        requiredSize:&required error:error];
    if (ok) NSLog(@"%s", buffer);
    free(buffer);
    return ok;
}

static void LogSDKError(NSError *error) {
    NSLog(@"%@ code=%ld: %@", error.domain, (long)error.code, error.localizedDescription);
}
// NSError *error = nil;
// if (!PrintDiagnostics(&error)) LogSDKError(error);

The Swift methods throw the same SDK errors as NSError. Query buffer size before allocation and log the domain, numeric code and description at the application boundary. A successful tracking result with zero faces is a normal result, not an exception.

import InspireFaceSwift

func printDiagnostics() throws {
    var required: Int32 = 0
    try InspireFaceDiagnostics.getDiagnosticInformation(nil, capacity: 0, requiredSize: &required)
    guard required > 0 else {
        throw NSError(domain: IFErrorDomain, code: Int(HERR_INVALID_PARAM))
    }
    let buffer = UnsafeMutablePointer<CChar>.allocate(capacity: Int(required))
    defer { buffer.deallocate() }
    try InspireFaceDiagnostics.getDiagnosticInformation(buffer, capacity: required,
                                                        requiredSize: &required)
    print(String(cString: buffer))
}

func logSDKError(_ error: Error) {
    let failure = error as NSError
    print("\(failure.domain) code=\(failure.code): \(failure.localizedDescription)")
}
// do { try printDiagnostics() } catch { logSDKError(error) }

static void printDiagnostics() {
    com.insightface.sdk.inspireface.base.InspireFaceVersion version =
            InspireFace.QueryInspireFaceVersion();
    if (version == null) throw new IllegalStateException("Version query failed");
    android.util.Log.i("FaceSDK", version.major + "." + version.minor + "."
            + version.patch + " " + version.information);
    InspireFace.SetLogLevel(InspireFace.LOG_INFO);
}

Java SDK 1.2.0 provides version information and log settings. Check null and boolean results at each call site, and include the operation and input format in the application's log.

import { FaceTrackResult, ImageStream, InspireFace, LogLevel, Session }
  from '@hyperinspire/inspireface';

function printDiagnostics(): void {
  const version = InspireFace.getVersion();
  console.info(`${version.major}.${version.minor}.${version.patch} ` +
    `C API level=${InspireFace.getCapiLevel()}`);
  console.info(InspireFace.getDiagnosticInformation());
  console.info(InspireFace.getComponentVersions());
  InspireFace.setLogLevel(LogLevel.INFO);
}

// The caller owns session/image and releases the returned face result.
function detectWithContext(session: Session, image: ImageStream): FaceTrackResult {
  try {
    return session.track(image);
  } catch (error) {
    const failure = error as Error;
    console.error(`track failed: ${failure.message}`);
    throw error;
  }
}

The ArkTS bridge throws errors for failed operations. Keep the error message, which includes the operation and SDK error text. When working with a numeric SDK status, InspireFace.getErrorMessage(code) returns its description. A successful result with detectedNum === 0 simply contains no faces.

import inspireface as isf

print(isf.version(), "C API level", isf.c_api_level())
print(isf.diagnostic_info())
for name, component in isf.component_versions().items():
    print(name, component["state"], component["version"])

# At the application boundary, preserve the original exception.
def detect_with_context(session, image):
    try:
        return session.face_detection(image)
    except isf.InspireFaceError as error:
        print(error.error_code, error.error_name, str(error))
        raise

Use a matching 1.2.4 wrapper and native library for these diagnostics. Log and handle processing exceptions separately from detection results. An empty result means the call succeeded with no accepted faces.

C++ Session, Image and the capture selector release their owned state when their scope ends. In an application that also uses the C API, the diagnostics above count active C session and stream handles. Use a memory profiler to inspect native C++ objects and GPU allocations.

Call before and after the workload on a quiet processing queue. Explicit closeWithError: releases a wrapper’s native handle immediately; ARC also releases owned handles when the object is destroyed. Close capture before its parent session and close streams before freeing borrowed input pixels. These counters cover sessions and streams, not every allocation.

#import <InspireFace/InspireFaceApple.h>

static BOOL PrintOpenHandles(NSError **error) {
    HInt32 sessions = 0, streams = 0;
    if (![IFDiagnostics getLiveSessionCount:&sessions error:error] ||
        ![IFDiagnostics getLiveStreamCount:&streams error:error]) return NO;
    NSLog(@"open sessions=%d streams=%d", sessions, streams);
    return [IFDiagnostics printResourceStatisticsWithError:error];
}

Use defer { try? resource.close() } for function-scoped resources, placing the defer immediately after successful creation. For long-lived camera objects, close them after their serial worker stops. The Swift closure helpers bound borrowed access; they do not make saved pointers valid after close or a later processing call.

import InspireFaceSwift

func printOpenHandles() throws {
    var sessions: Int32 = 0
    var streams: Int32 = 0
    try InspireFaceDiagnostics.getLiveSessionCount(&sessions)
    try InspireFaceDiagnostics.getLiveStreamCount(&streams)
    print("open sessions=\(sessions) streams=\(streams)")
    try InspireFaceDiagnostics.printResourceStatistics()
}

Pair every CreateSession with ReleaseSession and every stream creation with ReleaseImageStream, usually in finally. The newer FaceCapture and FaceDetectionSnapshot classes support try-with-resources when used with their matching JNI library.

Launch the model once before calling this helper. The frame is a tightly packed RGBA buffer; each call creates and closes one session, image stream and detection result.

import { DetectMode, ImageFormat, InspireFace } from '@hyperinspire/inspireface';

function checkResourceLifetime(rgba: Uint8Array, width: number, height: number): void {
  const before = InspireFace.getDebugResourceCounts();
  const session = InspireFace.createSession({ detectMode: DetectMode.ALWAYS_DETECT });
  try {
    const image = InspireFace.createImageStream(rgba, width, height, ImageFormat.RGBA);
    try {
      const faces = session.track(image);
      try {
        console.info(`faces=${faces.detectedNum}`);
      } finally {
        session.releaseFaceResult(faces);
      }
    } finally {
      image.close();
    }
  } finally {
    session.close();
    const after = InspireFace.getDebugResourceCounts();
    console.info(`sessions=${before.sessions}->${after.sessions} ` +
      `streams=${before.streams}->${after.streams}`);
    InspireFace.showDebugResourceStatistics();
  }
}

The counters cover sessions and streams. Also call ImageBitmap.close() and FaceCaptureSession.close() for objects you create, and release every result returned by session.track(). Keep a capture session inside its parent session's lifetime.

import inspireface as isf

# Call before and after a bounded workload during development.
isf.show_system_resource_statistics()

Prefer context managers for sessions, streams, snapshots and capture. For longer-lived application objects, call close() or release() when the owner shuts down.