人脸检测 SDK

微信小程序人脸检测 SDK 是鳄梨科技提供的人脸检测、人脸分析及人脸上报服务， 支持在小程序端对视频推流LivePusherContext实例和图片进行人脸检测分析。

:sparkles: 核心功能

1. 内置一套人脸分析和提示的规则，针对实时推流进行人脸分析，显示 toast 提示，对人脸变化进行上报

2. SDK 导出内置的规则和FaceMonitor类，FaceMonitor类支持对实时推流截取的图片进行自定义处理

3. FaceMonitor类支持对接口请求、是否显示检测 toast 进行配置，支持自定义业务数据metadata

4. FaceMonitor类提供了 获取推流截屏图片、获取图片像素点数据、人脸分析、接口请求、图片上传等功能

🔨 FaceMonitor 类提供的配置项

接口请求 requestHeader

实例化时传入的requestHeader会覆盖默认值

// 默认配置
const DefaultRequestHeader = {
  Accept: 'application/json',
  'X-Avocado-Source': 'miniprogram',
  Authorization: 'Basic ' + wx.getStorageSync('authToken')
}

// 自定义配置
const CusRequestHeader = {
  'Content-Type': 'application/json',
  Accept: 'application/json',
  'X-Avocado-Source': 'miniprogram',
  Authorization: 'Basic ' + wx.getStorageSync('authToken'),
  'X-Avocado-Version': '',
  'X-Position-Token': '',
  'X-Wx-Appid': ''
}
// 配置示例
this.FaceMonitor = new FaceMonitor({
  requestHeader: CusRequestHeader
})

人脸检测 config

实例化时传入的config会和默认配置合并，优先级高于默认配置

// 默认配置
const FaceDetectOneTimeCostMax = 1000 / 1.5
const DefalutConfig = {
  showToast: true, // 是否显示人脸异常的提示
  faceDetectOneTimeCostMax: FaceDetectOneTimeCostMax, // 一次人脸识别的最大耗时
  needPredict: true // 是否需要预检，差别: 预检不通过会直接关闭人脸检测
}

// 自定义配置
const CusConfig = {
  needPredict: false
}
// 配置示例
this.FaceMonitor = new FaceMonitor({
  config: CusConfig
})

业务数据 metadata

实例化时传入的metadata会和默认数据合并，优先级高于默认数据

// 默认配置
const DefalutMetadata = {
  cheatKey: 'default' // 作弊上报key
}

// 自定义配置
const CusMetadata = {
  info: patternName, // 类型：string， 上报图片的标题或者表述，必填
  stepToken,
  mediaName: streamName,
  cheatKey: token
}
// 配置示例
this.FaceMonitor = new FaceMonitor({
  metadata: CusMetadata
})

:factory: FaceMonitor 类提供的方法

getSnapshotData

获取快照
以 Promise 风格 调用：支持

• 参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :---------- | :----- | :----- | :--- | :--------------------------------------------- | | livePushCtx | object | - | 是 | 推流组件实例 | | quality | string | raw | 否 | 图片的质量，默认原图。有效值为 raw、compressed |

• 返回值

Object res

| 属性 | 类型 | 说明 | | :------------ | :----- | :----------------- | | tempImagePath | string | 图片文件的临时路径 | | width | string | 图片的宽度 | | height | string | 图片的高度 |

• 使用示例

const livePushCtx = wx.createLivePusherContext('pusher')
const res = await this.FaceMonitor.getSnapshotData(livePushCtx, 'raw、compressed')

getImageData

获取图片像素点数据
以 Promise 风格 调用：支持

• 参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :------------ | :----- | :----- | :--- | :----------------- | | width | number | - | 是 | 图片的宽度 | | height | number | - | 是 | 图片的高度 | | tempImagePath | string | - | 是 | 图片文件的临时路径 |

• 返回值

| 属性 | 类型 | 说明 | | :------------ | :---------------- | :---------------------------------------------------- | | tempImagePath | string | 图片文件的临时路径 | | width | number | 图像数据矩形的宽度 | | height | number | 图像数据矩形的高度 | | data | Uint8ClampedArray | 图像像素点数据，一维数组，每四项表示一个像素点的 rgba |

• 使用示例

const res = await this.FaceMonitor.getImageData({
  width,
  height,
  tempImagePath
})

faceAnalyse

人脸分析
以 Promise 风格 调用：支持

• 参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :------------ | :------- | :----- | :--- | :----------------- | | width | number | - | 是 | 图片的宽度 | | height | number | - | 是 | 图片的高度 | | tempImagePath | string | - | 是 | 图片文件的临时路径 | | data | string | - | 是 | 图片文件的临时路径 | | fn | function | - | 否 | 自定义分析处理方法 |

• 默认返回值

Object res

| 属性 | 类型 | 说明 | | :------------ | :----- | :------------------ | | tempImagePath | string | 图片文件的临时路径 | | status | string | 人脸状态 | | toastType | string | 提示类型 | | res | Object | faceDetect 原始数据 |

• 自定义分析时返回值

Object res

| 属性 | 类型 | 说明 | | :------------ | :----- | :------------------ | | tempImagePath | string | 图片文件的临时路径 | | res | Object | faceDetect 原始数据 |

• 使用示例

const imageData = {} // imageData对象
// 自由组合api，对人脸识别结果进行自定义分析时使用
this.FaceMonitor.faceAnalyse(imageData, (res) => {
  console.log(res)
})

// 默认返回

const res = await this.FaceMonitor.faceAnalyse(imageData)
console.log(res)

commonUpload

wx.uploadFile 图片上传
以 Promise 风格 调用：支持

