这篇文章基于 ArcfaceDemo HarmonyOS 示例工程，围绕 ArcSoft ArcFace SDK 在 HarmonyOS ArkTS 项目中的接入、激活、相机实时流处理、人脸注册识别、活体检测、人脸属性分析、图片比对和人脸管理进行实操拆解。示例工程的主要思路是：页面负责交互和绘制，Camera Worker 负责采集帧。算法 Worker 负责人脸检测、活体和特征处理，文件 Worker 负责注册照和特征文件落盘。

一、Demo 功能概览

从首页入口可以看到。该 Demo 覆盖了人脸识别增值版常见能力：

• 从人脸识别来看，实时预览中检测人脸，支持现场注册、历史人脸批量加载和识别比对。说起来，
• 说到活体检测。包含 RGB 活体、交互式动作活体、炫光活体、交互式炫光活体。
• 至于人脸属性。对图片做人脸检测，并输出年龄、性别、活体等属性。
• 图片比对这方面。选择注册照和识别照，提取特征后计算相似度。
• 从人脸管理来看。展示沙箱中的注册照和特征文件，支持删除、更新特征。
• 再看参数设置，通过 AppStorage 和 Preferences 管理活体开关和阈值。
• 引擎激活这方面，输入 APP_IDSDK_KEY 后调用 SDK 在线激活接口。

使用者痛点：

• 功能碎片化：开发者常抱怨一次性看不清所有能力如何组合使用，本节提供完整能力清单帮助快速定位需求。
• 激活流程繁琐：线上激活需要手动填入密钥且缺少错误提示，本 Demo 将激活状态统一放在首页入口并实时反馈。

相关入口配置在 entry/src/main/resources/base/profile/router_map.json首页菜单在 entry/src/main/ets/pages/Index.ets.

二、工程接入与运行准备

运行环境

{
"targetSdkVersion": "."。"compatibleSdkVersion": "."
}

{
"dependencies": {
"arcsoft_face": "file:../entry/libs/arcsoft_face.har"
}
}

"requestPermissions":,"when": "inuse"
}
}
]

Pain Point – 环境准备：C++/Java 开发者往往不熟悉 Harmony 的权限模型与 HAR 包引用方式，本节通过表格直观展示每一步骤，让新手无需反复查文档就可以完成依赖导入。

实操步骤建议

1. 使用 DevEco Studio 打开 /samplecode/ArcfaceDemo.
2. 确认 /entry/libs/arcsoft_face.har  存在且 /entry/oh‑package.json5  能解析本地依赖。
/src/main/ets/utils/Constants.ets  中替换为自己的 ID / KEY ，切勿泄露到公共仓库。

If your product requires online activation or network calls,remember to add network permissions and privacy compliance statements.

三、启动链路

The entry point is /entry/src/main/ets/entryability/EntryAbility.ets . On launch it initializes parameter manager and loads user‑agreement state:

 {
ParamManager.init;说起来，await preferencesUtil.loadPreferences;}

The window n loads home page:

windowStage.loadContent => {
if { return;}
})，

首页关键流程

1. Pops up privacy agreement on first launch.
2. User consent triggers camera permission request via PasswordManager.request .
3. The app calls FaceEngine.init for a lightweight image‑mode init just to verify SDK status and version.

async onAccept {
await preferencesUtil.putPreferencesValue(Constants.AGREE_NAME。Constants.IS_AGREE_NAME,true);await PermissionManager.request(Constants.PERMISSIONS,this.context);await this.initFaceEngine;}
private async initFaceEngine {
const initRes = await this.faceEngine.init(
this.context,DetectMode.ASF_DETECT_MODE_IMAGE。OrientPriority.ASF_OP_ALL_OUT,CombinedMask.ASF_FACE_DETECT | CombinedMask.ASF_FACE_RECOGNITION
);}

The home page uses image‑mode detection only – real‑time video pages will re‑initialize engine with video mode later.

• 页面与底层引擎耦合过紧导致后续功能 困难。老实说，Demo 将 UI 与 Engine 初始化分离。为业务层提供统一入口，
• 首次授权弹窗缺少可自定义文案。这里演示了通过PermissionManager.request 动态注入文案的做法，可直接 为公司隐私协议模板。

四、激活引擎

The activation page resides at /entry/src/main/ets/pages/ActiveEngine . ets . The flow consists of three steps:

1. 初始化引擎： 页面打开时创建一个包括检测、识别、年龄、性别和全部活体能力的完整 Engine 实例。

   await this.faceEngine.init(
   this.context,DetectMode.ASF_DETECT_MODE_IMAGE,OrientPriority.ASF_OP_ALL_OUT。CombinedMask.ASF_FACE_DETECT |
   CombinedMask.ASF_FACE_RECOGNITION |
   CombinedMask.ASF_AGE |
   CombinedMask.ASF_GENDER |
   CombinedMask.ASF_LIVENESS);

2. 在线激活： 点击按钮调用 faceEngine.active,成功后更新全局激活状态。

   let res:number = await this.faceEngine.active;if {
   Utils.showToast);return，}
   ParamManager.update;

3. 授权门禁： 首页通过 @StorageLink读取状态；怎么说呢，未激活时点击受限功能会自动跳转到此页。

   navigateTo{
   if {
   this.pageInfos.pushPath;} else{
   this.pageInfos.pushPath;}
   }
   

