id-scanner-lib

/** * @file 人脸检测接口 * @description 定义人脸检测相关的数据类型和接口 * @module interfaces/face-detection */ import { BaseScannerResult } from './scanner-module'; /** * 坐标点接口，表示2D坐标 */ export interface Point { /** X坐标 */ x: number; /** Y坐标 */ y: number; } /** * 矩形接口，表示检测框 */ export interface Rect { /** 左上角X坐标 */ x: number; /** 左上角Y坐标 */ y: number; /** 宽度 */ width: number; /** 高度 */ height: number; } /** * 人脸关键点 */ export interface FaceLandmarks { /** 左眼位置 */ leftEye: Point; /** 右眼位置 */ rightEye: Point; /** 鼻尖位置 */ nose: Point; /** 嘴巴中心位置 */ mouth: Point; /** 左眼角位置 */ leftEyeOuterCorner?: Point; /** 右眼角位置 */ rightEyeOuterCorner?: Point; /** 左耳位置 */ leftEar?: Point; /** 右耳位置 */ rightEar?: Point; /** 所有关键点（有些实现可能提供更多点） */ points?: Point[]; } /** * 人脸角度 */ export interface FaceAngle { /** 俯仰角(上下) */ pitch: number; /** 偏航角(左右) */ yaw: number; /** 滚动角(倾斜) */ roll: number; } /** * 人脸质量评估指标 */ export interface FaceQualityMetrics { /** 亮度评分(0-1) */ brightness: number; /** 清晰度评分(0-1) */ sharpness: number; /** 姿态合规程度(0-1) */ pose: number; /** 人脸完整度(0-1) */ integrity: number; /** 整体质量分数(0-1) */ overall: number; } /** * 人脸属性 */ export interface FaceAttributes { /** 年龄估计(岁) */ age?: number; /** 性别置信度(0-1，越大越倾向于男性) */ gender?: number; /** 是否戴眼镜置信度 */ glasses?: number; /** 是否戴口罩置信度 */ mask?: number; /** 微笑程度置信度 */ smile?: number; /** 人脸表情分类 */ emotion?: { /** 生气程度 */ angry?: number; /** 恐惧程度 */ fear?: number; /** 厌恶程度 */ disgust?: number; /** 高兴程度 */ happy?: number; /** 平静程度 */ neutral?: number; /** 伤心程度 */ sad?: number; /** 惊讶程度 */ surprise?: number; }; /** 人种类别置信度 */ ethnicity?: { /** 亚洲人程度 */ asian?: number; /** 黑人程度 */ black?: number; /** 白人程度 */ caucasian?: number; /** 其他人种程度 */ other?: number; }; /** 其他自定义属性 */ [key: string]: any; } /** * 人脸特征向量（人脸嵌入） */ export interface FaceEmbedding { /** 特征向量数据 */ vector: number[]; /** 特征维度 */ dimension: number; /** 模型版本 */ modelVersion?: string; } /** * 人脸检测结果 */ export interface FaceDetectionResult extends BaseScannerResult { /** 人脸区域 */ boundingBox: Rect; /** 人脸关键点 */ landmarks?: FaceLandmarks; /** 人脸角度 */ angle?: FaceAngle; /** 检测质量 */ quality?: FaceQualityMetrics; /** 人脸属性 */ attributes?: FaceAttributes; /** 人脸特征向量 */ embedding?: FaceEmbedding; /** 相似度分数（用于比对场景） */ similarityScore?: number; /** 是否有活体检测结果 */ isLive?: boolean; /** 活体检测分数(0-1) */ livenessScore?: number; /** 标识符（可用于跟踪） */ trackId?: string; /** 人脸图像数据（裁剪后） */ faceImageData?: string; } /** * 人脸比对结果 */ export interface FaceComparisonResult { /** 相似度分数(0-1) */ similarity: number; /** 是否匹配（基于阈值判断） */ isMatch: boolean; /** 使用的阈值 */ threshold: number; /** 源人脸 */ sourceFace?: FaceDetectionResult; /** 目标人脸 */ targetFace?: FaceDetectionResult; /** 处理时间(毫秒) */ processingTime: number; } /** * 活体检测类型 */ export enum LivenessDetectionType { /** 被动活体检测（单图分析） */ PASSIVE = 'passive', /** 主动活体检测（动作挑战） */ ACTIVE = 'active', /** 混合活体检测（结合多种方法） */ HYBRID = 'hybrid' } /** * 活体检测动作类型 */ export enum LivenessAction { /** 眨眼 */ BLINK = 'blink', /** 点头 */ NOD = 'nod', /** 摇头 */ SHAKE = 'shake', /** 微笑 */ SMILE = 'smile', /** 张嘴 */ MOUTH_OPEN = 'mouth_open', /** 注视点 */ GAZE = 'gaze' } /** * 活体检测结果 */ export interface LivenessDetectionResult { /** 是否为真人 */ isLive: boolean; /** 活体分数(0-1) */ score: number; /** 使用的活体检测类型 */ type: LivenessDetectionType; /** 活体检测动作（如果使用了主动活体检测） */ actions?: LivenessAction[]; /** 检测时间(毫秒) */ processingTime: number; /** 检测结果图片 */ imageData?: string; } /** * 活体检测会话 */ export interface LivenessSession { /** 会话ID */ id: string; /** 活体检测类型 */ type: LivenessDetectionType; /** 需要完成的动作 */ requiredActions?: LivenessAction[]; /** 当前动作索引 */ currentActionIndex?: number; /** 会话开始时间 */ startTime: number; /** 会话超时时间(毫秒) */ timeout: number; /** 会话状态 */ status: 'active' | 'completed' | 'failed' | 'timeout'; /** 完成的动作 */ completedActions?: LivenessAction[]; /** 活体检测结果 */ result?: LivenessDetectionResult; } /** * 人脸跟踪结果 */ export interface FaceTrackingResult { /** 跟踪ID */ trackId: string; /** 当前检测结果 */ detection: FaceDetectionResult; /** 首次检测时间 */ firstDetectedAt: number; /** 上次检测时间 */ lastDetectedAt: number; /** 跟踪状态 */ status: 'tracked' | 'lost' | 'removed'; /** 连续跟踪帧数 */ consecutiveFrames: number; /** 历史位置（最近几帧） */ history?: Rect[]; } /** * 人脸检测选项 */ export interface FaceDetectionOptions { /** 最低人脸置信度 */ minConfidence?: number; /** 最大检测人脸数 */ maxFaces?: number; /** 是否检测关键点 */ withLandmarks?: boolean; /** 是否检测属性 */ withAttributes?: boolean; /** 是否进行人脸对齐 */ doAlignment?: boolean; /** 是否提取人脸特征 */ withEmbedding?: boolean; /** 是否启用跟踪 */ enableTracking?: boolean; /** 是否执行活体检测 */ withLiveness?: boolean; /** 活体检测类型 */ livenessType?: LivenessDetectionType; /** 返回人脸图像 */ returnFaceImage?: boolean; /** 活体检测选项 */ livenessOptions?: Record<string, any>; /** 其他选项 */ [key: string]: any; }