• 参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :------- | :----- | :------------------------------------- | :--- | :---------------------------------------------------------------------------- | | url | string | - | 是 | 开发者服务器地址 | | filePath | string | - | 是 | 要上传文件资源的路径 (本地路径) | | name | string | file | 否 | 默认 file 文件对应的 key，开发者在服务端可以通过这个 key 获取文件的二进制内容 | | formData | object | - | 否 | HTTP 请求中其他额外的 form data | | header | object | new FaceMonitor 时传入的 requestHeader | 否 | HTTP 请求 Header，Header 中不能设置 Referer |

• 返回值

Object res

| 属性 | 类型 | 说明 | | :--- | :----- | :------------------- | | url | string | 上传后获取的图片地址 |

• 使用示例

const res = await this.FaceMonitor.commonUpload({
  url,
  filePath
})
console.log(res.url)

request

wx.request 接口请求，支持失败重试
以 Promise 风格 调用：支持

• 参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :--------- | :----- | :------------------------------------- | :--- | :------------------------------------------ | | url | string | - | 是 | 接口完整路径包括域名 | | method | string | post | 否 | 请求方式 | | data | object | - | 否 | 请求参数 | | timeout | number | 5000 | 否 | 超时时间及失败重试时间间隔 | | retryTimes | number | 2 | 否 | 失败重试次数 | | header | object | new FaceMonitor 时传入的 requestHeader | 否 | HTTP 请求 Header，Header 中不能设置 Referer |

• 返回值

Object res

| 属性 | 类型 | 说明 | | :--- | :----- | :--------------- | | res | object | 服务端返回的数据 |

• 使用示例

const res = await this.FaceMonitor.request({
  url,
  data: {
    photo,
    offset,
    scene,
    info: metadata?.info || '',
    metadata
  }
})
console.log(res)

start

推流组件人脸监控开始

• 参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :-------------------- | :------- | :----- | :--- | :----------------------------------------------------------- | | FaceMonitorStartParam | object | - | 是 | 推流开始参数 | | fn | function | - | 否 | 如果传入参数，使用方可对微信官方返回的人脸结果进行自定义处理 |

• FaceMonitorStartParam

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :---------- | :----- | :--------- | :--- | :--------------------------------------------- | --------------------------------------- | | livePushCtx | object | - | 是 | 推流组件实例 | | quality | string | compressed | 否 | 图片的质量，默认原图。有效值为 raw、compressed | | monitorType | string | monitor | 否 | 检测类型 有效值为 monitor: 实时检测 | predict: 预检，检测设备是否支持人脸识别 |

• 使用示例

const livePushCtx = wx.createLivePusherContext('pusher')
// 预检
this.FaceMonitor.start({ livePushCtx, monitorType: 'predict' })

// 实时检测
this.FaceMonitor.start({ livePushCtx })

// 自定义分析人脸结果
this.FaceMonitor.start({ livePushCtx }, (res) => {
  console.log(res)
})

stop

推流组件人脸监控结束

• 参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :---------- | :----- | :----- | :--- | :----------- | | livePushCtx | object | - | 是 | 推流组件实例 |

reportPhoto

上报图片
以 Promise 风格 调用：支持

• 参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | :------- | :----- | :----------- | :--- | :---------------------------------------------------- | | url | string | - | 是 | 上报的服务的 url | | photo | string | - | 是 | upload 后获取的图片线上地址 | | scene | number | 1 | 是 | 1、第一次进入 2、离开再进入 3、一变二， 4、没有人脸时 | | offset | number | 0 | 是 | 视频偏移量：图片所在视频的位置 | | metadata | object | { info: '' } | 是 | 业务的自定义数据 |

• 使用示例

const reportUrl = `${CONFIG.API_BASE_URL}/cheatDetection/${cheatKey}/reportPhoto`

this.reportPhoto({
  url: reportUrl,
  photo,
  scene,
  offset,
  metadata
})

:gem: MonitorRules 内置检测规则

// 人脸检测状态
export const FaceType = {
  NoFace: 'noFace',
  SingleFace: 'singleFace',
  MultiFace: 'multiFace',
  MaskFace: 'maskFace',
  FaceCenter: 'faceCenter'
}
// toast提示
export const ToastType = {
  noFace: '请保持人脸在画面中',
  multiFace: '检测到多人入镜',
  mouth: '请勿遮挡嘴巴',
  faceCenter: '请正对摄像头'
}

export const DefaultMonitorRules = [checkNoFace, checkMultiFace, checkMaskMouth]

:package: 使用示例

import { FaceMonitor, MonitorRules } from '../../common/aiService/FaceMonitor'

// 初始化
this.FaceMonitor = new FaceMonitor({
  metadata: {
    stepToken,
    mediaName: streamName,
    info: patternName,
    cheatKey: token
  },
  config: {
    needPredict: false
  },
  requestHeader: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
    'X-Avocado-Source': 'miniprogram',
    Authorization: 'Basic ' + wx.getStorageSync('authToken'),
    'X-Avocado-Version': CONFIG.VERSION,
    'X-Position-Token': curSessionToken,
    'X-Wx-Appid': appId
  }
})

// 开始检测
this.FaceMonitor.start({ livePushCtx: this.ctx })

// 结束
this.FaceMonitor.stop(this.ctx)

// 身份验证流程只进行图片上报
const reportUrl = `${CONFIG.API_BASE_URL}/cheatDetection/${cheatKey}/reportPhoto`
this.FaceMonitor.reportPhoto({
  url: reportUrl,
  photo,
  scene,
  offset,
  metadata
})

// 内置规则，对人脸分析结果进行自定义处理时使用

const { DefaultMonitorRules, FaceType, ToastType, checkNoFace, checkMultiFace, checkMaskMouth, checkFaceCenter } = MonitorRules

:link: 相关文档

1. LivePusherContext
2. snapshot
3. imageData 对象
4. faceDetect
5. OffscreenCanvas