InspireFaceInspireFace1.2.4.d10
首页
快速开始
获取和编译
完整示例
  • English
  • 简体中文
GitHub
首页
快速开始
获取和编译
完整示例
  • English
  • 简体中文
GitHub
  • 介绍
  • 快速开始
  • 功能概览
  • 使用指南

    • 架构与生命周期
    • 模型资源包
    • 图像输入与坐标
    • 会话与跟踪
    • 人脸分析
    • 识别与特征库
    • 人脸关键点
    • 活体检测
    • 人脸抓拍
    • 补充 API 示例
  • 语言与平台

    • C API
    • C++
    • Python
    • Java
    • Windows
    • Android
    • Apple
    • iOS
    • macOS
    • HarmonyOS
  • 获取和编译

    • 概述与下载
    • 源码准备与通用选项
    • Linux
    • Windows
    • macOS
    • Android
    • iOS
    • HarmonyOS
    • NVIDIA TensorRT
    • Rockchip NPU
    • Python 打包
    • Java 打包
  • 硬件部署

    • x86 CPU
    • ARM
    • NVIDIA TensorRT
    • Rockchip NPU
    • Rockchip 上的 Python
  • InspireCV
  • 完整示例
  • API 功能索引
  • 性能测量
  • 图像处理性能
  • 常见问题

人脸关键点

关键点描述检测到的人脸上的位置。五点输出适合人脸对齐,稠密关键点适合轮廓、贴图和局部图像处理。两者都在检测后通过人脸 token 获取。

使用人脸关键点对齐表情贴图

读取关键点

C API

从检测结果的 token 中读取五点坐标。下方的密集关键点辅助函数会先查询点数,再分配数组。两种调用均使用成功检测后得到的 faces.tokens[i]。

static HResult print_five_points(HFFaceBasicToken token) {
    HPoint2f points[5];
    HResult status = HFGetFaceFiveKeyPointsFromFaceToken(token, points, 5);
    if (status != HSUCCEED) return status;
    for (HInt32 i = 0; i < 5; ++i) {
        printf("%d: %.2f, %.2f\n", i, points[i].x, points[i].y);
    }
    return HSUCCEED;
}
C++

FaceDetectAndTrack 成功后,直接从每个 FaceTrackWrap 读取两组关键点。

for (const auto& face : faces) {
    auto fivePoints = session.GetFaceFiveKeyPoints(face);
    auto densePoints = session.GetFaceDenseLandmark(face);
    std::cout << fivePoints.size() << " " << densePoints.size() << '\n';
    for (const auto& point : densePoints) {
        std::cout << point.GetX() << ", " << point.GetY() << '\n';
    }
}
Objective-C

传入当前 HFMultipleFaceData 中的 token,并在下一次跟踪前读取;也可以使用尚未关闭的 IFFaceSnapshot 中的 token。接口写入调用方提供的数组,通过 BOOL 和 NSError 检查结果。

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

static BOOL ReadLandmarks(HFFaceBasicToken token, NSError **error) {
    HInt32 count = 0;
    if (![IFFaceToken getDenseLandmarkCount:&count error:error]) return NO;
    if (count <= 0) return IFCheck(HERR_INVALID_PARAM, error);
    HPoint2f five[5];
    HPoint2f *dense = calloc((size_t)count, sizeof(*dense));
    if (dense == NULL) return IFCheck(HERR_INVALID_PARAM, error);
    BOOL ok = [IFFaceToken getFiveKeyPoints:token into:five capacity:5 error:error] &&
        [IFFaceToken getDenseLandmarks:token into:dense capacity:count error:error];
    if (ok) {
        for (HInt32 i = 0; i < count; ++i) {
            NSLog(@"%d: %.2f, %.2f", i, dense[i].x, dense[i].y);
        }
    }
    free(dense);
    return ok;
}
Swift

在 session.withUnsafeFaces(in:) 内传入 faces.tokens[i],或保持对应的快照处于打开状态。输出数组独立保存坐标;视频循环中可以先查询点数,再分配一次数组并逐帧复用。

import InspireFaceSwift

func readLandmarks(token: FaceToken) throws {
    var count: Int32 = 0
    try FaceTokenUtilities.getDenseLandmarkCount(&count)
    guard count > 0 else {
        throw NSError(domain: IFErrorDomain, code: Int(HERR_INVALID_PARAM))
    }
    var five = [HPoint2f](repeating: HPoint2f(), count: 5)
    var dense = [HPoint2f](repeating: HPoint2f(), count: Int(count))
    try five.withUnsafeMutableBufferPointer {
        try FaceTokenUtilities.getFiveKeyPoints(token, into: $0)
    }
    try dense.withUnsafeMutableBufferPointer {
        try FaceTokenUtilities.getDenseLandmarks(token, into: $0)
    }
    for (index, point) in dense.enumerated() {
        print("\(index): \(point.x), \(point.y)")
    }
}
Java

