BaseFaceApi (faceapi-码云(gitee.com))

java.lang.Object
- net.gdface.sdk.BaseFaceApi

All Implemented Interfaces:

FaceApi

Direct Known Subclasses:

BaseFaceApiLocal
```
public abstract class BaseFaceApi
extends java.lang.Object
implements FaceApi
```
FaceApi抽象实现,SDK接口类必须从此类派生

Author:

guyadong

Constructor Summary

Constructors
Modifier Constructor and Description

protected BaseFaceApi()

Constructors
Modifier	Constructor and Description
`protected`	`BaseFaceApi()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`double`	`compare2Face(byte[] imgData1, CodeInfo facePos1, byte[] imgData2, CodeInfo facePos2)` 对人脸图像提取特征码，返回比较相似度结果 imgData1和imgData2相等或imgData2为`null`时,即比较同一张图像中的两张人脸的相似度调用该方法时假设图像(`imgData1`和`imgData2`)能正常解码, 所以当对图像解码出现异常时，将`ImageErrorException`异常对象封装到`RuntimeException`抛出任何参数为`null`则抛出`IllegalArgumentException`
`double[]`	`compareCodes(byte[] code1, CodeInfo[] codes)` 特征码比对1:N 返回对应的特征码相似度数组
`CompareResult`	`compareFaces(byte[] code, byte[] imgData, int faceNum)` 特征码比对1:N 对`imgData`图像数据检测人脸并提取特征，然后与`code`特征进行比对, 返回包含比对相似度结果的`CompareResult`实例
`java.util.List<java.lang.Double>`	`compareFeatures(byte[] code1, java.util.List<byte[]> codes)` 特征码比对1:N
`double`	`detectAndCompare2Face(byte[] imgData1, FRect detectRect1, byte[] imgData2, FRect detectRect2)` 对两个图像指定范围(`FRect`)进行人脸检测,找到并提取唯一的人脸特征码,然后比较相似度,返回相似度结果 imgData1和imgData2相等或imgData2为`null`时, 即比较同一张图像中的两张人脸的相似度,这种情况下detectRect1和detectRect2都不能为`null` imgData1和imgData2不相等且都不为`null`时,detectRect1和detectRect2被忽略
`CodeInfo`	`detectCenterFace(byte[] imgData)` 检测最中心的人脸返回人脸位置数据对象`CodeInfo`
`CodeInfo`	`detectMaxFace(byte[] imgData)` 检测最大的人脸返回人脸位置数据对象`CodeInfo`
`protected CodeInfo`	`findMaxFace(CodeInfo[] facePos)`
`byte[]`	`getFeature(java.util.Map<java.nio.ByteBuffer,CodeInfo> faces)` 多张人脸提取特征(用于多张人脸合成一个特征的算法) 返回人脸特征数据 `#multiFaceFeature()`返回`false`时代表此方法未被实现，执行会抛出异常
`static FeatureSe`	`getFeatureSeInstance(FaceApi faceapi)` 从`FaceApi`实例获取内存搜索引擎接口实例如果`FaceApi`不是`BaseFaceApiLocal`实例返回`null`
`protected abstract net.gdface.image.MatType`	`getNativeMatrixType()` 返回用于图像检测和建模的图像矩阵的(色彩空间)类型不可返回`null`
`boolean`	`hasFace(byte[] imgData)` 判断图像是否能提取到人脸特征码为`true`则能检测到人脸并能提取特征码
`protected net.gdface.image.BaseLazyImage`	`makeOpenedLazyImage(byte[] imgData)` 通过图像数据字节流(byte[])创建FaceImage对象调用`BaseLazyImage.setAutoClose(boolean)`设置 autClose为`false` 如果有特殊要求，子类可以重写此方法
`CodeInfo`	`matDetectMaxFace(net.gdface.image.MatType matType, byte[] matData, int width, int height)` 检测最大的人脸返回人脸位置数据对象`CodeInfo`
`boolean`	`matHasFace(net.gdface.image.MatType matType, byte[] matData, int width, int height)` 判断图像矩阵是否能提取到人脸特征码返回为`true`则能检测到人脸并能提取特征码
`FseResult[]`	`matSearchFaces(net.gdface.image.MatType matType, byte[] matData, int width, int height, CodeInfo facePos, double similarty, int rows)` 1:N 人脸图像搜索对`facePos`指定的人脸位置提取特征码,然后在数据库中搜索相似的人脸返回搜索结果。返回包含相似度计算结果的FseResult数组相似度值通过 FseResult.getSimilartys() 获取对应的人脸特征ID由 FseResult.getFeatureIds()获取
`FseResult[]`	`searchFaces(byte[] imgData, CodeInfo facePos, double similarty, int rows)` 1:N 人脸图像搜索对`facePos`指定的人脸位置提取特征码,然后在数据库中搜索相似的人脸返回搜索结果。返回包含相似度计算结果的FseResult数组相似度值通过 FseResult.getSimilartys() 获取对应的人脸特征ID由 FseResult.getFeatureIds()获取
`protected abstract byte[]`	`toNativeMatrix(net.gdface.image.MatType matType, byte[] matData, int width, int height)` 将指定的图像矩阵转为图像检测和建模的图像矩阵的(色彩空间)类型(参见 `getNativeMatrixType()`)

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.gdface.sdk.FaceApi
compareCode, detectAndGetCodeInfo, detectFace, getCodeInfo, getCodeInfo, isLocal, matDetectAndGetCodeInfo, matDetectFace, matGetCodeInfo, matGetCodeInfo, matWearMask, sdkCapacity, searchFeatures, wearMask

