arc/lib/arc.dart

import 'dart:typed_data';

import 'arc_platform_interface.dart';

class Arc {
  /// 获取平台版本
  Future<String?> getPlatformVersion() {
    return ArcPlatform.instance.getPlatformVersion();
  }

  /// 激活 SDK（在线激活）
  /// [appId] 应用 ID（从虹软控制台获取）
  /// [sdkKey] SDK 密钥（从虹软控制台获取）
  /// [activeKey] 激活密钥
  /// 返回包含 success, errorCode, message 的 Map
  Future<Map<String, dynamic>?> activeOnline({
    required String appId,
    required String sdkKey,
    required String activeKey,
  }) {
    return ArcPlatform.instance.activeOnline(
      appId: appId,
      sdkKey: sdkKey,
      activeKey: activeKey,
    );
  }

  /// 初始化人脸识别引擎
  /// [detectMode] 检测模式（0=VIDEO 视频流模式，1=IMAGE 图像模式）
  /// [orient] 检测角度（0/90/180/270/360）
  /// [maxFaceNum] 最大可检测人脸数量
  /// [combinedMask] 功能组合掩码
  /// 返回包含 success, errorCode, message 的 Map
  Future<Map<String, dynamic>?> init({
    int? detectMode,
    int? orient,
    int? maxFaceNum,
    int? combinedMask,
  }) {
    return ArcPlatform.instance.init(
      detectMode: detectMode,
      orient: orient,
      maxFaceNum: maxFaceNum,
      combinedMask: combinedMask,
    );
  }

  /// 检测人脸（同时进行 RGB 活体检测）
  /// [data] NV21 格式的图像数据
  /// [width] 图像宽度
  /// [height] 图像高度
  /// [format] 图像格式（2050=NV21，默认）
  /// 返回包含 success, errorCode, message, faceList, rgbLiveness, isRgbAlive 的 Map
  /// rgbLiveness: -1=未知, 0=非真人, 1=真人
  Future<Map<String, dynamic>?> detectFaces({
    required Uint8List data,
    required int width,
    required int height,
    int format = 2050,
  }) {
    return ArcPlatform.instance.detectFaces(
      data: data,
      width: width,
      height: height,
      format: format,
    );
  }

  /// 提取人脸特征
  /// [data] NV21 格式的图像数据
  /// [width] 图像宽度
  /// [height] 图像高度
  /// [rectLeft] 人脸框左边界（从detectFaces获取）
  /// [rectTop] 人脸框上边界（从detectFaces获取）
  /// [rectRight] 人脸框右边界（从detectFaces获取）
  /// [rectBottom] 人脸框下边界（从detectFaces获取）
  /// [format] 图像格式（2050=NV21，默认）
  /// [faceOrientation] 人脸角度（从detectFaces获取）
  /// [faceId] 人脸ID（从detectFaces获取）
  /// [faceData] 人脸数据（从detectFaces获取，必需！这是虹软SDK进行特征提取的关键数据）
  /// [extractType] 特征提取类型（0=注册, 1=识别，默认为识别）
  /// [mask] 口罩状态（0=未佩戴, 1=已佩戴，默认为未佩戴）
  /// 返回包含 success, errorCode, message, featureData 的 Map
  Future<Map<String, dynamic>?> extractFaceFeature({
    required Uint8List data,
    required int width,
    required int height,
    required int rectLeft,
    required int rectTop,
    required int rectRight,
    required int rectBottom,
    int format = 2050,
    int faceOrientation = 0,
    int faceId = -1,
    Uint8List? faceData,
    int extractType = 1,
    int mask = 0,
  }) {
    return ArcPlatform.instance.extractFaceFeature(
      data: data,
      width: width,
      height: height,
      rectLeft: rectLeft,
      rectTop: rectTop,
      rectRight: rectRight,
      rectBottom: rectBottom,
      format: format,
      faceOrientation: faceOrientation,
      faceId: faceId,
      faceData: faceData,
      extractType: extractType,
      mask: mask,
    );
  }

  /// 比对人脸特征
  /// [featureData1] 第一个人脸特征数据（从extractFaceFeature获取）
  /// [featureData2] 第二个人脸特征数据（从extractFaceFeature获取）
  /// [compareModel] 比对模型（0=生活照, 1=证件照，默认为生活照）
  /// 返回包含 success, errorCode, message, similarity 的 Map
  /// similarity: 相似度分数（0-1之间，推荐阈值：生活照0.8，证件照0.82）
  Future<Map<String, dynamic>?> compareFaceFeature({
    required Uint8List featureData1,
    required Uint8List featureData2,
    int compareModel = 0,
  }) {
    return ArcPlatform.instance.compareFaceFeature(
      featureData1: featureData1,
      featureData2: featureData2,
      compareModel: compareModel,
    );
  }

  /// 注册单张人脸特征到人脸库（用于1:N搜索）
  /// [searchId] 唯一标识符（用于后续搜索匹配，建议使用用户ID）
  /// [featureData] 人脸特征数据（从extractFaceFeature获取，建议使用extractType=0注册模式）
  /// [faceTag] 附属信息（可选，如用户名、员工ID等）
  /// 返回包含 success, errorCode, message 的 Map
  /// 注意：如果底库中已存在相同searchId，SDK会忽略此次注册
  Future<Map<String, dynamic>?> registerFaceFeature({
    required int searchId,
    required Uint8List featureData,
    String? faceTag,
  }) {
    return ArcPlatform.instance.registerFaceFeature(
      searchId: searchId,
      featureData: featureData,
      faceTag: faceTag,
    );
  }

  /// 批量注册人脸特征到人脸库（用于1:N搜索）
  /// [faceList] 人脸列表，每项需包含：
  ///            - searchId: 唯一标识符（int，必填）
  ///            - featureData: 人脸特征数据（Uint8List，必填）
  ///            - faceTag: 附属信息（String，可选）
  /// 返回包含 success, errorCode, message 的 Map
  /// 示例：
  /// ```dart
  /// await arc.registerFaceFeatureBatch(
  ///   faceList: [
  ///     {'searchId': 1, 'featureData': feature1, 'faceTag': '张三'},
  ///     {'searchId': 2, 'featureData': feature2, 'faceTag': '李四'},
  ///   ],
  /// );
  /// ```
  Future<Map<String, dynamic>?> registerFaceFeatureBatch({
    required List<Map<String, dynamic>> faceList,
  }) {
    return ArcPlatform.instance.registerFaceFeatureBatch(
      faceList: faceList,
    );
  }
}