使用 Java SDK 完成跟踪后,调用 readLandmarks(faces.tokens[i])。Token 引用原生内存:保持对应会话或 snapshot 有效,并在该结果被替换前完成读取。JNI 会填充 HPoint2f[] 中的元素;得到的坐标是 Java 数值,可以保留。密集关键点数量通过查询获取,不要写死。

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

public final class LandmarkExample {
    public static void readLandmarks(HFFaceBasicToken token) {
        int[] count = new int[1];
        check(HFGetNumOfFaceDenseLandmark(count));
        if (count[0] <= 0) throw new IllegalStateException("No landmark model");
        HPoint2f[] five = new HPoint2f[5];
        HPoint2f[] dense = new HPoint2f[count[0]];
        check(HFGetFaceFiveKeyPointsFromFaceToken(token, five, five.length));
        check(HFGetFaceDenseLandmarkFromFaceToken(token, dense, dense.length));
        System.out.println("five=" + five.length + " dense=" + dense.length);
        for (HPoint2f point : dense) {
            System.out.println(point.x + ", " + point.y);
        }
    }
}
Android

Android 1.2.4.post1 同时提供五点和稠密关键点。静态图片使用 DETECT_MODE_ALWAYS_DETECT,视频使用 DETECT_MODE_LIGHT_TRACK 并复用会话。检测结果的 token 和返回的 Point2f[] 都使用 Java 自有存储;绘制前仍需转换到预览坐标。

// Use ALWAYS_DETECT for independent photos, or LIGHT_TRACK for video.
MultipleFaceData faces = InspireFace.ExecuteFaceTrack(session, stream);
if (faces == null) throw new IllegalStateException("Detection failed");
for (int i = 0; i < faces.detectedNum; i++) {
    Point2f[] five = InspireFace.GetFaceFiveKeyPointsFromFaceToken(faces.tokens[i]);
    Point2f[] dense = InspireFace.GetFaceDenseLandmarkFromFaceToken(faces.tokens[i]);
    if (five == null || five.length != 5 || dense == null || dense.length == 0) {
        throw new IllegalStateException("Landmarks are unavailable");
    }
    System.out.println("five=" + five.length + " dense=" + dense.length);
    for (Point2f point : dense) {
        System.out.println(point.x + ", " + point.y);
    }
}
HarmonyOS

传入已初始化的 Session 和当前帧的 ImageStream。两种关键点接口都返回按 x0, y0, x1, y1, … 排列的 Float32Array。函数释放检测结果;会话由调用方保留,图像流在该帧所有处理完成后关闭。

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

function readLandmarks(session: Session, stream: ImageStream): void {
  const result = session.track(stream);
  try {
    for (const face of result.faces) {
      const five = InspireFace.getFiveKeyPoints(face);
      const dense = InspireFace.getDenseLandmarks(face);
      console.info(`five=${five.length / 2} dense=${dense.length / 2}`);
      for (let i = 0; i < dense.length; i += 2) {
        console.info(`${dense[i]}, ${dense[i + 1]}`);
      }
    }
  } finally {
    session.releaseFaceResult(result);
  }
}
Python

以下使用已初始化的会话,image 是本次检测的 BGR 原始图像。

# session is initialized; image is the BGR frame used for this detection.
faces = session.face_detection(image)
for face in faces:
    five_points = session.get_face_five_key_points(face)
    dense_points = session.get_face_dense_landmark(face)
    print(five_points.shape, dense_points.shape)
    for x, y in dense_points:
        cv2.circle(image, (round(float(x)), round(float(y))), 1, (0, 220, 0), -1)

先读取所有需要原始像素的结果,再绘制图像,或者在副本上绘制。Python 五点输出的形状为 (5, 2);当前稠密关键点引擎输出 106 个点。在 C 中先查询原生接口返回的点数,再按这个长度分配数组。

在 C 中读取关键点

下面的辅助函数打印一个有效检测 token 中的关键点,并返回遇到的第一个错误。它使用调用方已有的 SDK 会话和检测结果。

#include <stdio.h>
#include <stdlib.h>
#include <inspireface.h>