- Constructor Detail
  - BaseFaceApi
```
protected BaseFaceApi()
```
- Method Detail
  - compare2Face
```
public double compare2Face(byte[] imgData1,
                           CodeInfo facePos1,
                           byte[] imgData2,
                           CodeInfo facePos2)
                    throws NotFaceDetectedException
```
    Description copied from interface: FaceApi
    
    对人脸图像提取特征码，返回比较相似度结果
    imgData1和imgData2相等或imgData2为null时,即比较同一张图像中的两张人脸的相似度调用该方法时假设图像(imgData1和imgData2)能正常解码,
    所以当对图像解码出现异常时，将ImageErrorException异常对象封装到RuntimeException抛出
    任何参数为null则抛出IllegalArgumentException
    
    Specified by:
    
    compare2Face in interface FaceApi
    
    Parameters:
    
    imgData1 - 图像1数据(jpg,png...)字节数组
    
    facePos1 - 检测到的人脸/眼睛位置
    
    imgData2 - 图像1数据(jpg,png...)字节数组
    
    facePos2 - 检测到的人脸/眼睛位置
    
    Returns:
    
    两张人脸之间的相似度(0.0~1)
    
    Throws:
    
    NotFaceDetectedException
    
    See Also:
    
    FaceApi.getCodeInfo(byte[], int, CodeInfo[]), FaceApi.compareCode(byte[], byte[])
  - compareFaces
```
public CompareResult compareFaces(byte[] code,
                                  byte[] imgData,
                                  int faceNum)
                           throws NotFaceDetectedException,
                                  net.gdface.image.ImageErrorException
```
    Description copied from interface: FaceApi
    
    特征码比对1:N
    对imgData图像数据检测人脸并提取特征，然后与code特征进行比对, 返回包含比对相似度结果的CompareResult实例
    
    Specified by:
    
    compareFaces in interface FaceApi
    
    Parameters:
    
    code - 人脸特征数据
    
    imgData - 待比对的图像(jpg,png...)(可能有多张人脸)
    
    faceNum - 参见 FaceApi.getCodeInfo(byte[], int, CodeInfo[])
    
    Returns:
    
    CompareResult实例
    
    Throws:
    
    NotFaceDetectedException - 没有检测到人脸
    
    net.gdface.image.ImageErrorException
    
    See Also:
    
    FaceApi.compareCodes(byte[], CodeInfo[]), FaceApi.detectAndGetCodeInfo(byte[], int)
  - detectAndCompare2Face
