235 lines
6.6 KiB
Markdown
235 lines
6.6 KiB
Markdown
# x-facedetection
|
|
|
|
## 特性说明
|
|
|
|
1. 检测提供的图片是否有人脸信息
|
|
2. 从相册中选取检测人脸信息
|
|
3. 通过相机实时捕捉人脸信息(并通过姿势姿态检测当前活体)
|
|
4. ios端后续提供,仅支持图片人脸信息检测
|
|
|
|
## 兼容性
|
|
|
|
| Harmony | IOS | Android | WEB | 小程序 |
|
|
| --- | --- | --- | --- | --- |
|
|
| 支持 | - | 支持 | x | x |
|
|
|
|
## 安装方式
|
|
|
|
通过HBuilderX导入插件，或在插件市场下载后导入项目。
|
|
|
|
## API接口说明
|
|
|
|
### 检测图片中的人脸
|
|
|
|
```ts
|
|
// 通过相册选择图片检测人脸,仅支持安卓,ios,鸿蒙
|
|
checkFaceByImage(config: XFACE_CHECK_OPTS)
|
|
|
|
// 通过提供的图片路径检测人脸,仅支持安卓,ios,鸿蒙
|
|
checkFaceByImageFromFilePath(config: XFACE_CHECK_OPTS)
|
|
```
|
|
|
|
### 通过相机进行人脸活体检测
|
|
|
|
```ts
|
|
// 检查相机权限，仅安卓
|
|
checkCamraPermissions(call: (istrue: boolean) => void)
|
|
|
|
// 打开相机进行人脸活体检测，仅安卓
|
|
checkFaceByCamra(config: XFACE_CHECK_OPTS)
|
|
```
|
|
|
|
## 参数类型说明
|
|
|
|
### XFACE_CHECK_OPTS
|
|
|
|
```ts
|
|
type XFACE_CHECK_OPTS = {
|
|
// 如果是通过图片检测需要提供图片路径
|
|
url?: string,
|
|
// 如果是通过图片buffer解析需要提供(暂无法使用)
|
|
buffer?: ArrayBuffer,
|
|
// 如果是通过相机动态绑定嵌入式页面时,需要提供页面view的id
|
|
viewId?: string,
|
|
/**
|
|
* 活体检测指令，通过相机视频检测
|
|
* 如果提供指令数组时,会根据完整指令顺序检测直到验证通过.
|
|
* 如果视频检测时,指令为空数组则只检测整个五官是不是在画面中,一旦检测到人脸立即验证通过.
|
|
*/
|
|
instruction?: XFACE_INS[]
|
|
// 验证结束并通过时返回
|
|
success?: (data: XFACE_EVENT_CHECK_SUCCESS) => void,
|
|
/**
|
|
* 在视频活体检测时，返回每一帧的检测详细检测过程的信息，此事件是持续触发，直到结束。
|
|
* 在图片检测的时候，只返回一次。
|
|
*/
|
|
enter?: (data: XFACE_EVENT_SUCCESS[], maps: string) => void,
|
|
/**
|
|
* 开始检测，正在开始检测的指令。类似：向左转一次，向右转一次，点点头，张张嘴等执行时触发，
|
|
* 方便用户自定自己的提示语或者语音播报
|
|
* 'start'，现在开始，
|
|
* 'ins_start_指令名称'：某个指令开始，如：ins_start_left,ins_start_right
|
|
* 'ins_end_指令名称'：某个指令结束，如：ins_end_left,ins_end_right
|
|
* 'end'结束所有指令
|
|
*/
|
|
insTipsEvent?: (data: string) => void,
|
|
fail?: (error: string) => void,
|
|
}
|
|
```
|
|
|
|
### 活体检测指令类型
|
|
|
|
```ts
|
|
/**
|
|
* 活体检测指令，可以通过指令控制检测动作
|
|
* left: 向左转一次
|
|
* right: 向右转一次
|
|
* downUp: 上下点头
|
|
* eyeOplenClose: 眨眼
|
|
* monthOpenClose: 张张嘴
|
|
*/
|
|
type XFACE_INS = "left" | "right" | "downUp" | "eyeOplenClose" | "monthOpenClose"
|
|
```
|
|
|
|
### 检测结果类型
|
|
|
|
```ts
|
|
type XFACE_EVENT_SUCCESS = {
|
|
// 右眼眨眼睛的闭合数据
|
|
rightEye: XFACE_TEST_EYE_TYPE,
|
|
// 左眼眨眼睛的闭合数据
|
|
leftEye: XFACE_TEST_EYE_TYPE,
|
|
// 是否在微笑
|
|
isSmile: boolean,
|
|
// 脸向左,向右,中间
|
|
faceRightLeft: XFACE_FACE_Direction,
|
|
// 点头的方向
|
|
faceUpDown: XFACE_FACE_Direction,
|
|
imgWidth: number,
|
|
imgHeight: number,
|
|
// 嘴巴是不是张开
|
|
isMouthOpened: boolean,
|
|
// 整个脑袋是否在画面中
|
|
allHeadBody: boolean,
|
|
// 人脸ID，用于追踪同一个人脸
|
|
faceId: number | null
|
|
}
|
|
|
|
type XFACE_EVENT_CHECK_SUCCESS = {
|
|
/**
|
|
* 验证结束保存的视频地址，方便上传保存到后台储存备份，抽查验证。
|
|
* 仅在活体检测时返回，图片检测时为空字符串。
|
|
*/
|
|
videoPath: string
|
|
/**
|
|
* 在活体检测过程中,会按照指令顺序进行截图,保存验证时人脸对应的动画图片。
|
|
* 多少个指令就有多少张图片。最后一张为全脸捕捉画面。
|
|
* 图片检测时，返回检测的图片路径。
|
|
*/
|
|
images: string[],
|
|
/**
|
|
* 验证是否通过
|
|
*/
|
|
isPass: boolean
|
|
}
|
|
```
|
|
|
|
## 使用示例
|
|
|
|
### 图片人脸检测
|
|
|
|
仅安卓，鸿蒙 Next,ios 支持
|
|
|
|
```ts
|
|
import { checkFaceByImage, checkFaceByImageFromFilePath } from '@/uni_modules/x-facedetection'
|
|
|
|
// 从相册选择图片检测人脸
|
|
checkFaceByImage({
|
|
success: (res) => {
|
|
console.log('检测成功', res.isPass)
|
|
console.log('图片路径', res.images)
|
|
},
|
|
fail: (err) => {
|
|
console.error('检测失败', err)
|
|
},
|
|
enter: (data, maps) => {
|
|
console.log('人脸信息', data)
|
|
}
|
|
})
|
|
|
|
// 通过图片路径检测人脸
|
|
checkFaceByImageFromFilePath({
|
|
url: '图片路径',
|
|
success: (res) => {
|
|
console.log('检测成功', res.isPass)
|
|
console.log('图片路径', res.images)
|
|
},
|
|
fail: (err) => {
|
|
console.error('检测失败', err)
|
|
},
|
|
enter: (data, maps) => {
|
|
console.log('人脸信息', data)
|
|
}
|
|
})
|
|
```
|
|
|
|
### 相机活体检测
|
|
|
|
仅安卓
|
|
|
|
```ts
|
|
import { checkCamraPermissions, checkFaceByCamra } from '@/uni_modules/x-facedetection/utssdk/app-android/index.uts'
|
|
|
|
// 检查相机权限
|
|
checkCamraPermissions((hasPermission) => {
|
|
if (hasPermission) {
|
|
// 有权限，开始活体检测
|
|
startFaceDetection()
|
|
} else {
|
|
console.error('没有相机权限')
|
|
}
|
|
})
|
|
|
|
// 开始活体检测
|
|
function startFaceDetection() {
|
|
checkFaceByCamra({
|
|
viewId: 'camera-container', // 相机预览容器的ID
|
|
instruction: ['left', 'right', 'eyeOplenClose', 'monthOpenClose'], // 活体检测指令序列
|
|
insTipsEvent: (event) => {
|
|
// 处理指令提示事件
|
|
if (event === 'start') {
|
|
console.log('开始检测')
|
|
} else if (event.startsWith('ins_start_')) {
|
|
const action = event.replace('ins_start_', '')
|
|
console.log(`开始执行动作: ${action}`)
|
|
} else if (event.startsWith('ins_end_')) {
|
|
const action = event.replace('ins_end_', '')
|
|
console.log(`完成动作: ${action}`)
|
|
} else if (event === 'end') {
|
|
console.log('检测完成')
|
|
}
|
|
},
|
|
success: (res) => {
|
|
console.log('活体检测成功', res.isPass)
|
|
console.log('视频路径', res.videoPath)
|
|
console.log('检测过程图片', res.images)
|
|
},
|
|
fail: (err) => {
|
|
console.error('活体检测失败', err)
|
|
},
|
|
enter: (data, maps) => {
|
|
// 实时人脸检测数据
|
|
console.log('实时人脸数据', data)
|
|
}
|
|
})
|
|
}
|
|
```
|
|
|
|
## 注意事项
|
|
|
|
1. 活体检测需要用户保持面部在摄像头范围内，并按照指令完成相应动作
|
|
2. 检测过程中如果用户移出屏幕或光线变化太大，可能会导致检测失败
|
|
3. 为获得最佳效果，建议在光线充足的环境下使用
|
|
4. iOS和Android实现可能存在细微差异，请根据实际测试结果调整应用逻辑
|
|
5. 鸿蒙人脸检测效率由原生支持。
|