static HResult print_landmarks(HFFaceBasicToken token) {
    HInt32 count = 0;
    HResult status = HFGetNumOfFaceDenseLandmark(&count);
    if (status != HSUCCEED) return status;
    if (count <= 0) return HERR_INVALID_PARAM;
    HPoint2f *points = (HPoint2f *)malloc((size_t)count * sizeof(*points));
    if (points == NULL) return HERR_INVALID_PARAM;
    status = HFGetFaceDenseLandmarkFromFaceToken(token, points, count);
    if (status == HSUCCEED) {
        for (HInt32 i = 0; i < count; ++i) {
            printf("%d: %.2f, %.2f\n", i, points[i].x, points[i].y);
        }
    }
    free(points);
    return status;
}

使用 faces.tokens[i] 调用时,应在下一次跟踪覆盖会话借用的结果之前完成。若要在处理下一帧后继续使用结果,也可以创建具有独立生命周期的检测快照。

Snapshot 与延时

Snapshot 可以在后续帧到来后继续保留检测结果,在不同处理步骤间传递更方便,但创建时会拷贝数据,增加延时。直接读取当前会话结果可以省去这次拷贝,适合单路视频连续处理;请在下一次跟踪或重置会话前用完其中的 token。

原生 C++ 接口通过 session.GetFaceDenseLandmark(face) 和 session.GetFaceFiveKeyPoints(face) 读取 FaceTrackWrap 中的关键点。完整检测循环见 C++ 接入。

选择关键点引擎

可选的关键点引擎:

EngineEnum
HyperLandmarkV2 0.25 (default)HF_LANDMARK_HYPLMV2_0_25
HyperLandmarkV2 0.50HF_LANDMARK_HYPLMV2_0_50
InsightFace 2D106 trackingHF_LANDMARK_INSIGHTFACE_2D106_TRACK

在创建会话前选择引擎:C 与 Java 使用 HFSwitchLandmarkEngine,Objective-C 使用 [IFRuntime setLandmarkEngine:HF_LANDMARK_HYPLMV2_0_25 error:&error],Swift 使用 try InspireFaceRuntime.setLandmarkEngine(.hyperLandmark025),HarmonyOS 使用 InspireFace.switchLandmarkEngine,Python 使用 isf.switch_landmark_engine。选择结果对新创建的会话生效,模型包需要包含对应模型。

Android AAR 同时包含完整 JNI 接口,可以直接用 Native.HFSwitchLandmarkEngine 切换引擎:

import com.insightface.sdk.inspireface.jni.InspireFaceException;
import com.insightface.sdk.inspireface.jni.Native;
import static com.insightface.sdk.inspireface.jni.NativeConstants.*;

// After GlobalLaunch and before CreateSession.
InspireFaceException.check(Native.HFSwitchLandmarkEngine(HF_LANDMARK_HYPLMV2_0_25));

视频接入可以先使用默认引擎,再用典型视频片段比较点位稳定性和耗时,选择合适的引擎。

点位顺序与坐标

下图展示 HyperLandmarkV2 的点位顺序。提取眼部、嘴部或轮廓点时,使用所选引擎对应的索引。

标有索引编号的 HyperLandmarkV2 人脸关键点分布图
HyperLandmarkV2 索引图。例如,左眼轮廓对应 51–58,右眼轮廓对应 59–66。

关键点坐标属于输入帧。绘制到摄像头界面前,还需应用预览的裁剪、缩放和镜像变换。详见图像输入与坐标。

平滑视频关键点

按顺序处理视频时使用跟踪模式,通过跟踪参数调整平滑比例与缓存长度。增强平滑能减少抖动,也会在快速运动时增加延迟。可以用包含静止、转头和短暂遮挡的视频片段评估设置。

每路摄像头使用独立会话,分别保存各自的跟踪历史。Android 的 InspireFace.SetLandmarkAugmentationNum(session, num) 可调整关键点增强次数,默认为 1,必须大于零。增加次数会增加计算量,应同时比较点位稳定性和单帧延时。

更多类型的关键点模型

HyperLandmark 提供多个版本的关键点模型,包括侧重高精度、高稳定度或低延时的版本,也有不同的特征点数量与分布方案。可以根据关注的人脸区域、所需的细节程度、视频跟踪需求和设备性能,选择合适的模型。

如需了解模型选择或申请商用授权,请联系 contact@insightface.ai,并说明目标平台、点位需求和使用场景。

HyperLandmark 人脸关键点示例,用不同颜色标记脸部轮廓、眉毛、眼睛、鼻子、嘴唇与虹膜
编辑此页
最近更新: 2026/9/29 15:05
贡献者: Jingyu
上一页
识别与特征库
下一页
活体检测