```
public double detectAndCompare2Face(byte[] imgData1,
                                    FRect detectRect1,
                                    byte[] imgData2,
                                    FRect detectRect2)
                             throws net.gdface.image.ImageErrorException,
                                    NotFaceDetectedException
```
    Description copied from interface: FaceApi
    
    对两个图像指定范围(FRect)进行人脸检测,找到并提取唯一的人脸特征码,然后比较相似度,返回相似度结果
    imgData1和imgData2相等或imgData2为null时, 即比较同一张图像中的两张人脸的相似度,这种情况下detectRect1和detectRect2都不能为null
    imgData1和imgData2不相等且都不为null时,detectRect1和detectRect2被忽略
    
    Specified by:
    
    detectAndCompare2Face in interface FaceApi
    
    Parameters:
    
    imgData1 - 图像1数据(jpg,png...)字节数组,为null则抛出IllegalArgumentException
    
    detectRect1 - 图片检测范围，为null时全图检测
    
    imgData2 - 图像2数据(jpg,png...)字节数组
    
    detectRect2 - 图片检测范围，为null时全图检测
    
    Returns:
    
    两张人脸之间的相似度(0.0~1)
    
    Throws:
    
    net.gdface.image.ImageErrorException
    
    NotFaceDetectedException
    
    See Also:
    
    FaceApi.detectAndGetCodeInfo(byte[], int), FaceApi.compareCode(byte[], byte[])
  - compareFeatures
```
public java.util.List<java.lang.Double> compareFeatures(byte[] code1,
                                                        java.util.List<byte[]> codes)
```
    Description copied from interface: FaceApi
    
    特征码比对1:N
    
    Specified by:
    
    compareFeatures in interface FaceApi
    
    Parameters:
    
    code1 - 人脸特征数据
    
    codes - 一组人脸特征
    
    Returns:
    
    返回对应的特征码相似度列表
  - compareCodes
```
public double[] compareCodes(byte[] code1,
                             CodeInfo[] codes)
```
    Description copied from interface: FaceApi
    
    特征码比对1:N
    返回对应的特征码相似度数组
    
    Specified by:
    
    compareCodes in interface FaceApi
    
    Parameters:
    
    code1 - 待比对的特征码
    
    codes - 包含人脸特征的CodeInfo数组
    
    Returns:
    
    特征码相似度数组
  - makeOpenedLazyImage
```
protected net.gdface.image.BaseLazyImage makeOpenedLazyImage(byte[] imgData)
                                                      throws net.gdface.image.UnsupportedFormatException,
                                                             net.gdface.image.NotImageException
```
    通过图像数据字节流(byte[])创建FaceImage对象
    调用BaseLazyImage.setAutoClose(boolean)设置 autClose为false
    如果有特殊要求，子类可以重写此方法
    
    Parameters:
    
    imgData -
    
    Returns:
    
    Throws:
    
    net.gdface.image.UnsupportedFormatException
    
    net.gdface.image.NotImageException
    
    See Also:
    
    BaseLazyImage.open(), BaseLazyImage.setAutoClose(boolean)
  - detectCenterFace
```
public CodeInfo detectCenterFace(byte[] imgData)
                          throws NotFaceDetectedException,
                                 net.gdface.image.ImageErrorException
```
    Description copied from interface: FaceApi
    
    检测最中心的人脸
    返回人脸位置数据对象CodeInfo
    
    Specified by:
    
    detectCenterFace in interface FaceApi
    
    Parameters:
    
    imgData - 图像数据(jpg,png...)字节数组,为null则抛出IllegalArgumentException
    
    Returns:
    
    CodeInfo
    
    Throws:
    
    NotFaceDetectedException
    
    net.gdface.image.ImageErrorException
  - findMaxFace