This design centralizes activation checks,avoiding repetitive guard logic across all feature pages.

User Pain Point – Activation Complexity:

• Many developers forget to guard feature entry after activation failure。leading to runtime crashes. The unified gate in Index solves it.
• Hard‑coded APP_ID / SDK_KEY in source control is a security risk—Demo clearly marks where to replace m and warns against publishing.

五、相机实时流

The real‑time recognition and liveness modules share a common camera pipeline split into .

1. 双路预览：  创建两条预览流——一条绑定 XComponent 用于 UI 显示，一条绑定 ImageReceiver 用于获取原始帧交给算法 Worker。

   /​// UI preview stream
   this.previewOutput = this.cameraManager.createPreviewOutput;// Frame capture stream
   this.receiver = image.createImageReceiver;let imageReceiverSurfaceId = await this.receiver.getReceivingSurfaceId;this.previewOutput2 = this.cameraManager.createPreviewOutput;

2. 帧回调：  读取 ImageReceiver 中 JPEG 数据并回调给 .

   receiver.on=>{
   receiver.readNextImage=>{
   nextImage.getComponent=>{
   if{
   this.onImageCallback;}
   nextImage.release;})，});
   })，

3. 共享内存双缓冲：  使用  实现零拷贝帧传输。说起来，Header 区保存 seq/writeIdx/readIdx/status 四个 Int32；随后两个等长缓冲区轮流写入。

   /​const HEADER_INTS = …//
   headerView = new Int32Array;frameBytes = Math.ceil / …)+，;frame0Offset = HEADER_BYTES;frame1Offset = HEADER_BYTES + frameBytes;

4. 写入帧并通知算法 Worker：  确保多线程同步。

   /​let writeIdx=+1)%BUFFER_COUNT;const dstOffset = writeIdx===0?frame0Offset:frame1Offset;const pixelView=new Uint8Array;pixelView.set);Atomics.store;// update seq
   workerPort.postMessage;

This architecture keeps heavy image data off main thread and avoids per‑frame object allocation—critical for smooth UI on low‑end devices.

User Pain Point – Performance Bottleneck:
• The original demo placed image processing directly on UI thread causing jank on older phones. The shared memory + worker model resolves it.
• Lack of format validation often leads to “unsupported format” errors when device camera outputs YUV420 instead of NV21. The note about verifying ImageFormat helps avoid runtime crashes.

六、人脸识别

The recognition page lives at /entry/src/main/ets/pages/RecognizeAndRegister . ets . Its overall pipeline is:

• — four workers coordinate detection,feature extraction & persistence.
• : 双路预览 + 帧写入 SharedArrayBuffer → FRAME_READY 通知算法层。按理说，
• : 视频模式轻量检测。返回人脸坐标供后续处理使用。
• : 人脸特征提取或搜索。内部 spawn FileWorker 完成持久化。
• : 将 .dat 特征文件及裁剪后的注册头像保存至 sandbox//registerImages​)。

The recognition chain uses video mode which differs from homepage’s image mode initialization.

主要步骤拆解

• let sab=new SharedArrayBuffer;this.cameraWorker.postMessage;this.faceRecognitionManager?.initialize，this.faceRecognitionManager?.registerAllFace;
**User Pain Point – Feature Registration Management:** Many developers struggle with persisting face features securely and keeping m in sync after app restarts. This demo separates in‑memory engine registration from sandbox file storage and provides explicit load/unload logic. **User Pain Point – Real‑Time Recognition Latency:** If multiple faces appear simultaneously demo defaults to largest face only . For multi‑person scenarios you must extend `FaceRecognitionManager` with a map of `searchId` per detected face.

---

检测与特征提取流程

typescript // FRWorker 检测当前帧 const detectRes = frEngine.detectFaces;ftWorker.postMessage({ 至于action。WorkerActions.EXTRACT_FEATURE,extractType: registerNextFrame?ExtractType.ASF_REGISTER : ExtractType.ASF_RECOGNITION,…})，其实，typescript // FTWorker 提取特征 const extractRes = ftEngine.extractFaceFeature;

注册方法

typescript const featureOfReg:{searchId,…}= {，};话说回来，const registerRes = ftEngine.registerFaceFeature;fileWorker.postMessage;// 保存图片 & .dat 文件

识别方法

typescript const searchRes = ftEngine.searchFaceFeature(faceFeature.feature。CompareModel.ASF_LIFE_PHOTO,searchResult);workerPort.postMessage({ 至于action，WorkerActions.FR_RESULT。type:'recognize',success: similarity>=Constants.SIMILARITY_THRESHOLD,…})，

---

实时预览中 SDK 返回的人脸框坐标属于原始图像坐标系，而前置摄像头画面需要旋转 + 镜像处理。Demo 把所有坐标转换封装到 `DrawHelper.ts` 中。typescript const ratio = surfaceWidth / imageHeight;const scaleLeft=Math.floor);// ，怎么说呢，or sides …const x=isMirror?canvasWidth-scaleBottom:scaleLeft;四角线段代替普通矩形，使视觉效果更贴近实际业务需求。**使用者痛点 – 坐标偏移** 前置摄像头经常导致框偏左或倒置，新手很难自行调试。本 Demo 提供统一转换函数，只需修改 `isMirror` 标记即可适配不同设备。按理说，---

八、活体检测