```
protected CodeInfo findMaxFace(CodeInfo[] facePos)
```
  - detectMaxFace
```
public CodeInfo detectMaxFace(byte[] imgData)
                       throws NotFaceDetectedException,
                              net.gdface.image.ImageErrorException
```
    Description copied from interface: FaceApi
    
    检测最大的人脸
    返回人脸位置数据对象CodeInfo
    
    Specified by:
    
    detectMaxFace in interface FaceApi
    
    Parameters:
    
    imgData - 图像数据(jpg,png...)字节数组,为null则抛出IllegalArgumentException
    
    Returns:
    
    CodeInfo
    
    Throws:
    
    NotFaceDetectedException
    
    net.gdface.image.ImageErrorException
  - hasFace
```
public boolean hasFace(byte[] imgData)
                throws net.gdface.image.ImageErrorException
```
    Description copied from interface: FaceApi
    
    判断图像是否能提取到人脸特征码
    为true则能检测到人脸并能提取特征码
    
    Specified by:
    
    hasFace in interface FaceApi
    
    Parameters:
    
    imgData - 图像数据(jpg,png...)字节数组,为null则抛出IllegalArgumentException
    
    Returns:
    
    为true则能检测到人脸并能提取特征码
    
    Throws:
    
    net.gdface.image.ImageErrorException
    
    See Also:
    
    FaceApi.detectAndGetCodeInfo(byte[], int)
  - matHasFace
```
public boolean matHasFace(net.gdface.image.MatType matType,
                          byte[] matData,
                          int width,
                          int height)
```
    Description copied from interface: FaceApi
    
    判断图像矩阵是否能提取到人脸特征码
    返回为true则能检测到人脸并能提取特征码
    
    Specified by:
    
    matHasFace in interface FaceApi
    
    Parameters:
    
    matType - 图像矩阵类型
    
    matData - 图像矩阵,为null则抛出IllegalArgumentException
    
    width - 图像宽度
    
    height - 图像高度
    
    Returns:
    
    为true则能检测到人脸并能提取特征码
  - matDetectMaxFace
```
public CodeInfo matDetectMaxFace(net.gdface.image.MatType matType,
                                 byte[] matData,
                                 int width,
                                 int height)
                          throws NotFaceDetectedException
```
    Description copied from interface: FaceApi
    
    检测最大的人脸
    返回人脸位置数据对象CodeInfo
    
    Specified by:
    
    matDetectMaxFace in interface FaceApi
    
    Returns:
    
    CodeInfo
    
    Throws:
    
    NotFaceDetectedException
  - getFeature
```
public byte[] getFeature(java.util.Map<java.nio.ByteBuffer,CodeInfo> faces)
                  throws NotFaceDetectedException
```
    Description copied from interface: FaceApi
    
    多张人脸提取特征(用于多张人脸合成一个特征的算法)
    返回人脸特征数据 #multiFaceFeature()返回false时代表此方法未被实现，执行会抛出异常
    
    Specified by:
    
    getFeature in interface FaceApi
    
    Parameters:
    
    faces - 人脸图像数据(jpg,png...)与人脸位置信息对象的映射
    
    Returns:
    
    人脸特征数据
    
    Throws:
    
    NotFaceDetectedException
  - searchFaces
```
public FseResult[] searchFaces(byte[] imgData,
                               CodeInfo facePos,
                               double similarty,
                               int rows)
                        throws NotFaceDetectedException,
                               net.gdface.image.ImageErrorException
```
    Description copied from interface: FaceApi
    
    1:N 人脸图像搜索
    对facePos指定的人脸位置提取特征码,然后在数据库中搜索相似的人脸返回搜索结果。
    返回包含相似度计算结果的FseResult数组
    相似度值通过 FseResult.getSimilartys() 获取
    对应的人脸特征ID由 FseResult.getFeatureIds()获取
    
    Specified by:
    
    searchFaces in interface FaceApi
    
    Parameters:
    
    imgData - 图片字节数组
    
    facePos - 人脸位置对象
    为null时,先做人脸检测再提取特征码
    不为null时,直接在指定的位置提取特征码
    
    similarty - 相似度阀值
    
    rows - 最多返回的记录数目
    
    Returns:
    
    包含相似度计算结果的FseResult数组
    
    Throws:
    
    NotFaceDetectedException - -
    
    net.gdface.image.ImageErrorException - -
    
    See Also:
    
    FaceApi.getCodeInfo(byte[], int, CodeInfo[]), FaceApi.searchFeatures(byte[], double, int)
  - matSearchFaces
```
public FseResult[] matSearchFaces(net.gdface.image.MatType matType,
                                  byte[] matData,
                                  int width,
                                  int height,
                                  CodeInfo facePos,
                                  double similarty,
                                  int rows)
                           throws NotFaceDetectedException,
                                  net.gdface.image.ImageErrorException
```
    Description copied from interface: FaceApi
    
    1:N 人脸图像搜索
    对facePos指定的人脸位置提取特征码,然后在数据库中搜索相似的人脸返回搜索结果。
    返回包含相似度计算结果的FseResult数组
    相似度值通过 FseResult.getSimilartys() 获取
    对应的人脸特征ID由 FseResult.getFeatureIds()获取
    
    Specified by:
    
    matSearchFaces in interface FaceApi
    
    Parameters:
    
    matType - 图像矩阵类型
    
    matData - 图像矩阵
    
    width - 图像宽度
    
    facePos - 人脸位置对象
    为null时,先做人脸检测再提取特征码
    不为null时,直接在指定的位置提取特征码
    
    similarty - 相似度阀值
    
    rows - 最多返回的记录数目
    
    Returns:
    
    包含相似度计算结果的FseResult数组
    
    Throws:
    
    NotFaceDetectedException - -
    
    net.gdface.image.ImageErrorException - -
    
    See Also:
    
    FaceApi.getCodeInfo(byte[], int, CodeInfo[]), FaceApi.searchFeatures(byte[], double, int)
  - getNativeMatrixType
```
protected abstract net.gdface.image.MatType getNativeMatrixType()
```
    返回用于图像检测和建模的图像矩阵的(色彩空间)类型
    不可返回null
    
    Returns:
    
    矩阵类型
  - toNativeMatrix
```
protected abstract byte[] toNativeMatrix(net.gdface.image.MatType matType,
                                         byte[] matData,
                                         int width,
                                         int height)
```
    将指定的图像矩阵转为图像检测和建模的图像矩阵的(色彩空间)类型(参见 getNativeMatrixType())
    
    Parameters:
    
    matType - 输入矩阵类型
    
    matData - 矩阵数据
    
    width - 矩阵宽度
    
    height - 矩阵高度
    
    Returns:
    
    转换后的矩阵数据
  - getFeatureSeInstance
```
public static final FeatureSe getFeatureSeInstance(FaceApi faceapi)
```
    从FaceApi实例获取内存搜索引擎接口实例
    如果FaceApi不是BaseFaceApiLocal实例返回null
    
    Parameters:
    
    faceapi -
    
    Returns:

Class BaseFaceApi

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface net.gdface.sdk.FaceApi

Constructor Detail

BaseFaceApi

Method Detail

compare2Face

compareFaces

detectAndCompare2Face

compareFeatures

compareCodes

makeOpenedLazyImage

detectCenterFace

findMaxFace

detectMaxFace

hasFace

matHasFace

matDetectMaxFace

getFeature

searchFaces

matSearchFaces

getNativeMatrixType

toNativeMatrix

getFeatureSeInstance