Face recognition system CompreFace .NET SDK

Github address: https://github.com/exadel-inc/compreface-net-sdk

CompreFace NET SDK makes face recognition in your application easier.

Table of contents

Require

Before using our SDK, please make sure CompreFace and .NET are installed on your computer.

1. CompreFace
2. .NET (Version 6+)

CompreFace Compatibility Matrix

CompreFace .NET SDK version	CompreFace 1.1.0
1.0.0	✔
1.0.1	✔
1.0.2	✔

explain:

• SDK supports all functions of CompreFace.
• SDK is available for this version of CompreFace.
  If CompreFace is newer - SDK will not support new features of CompreFace. If CompreFace version is old - new SDK functions will fail.
• There are major backward compatibility issues. It is not recommended to use these versions together

Install

Install the NuGet package using the SDK:

Install-Package CompreFace.NET.Sdk

usage

All examples below can be found in the repository inside the examples folder.
You can also take a look at the recognition sample application. This is a simple example of CompreFace usage.

initialization

To start using the Compreface .NET SDK, you need to compreface-sdkimport objects from dependencies CompreFace.

Then you need to create CompreFaceClientthe object and initialize it using DOMAINand . PORTBy default, if you are running CompreFace on your local machine, DOMAINit will be http://localhost, in this case PORTwill be 8000.
You can pass an optional optionsobject when calling the method to set default parameters, see more information .

You should use the services CompreFaceClientin the object RecognitionServiceto recognize faces.

However, before recognition, you need to first add the subject to the collection of faces. To do this, RecognitionServiceget the object with the help of Subject. Subjectcontained RecognitionServicein the class.

var client = new CompreFaceClient(
    domain: "http://localhost",
    port: "8000");

var recognitionService = client.GetCompreFaceService<RecognitionService>(recognition api key);

var subject = recognitionService.Subject;

var subjectRequest = new AddSubjectRequest()
{
    Subject = "Subject name"
};

var subjectResponse = await subject.AddAsync(subjectRequest);

Add face to face collection

Here's an example showing how to add an image from your filesystem to your face collection:

var faceCollection = recognitionService.FaceCollection;

var request = new AddSubjectExampleRequestByFilePath()
{
    DetProbThreShold = 0.81m,
    Subject = "Subject name",
    FilePath = "Full file path"
};

var response = await faceCollection.AddAsync(request);

identify

This code snippet shows how to recognize unknown faces.
Recognize faces from a given image

var recognizeRequest = new RecognizeFaceFromImageRequestByFilePath()
{
    FilePath = "Full file path",
    DetProbThreshold = 0.81m,
    FacePlugins = new List<string>()
    {
        "landmarks",
        "gender",
        "age",
        "detector",
        "calculator"
    },
    Limit = 0,
    PredictionCount = 1,
    Status = true
};

var recognizeResponse = await recognitionService.RecognizeFaceFromImage.RecognizeAsync(recognizeRequest);

reference

CompreFace global object

The CompreFace global object is used to initialize a connection to CompreFace and set default values ​​for options.
Each service method will use default values, if applicable.

Constructor:

CompreFaceClient(domain, port)

parameter	type	Is it necessary	note
domain	string	yes	CompreFace's domain name and protocol. For example:http://localhost
port	string	yes	Port of CompreFace. For example:8000

example:

var client = new CompreFaceClient(
    domain: "http://localhost",
    port: "8000");

Serve

1. client.GetCompreFaceService<RecognitionService>(apiKey)

Initialize the face recognition service object.

parameter	type	Is it necessary	explain
apiKey	string	yes	Face recognition API key in UUID format

example:

var apiKey = "00000000-0000-0000-0000-000000000002";

var recognitionService = client.GetCompreFaceService<RecognitionService>(apiKey);

2. client.GetCompreFaceService<FaceDetectionService>(apiKey)

Initialize the face detection service object.

parameter	type	Is it necessary	explain
apiKey	string	yes	Face recognition API key in UUID format

example:

var apiKey = "00000000-0000-0000-0000-000000000003";

var faceDetectionService = client.GetCompreFaceService<FaceDetectionService>(api_key);

3. client.GetCompreFaceService<FaceVerificationService>(apiKey)

Initialize the face verification service object.

parameter	type	Is it necessary	explain
apiKey	string	yes	Face recognition API key in UUID format

example:

var apiKey = "00000000-0000-0000-0000-000000000004";

var faceVerificationService = client.GetCompreFaceService<FaceVerificationService>(api_key);

optional attributes

All optional attributes are located in the "BaseFaceRequest" class.

public class BaseFaceRequest
{
    public int? Limit { get; set; }

    public decimal DetProbThreshold { get; set; }

    public IList<string> FacePlugins { get; set; }

    public bool Status { get; set; }
}

BaseFaceRequestClass is inherited by several DTO classes which are serialized into request format.

This is the description in the request body.

options	type	explain
it_prob_threshold	float	The recognized face is actually the minimum confidence required for the face. Value between 0.0 and 1.0
limit	integer	The maximum number of faces to recognize on an image. It identifies the largest faces first. A value of 0 means no limit. Default: 0
prediction_count	integer	Maximum number of topic predictions per face. It returns the most similar topics. Default: 1
face_plugins	string	Comma-separated face plugins. If empty, no additional information is returned. Learn more
status	boolean	If true contains system information such as execution_time and plugin_version fields. The default value is false

Object face recognition example:

var recognizeRequest = new RecognizeFaceFromImageRequestByFilePath()
{
    FilePath = "Full file path",
    DetProbThreshold = 0.81m,
    FacePlugins = new List<string>()
    {
        "landmarks",
        "gender",
        "age",
        "detector",
        "calculator"
    },
    Limit = 0,
    PredictionCount = 1,
    Status = true
};

var recognizeResponse = await recognitionService.RecognizeFaceFromImage.RecognizeAsync(recognizeRequest);

Face recognition service

The face recognition service is used for face recognition.
This means that you first need to upload known faces into a face collection, and then recognize unknown faces in it.
When you upload an unknown face, the service returns the face that is most similar to it.
In addition, the face recognition service also supports a verification endpoint to check that the person is correct in the face collection.
See the CompreFace page for more information .

face recognition

method:

Recognize Faces from a Given Image

Recognize all faces in an image.
The first parameter is the image location, it can be url, local path or bytes.

await recognitionService.RecognizeFaceFromImage.RecognizeAsync(recognizeRequest)

parameter	type	Is it necessary	explain
recognizeRequest	RecognizeFaceFromImageRequestByFilePath	yes

RecognizeFaceFromImageRequestByFilePathThis is the data transfer object serialized to JSON.

public class RecognizeFaceFromImageRequestByFilePath : BaseRecognizeFaceFromImageRequest
{
    public string FilePath { get; set; }
}

BaseRecognizeFaceFromImageRequestkind:

public class BaseRecognizeFaceFromImageRequest : BaseFaceRequest
{
    public int? PredictionCount { get; set; }
}

BaseFaceRequestThe class contains optional attributes:

public class BaseFaceRequest
{
    public int? Limit { get; set; }

    public decimal DetProbThreshold { get; set; }

    public IList<string> FacePlugins { get; set; } = new List<string>()

    public bool Status { get; set; }
}

options	type	explain
it_prob_threshold	float	The recognized face is actually the minimum confidence required for the face. Value between 0.0 and 1.0
limit	integer	The maximum number of faces to recognize on an image. It identifies the largest faces first. A value of 0 means no limit. Default: 0
prediction_count	integer	Maximum number of topic predictions per face. It returns the most similar topics. Default: 1
face_plugins	string	Comma-separated face plugins. If empty, no additional information is returned. Learn more
status	boolean	If true contains system information such as execution_time and plugin_version fields. The default value is false

ComreFace API response:

{
  "result" : [ {
    "age" : {
      "probability": 0.9308982491493225,
      "high": 32,
      "low": 25
    },
    "gender" : {
      "probability": 0.9898611307144165,
      "value": "female"
    },
    "mask" : {
      "probability": 0.9999470710754395,
      "value": "without_mask"
    },
    "embedding" : [ 9.424854069948196E-4, "...", -0.011415496468544006 ],
    "box" : {
      "probability" : 1.0,
      "x_max" : 1420,
      "y_max" : 1368,
      "x_min" : 548,
      "y_min" : 295
    },
    "landmarks" : [ [ 814, 713 ], [ 1104, 829 ], [ 832, 937 ], [ 704, 1030 ], [ 1017, 1133 ] ],
    "subjects" : [ {
      "similarity" : 0.97858,
      "subject" : "subject1"
    } ],
    "execution_time" : {
      "age" : 28.0,
      "gender" : 26.0,
      "detector" : 117.0,
      "calculator" : 45.0,
      "mask": 36.0
    }
  } ],
  "plugins_versions" : {
    "age" : "agegender.AgeDetector",
    "gender" : "agegender.GenderDetector",
    "detector" : "facenet.FaceDetector",
    "calculator" : "facenet.Calculator",
    "mask": "facemask.MaskDetector"
  }
}

element	type	describe
age	object	Detected age ranges. Only returned when the age plugin is enabled
gender	object	Gender detected. Only returned if the gender plugin is enabled
mask	object	Mask detected. Only returned if the mask plugin is enabled.
embedding	array	Face embedding. Only returned if the calculator plugin is enabled
box	object	A list of bounding box parameters for the face
probability	float	The probability that the found face is actually a human face
x_max, y_max, x_min, y_min	integer	Coordinates of the frame containing the face
landmarks	array	A list of coordinates for the frame containing the facial landmarks.
subjects	list	List of similar topics for <prediction_count> (ordered by similarity)
similarity	float	The image predicts the similarity of the person
subject	string	Subject name in face collection
execution_time	object	Execution time of all plugins
plugins_versions	object	Contains information about the plugin version

This JSON response is deserialized into RecognizeFaceFromImageResponsea Data Transfer Object (DTO).

public class RecognizeFaceFromImageResponse
{
    public IList<Result> Result { get; set; }

    public PluginVersions PluginsVersions { get; set; }
}

public class Result : BaseResult
{
    public IList<SimilarSubject> Subjects { get; set; }
} 

BaseResultkind:

public class BaseResult
{
    public Age Age { get; set; }

    public Gender Gender { get; set; }

    public Mask Mask { get; set; }

    public Box Box { get; set; }

    public IList<List<int>> Landmarks { get; set; }

    public ExecutionTime ExecutionTime { get; set; }

    public IList<decimal> Embedding { get; set; }
}

Verify faces in a given image

await recognitionService.RecognizeFaceFromImage.VerifyAsync(request);

Compares the similarity of the given image to the images in the faces collection.

parameter	type	Is it necessary
request	VerifyFacesFromImageRequest	Is it necessary

VerifyFacesFromImageRequestThis is the data transfer object serialized to JSON.

public class VerifyFacesFromImageRequest : BaseVerifyFacesFromImageRequest
{
    public string FilePath { get; set; }
}

BaseVerifyFacesFromImageRequestkind:

public class BaseVerifyFacesFromImageRequest : BaseFaceRequest
{
    public Guid ImageId { get; set; }
}

BaseFaceRequestThe class contains optional attributes:

public class BaseFaceRequest
{
    public int? Limit { get; set; }

    public decimal DetProbThreshold { get; set; }

    public IList<string> FacePlugins { get; set; }

    public bool Status { get; set; }
}

options	type	explain
it_prob_threshold	float	The recognized face is actually the minimum confidence required for the face. Value between 0.0 and 1.0
limit	integer	The maximum number of faces to recognize on an image. It identifies the largest faces first. A value of 0 means no limit. Default: 0
prediction_count	integer	Maximum number of topic predictions per face. It returns the most similar topics. Default: 1
face_plugins	string	以逗号分隔的面部插件。 如果为空，则不返回任何附加信息。Learn more
status	boolean	如果 true 包含系统信息，例如execution_time 和plugin_version 字段。 默认值为 false

回复：

{
    
    
  "result" : [ {
    
    
    "age" : {
    
    
      "probability": 0.9308982491493225,
      "high": 32,
      "low": 25
    },
    "gender" : {
    
    
      "probability": 0.9898611307144165,
      "value": "female"
    },
    "mask" : {
    
    
      "probability": 0.9999470710754395,
      "value": "without_mask"
    },
    "embedding" : [ 9.424854069948196E-4, "...", -0.011415496468544006 ],
    "box" : {
    
    
      "probability" : 1.0,
      "x_max" : 1420,
      "y_max" : 1368,
      "x_min" : 548,
      "y_min" : 295
    },
    "landmarks" : [ [ 814, 713 ], [ 1104, 829 ], [ 832, 937 ], [ 704, 1030 ], [ 1017, 1133 ] ],
    "subjects" : [ {
    
    
      "similarity" : 0.97858,
      "subject" : "subject1"
    } ],
    "execution_time" : {
    
    
      "age" : 28.0,
      "gender" : 26.0,
      "detector" : 117.0,
      "calculator" : 45.0,
      "mask": 36.0
    }
  } ],
  "plugins_versions" : {
    
    
    "age" : "agegender.AgeDetector",
    "gender" : "agegender.GenderDetector",
    "detector" : "facenet.FaceDetector",
    "calculator" : "facenet.Calculator",
    "mask": "facemask.MaskDetector"
  }
}

元素	类型	描述
age	object	检测到的年龄范围。 仅在启用 age 插件 时返回
gender	object	检测到性别。 仅在启用 性别插件 时返回
mask	object	检测到面具。 仅在启用面罩插件时返回。
embedding	array	人脸嵌入。 仅在启用 计算器插件 时返回
box	object	该人脸的边界框参数列表
probability	float	找到的人脸实际上是人脸的概率
x_max, y_max, x_min, y_min	integer	包含脸部的框架的坐标
landmarks	array	包含面部标志的框架的坐标列表。
subjects	list	<prediction_count> 的相似主题列表（按相似度排序）
similarity	float	该图像预测人的相似度
subject	string	人脸集合中的主体名称
execution_time	object	所有插件的执行时间
plugins_versions	object	包含有关插件版本的信息

此 JSON 响应被反序列化为VerifyFacesFromImageResponse数据传输对象 (DTO)。

public class VerifyFacesFromImageResponse
{
    public IList<Result> Result { get; set; }

    public PluginVersions PluginsVersions { get; set; }
}

public class Result : BaseResult
{
    public string Subject { get; set; }
    
    public decimal Similarity { get; set; }
}

BaseResult 类:

public class BaseResult
{
    public Age Age { get; set; }

    public Gender Gender { get; set; }

    public Mask Mask { get; set; }

    public Box Box { get; set; }

    public IList<List<int>> Landmarks { get; set; }

    public ExecutionTime ExecutionTime { get; set; }

    public IList<decimal> Embedding { get; set; }
}

ExecutionTime 类:

public class ExecutionTime
{
    public decimal Age { get; set; }

    public decimal Gender { get; set; }

    public decimal Detector { get; set; }

    public decimal Calculator { get; set; }

    public decimal Mask { get; set; }
}

获取人脸集合

recognitionService.FaceCollection

返回人脸集合对象

面部收集可用于管理已知面部，例如 添加、列出或删除它们。

人脸识别是针对人脸集合中保存的已知人脸进行的，因此在使用“识别”方法之前需要将至少一张人脸保存到人脸集合中。

有关面部收集和管理示例的更多信息此处

方法：

Add an Example of a Subject

注：这里的Subject被翻译成“主题”，但其实就是指：某个人。一个人，可以有一张或多张照片。

这将通过保存图像创建主题的示例。 您可以添加任意数量的图像来训练系统。 图像应该仅包含一张脸。

await recognitionService.FaceCollection.AddAsync(request);

参数	类型	是否	解释
request	AddSubjectExampleRequestByFilePath	是

AddSubjectExampleRequestByFilePath 这是序列化为 JSON 的数据传输对象。

public class AddSubjectExampleRequestByFilePath : BaseExampleRequest
{
    public string FilePath { get; set; }
}

BaseExampleRequest 类:

namespace Exadel.Compreface.DTOs.HelperDTOs.BaseDTOs
{
    public class BaseExampleRequest
    {
        public string Subject { get; set; }

        public decimal? DetProbThreShold { get; set; }
    }
}

选项	类型	解释
det_prob_threshold	float	所识别的面孔实际上是面孔所需的最低置信度。 值介于 0.0 和 1.0 之间

DetProbThreShold 是可选属性。

Response:

{
  "image_id": "6b135f5b-a365-4522-b1f1-4c9ac2dd0728",
  "subject": "SubjectName"
}

元素	类型	描述
image_id	UUID	UUID of uploaded image
subject	string	Subject of the saved image

此 JSON 响应被反序列化为AddSubjectExampleResponse数据传输对象 (DTO)。

public class AddSubjectExampleResponse
{
    public Guid ImageId { get; set; }

    public string Subject { get; set; }
}

主题的所有已保存示例的列表

要检索保存在面部集合中的主题列表：

await recognitionService.FaceCollection.ListAsync(request);

参数	类型	是否必须	解释
request	ListAllSubjectExamplesRequest	是

ListAllSubjectExamplesRequest 这是序列化为 JSON 的数据传输对象。

public class ListAllSubjectExamplesRequest
{
    public int? Page { get; set; }
    
    public int? Size { get; set; }
    
    public string Subject { get; set; }
}

参数	类型	是否必须	解释
Page	int	可选	要返回的示例的页码。 可用于分页。 默认值为0。从0.6版本开始。
Size	int	可选	页面上的面孔（页面大小）。 可用于分页。 默认值为 20。从 0.6 版本开始。
Subject	int	可选	端点应返回什么主题示例。 如果为空，则返回所有主题的示例。 从1.0版本开始

Response:

{
  "faces": [
    {
      "image_id": <image_id>,
      "subject": <subject>
    },
    ...
  ]
}

元素	类型	描述
image_id	UUID	人脸UUID
subject	string	为此 api 密钥保存其照片的人员的

此 JSON 响应被反序列化为ListAllSubjectExamplesResponse数据传输对象 (DTO)。

public class ListAllSubjectExamplesResponse
{
    public IList<Face> Faces { get; set; }

    public int PageNumber { get; set; }

    public int PageSize { get; set; }
    
    public int TotalPages { get; set; }
    
    public int TotalElements { get; set; }
}

Face 类:

public class Face
{
    public Guid ImageId { get; set; }
    
    public string Subject{ get; set; }
}

按名称删除主题的所有示例

要删除<主题>的所有图像示例：

recognitionService.FaceCollection.DeleteAllAsync(request);

参数	类型	是否必须	解释
request	DeleteAllExamplesRequest	是否必须

DeleteAllExamplesRequest 这是序列化为 JSON 的数据传输对象。

public class DeleteMultipleExampleRequest
{
	public IList<Guid> ImageIdList { get; set; }
}

Response:

{
    "deleted": <count>
}

元素	类型	描述
deleted	integer	删除的人脸数量

此 JSON 响应被反序列化为DeleteMultipleExamplesResponse数据传输对象 (DTO)。

public class DeleteMultipleExamplesResponse
{
	public IList<Face> Faces { get; set; }
}

按 ID 删除主题的示例

按 ID 删除图像：

await recognitionService.FaceCollection.DeleteAsync(request);

参数	类型	是否必须	解释
request	DeleteImageByIdRequest	是

DeleteImageByIdRequest 这是序列化为 JSON 的数据传输对象。

public class DeleteImageByIdRequest
{
	public Guid ImageId { get; set; }
}

Response:

{
  "image_id": <image_id>,
  "subject": <subject>
}

元素	类型	描述
image_id	UUID	被删除的人脸的UUID
subject	string	为此 api 密钥保存其照片的人员的

此 JSON 响应被反序列化为DeleteImageByIdResponse数据传输对象 (DTO)。

public class DeleteImageByIdResponse
{
	public Guid ImageId { get; set; }

	public string Subject { get; set; }
}

通过 ID 直接下载主题的图像示例

按 ID 下载图像：

await recognitionService.FaceCollection.DownloadAsync(downloadImageByIdRequest);

参数	类型	是否必须	解释
request	DownloadImageByIdDirectlyRequest	是

DownloadImageByIdDirectlyRequest 这是序列化为 JSON 的数据传输对象。

public class DownloadImageByIdDirectlyRequest
{
	public Guid ImageId { get; set; }

    public Guid RecognitionApiKey { get; set; }
}

响应正文是二值图像。 如果找不到图像则为空字节。

按 ID 下载主题的图像示例

0.6版本以来

要按 ID 下载主题的图像示例：

await recognitionService.FaceCollection.DownloadAsync(downloadImageBySubjectIdRequest);

参数	类型	是否必须	解释
request	DownloadImageByIdFromSubjectRequest	是

DownloadImageByIdFromSubjectRequest 这是序列化为 JSON 的数据传输对象。

public class DownloadImageByIdFromSubjectRequest
{
	public Guid ImageId { get; set; }
}

Response body是二值图像。 如果找不到图像则为空字节。

获取主题

recognitionService.Subject

返回主题对象
主题对象允许直接使用主题（而不是通过主题示例）。
有关主题的更多信息此处

方法：

Add a Subject

在人脸收藏中创建一个新主题。

await recognitionService.Subject.AddAsync(request);

参数	类型	是否必须	解释
request	AddSubjectRequest	是

AddSubjectRequest 这是序列化为 JSON 的数据传输对象。

public class AddSubjectRequest
{
    public string Subject { get; set; }
}

Response:

{
    
    
  "subject": "subject1"
}

参数	类型	描述
subject	string	是主题的名称

该 JSON 响应被反序列化为AddSubjectResponse数据传输对象（DTO）。

public class AddSubjectResponse
{
    public string Subject { get; set; }
}

获取主题列表

返回与人脸集合相关的所有主题。

await recognitionService.Subject.ListAsync();

Response:

{
    
    
  "subjects": [
    "<subject_name1>",
    "<subject_name2>"
  ]
}

元素	类型	描述
subjects	array	人脸收藏中的主题列表

此 JSON 响应被反序列化为“GetAllSubjectResponse”数据传输对象 (DTO)。

public class GetAllSubjectResponse
{
    public IList<string> Subjects { get; set; }
}

重命名主题

重命名现有主题。 如果新的主题名称已存在，则主题将被合并 - 旧主题名称中的所有面孔将重新分配给具有新名称的主题，旧主题将被删除。

await recognitionService.Subject.RenameAsync(request);

参数	类型	是否必须	解释
request	RenameSubjectRequest	是

RenameSubjectRequest 这是序列化为 JSON 的数据传输对象。

public class RenameSubjectRequest
{
    public string CurrentSubject { get; set; }

    public string Subject { get; set; }
}

Response:

{
    
    
  "updated": "true|false"
}

元素	类型	描述
updated	boolean	failed or success

此 JSON 响应被反序列化为RenameSubjectResponse数据传输对象 (DTO)。

public class RenameSubjectResponse
{
    public bool Updated { get; set; }
}

删除主题

删除现有主题和所有已保存的面孔。

await recognitionService.Subject.DeleteAsync(request);

参数	类型	是否必须	解释
request	DeleteSubjectRequest	是

DeleteSubjectRequest 这是序列化为 JSON 的数据传输对象。

public class RenameSubjectRequest
{
    public string CurrentSubject { get; set; }

    public string Subject { get; set; }
}

Response:

{
    
    
  "subject": "subject1"
}

元素	类型	描述
subject	string	is the name of the subject

此 JSON 响应被反序列化为DeleteSubjectResponse数据传输对象 (DTO)。

public class DeleteSubjectResponse
{
    public string Subject { get; set; }
}

删除所有主题

删除所有现有主题和所有已保存的面孔。

await recognitionService.Subject.DeleteAllAsync();

Response:

{
    
    
  "deleted": "<count>"
}

元素	类型	描述
deleted	integer	number of deleted subjects

此 JSON 响应被反序列化为DeleteAllSubjectsResponse数据传输对象 (DTO)。

public class DeleteAllSubjectsResponse
{
    public int Deleted { get; set; }
}

人脸检测服务

人脸检测服务用于检测图像中的人脸。

方法：

Detect

await faceDetectionService.DetectAsync(request);

查找图像上的所有面孔。

参数	类型	是否必须	解释
request	FaceDetectionRequestByFilePath	是

FaceDetectionRequestByFilePath 这是序列化为 JSON 的数据传输对象。

public class FaceDetectionRequestByFilePath : BaseFaceRequest
{
	public string FilePath { get; set; }
}

BaseFaceRequest 类包含 可选 属性：

public class BaseFaceRequest
{
    public int? Limit { get; set; }

    public decimal DetProbThreshold { get; set; }

    public IList<string> FacePlugins { get; set; }

    public bool Status { get; set; }
}

选项	类型	解释
det_prob_threshold	float	所识别的面孔实际上是面孔所需的最低置信度。 值介于 0.0 和 1.0 之间
limit	integer	图像上要识别的最大人脸数量。 它首先识别最大的面孔。 值为 0 表示没有限制。 默认值：0
prediction_count	integer	每张脸的主题预测的最大数量。 它返回最相似的主题。 默认值：1
face_plugins	string	以逗号分隔的面部插件。 如果为空，则不返回任何附加信息。Learn more
status	boolean	如果 true 包含系统信息，例如execution_time 和plugin_version 字段。 默认值为 false

Response:

{
    
    
  "result" : [ {
    
    
    "age" : {
    
    
      "probability": 0.9308982491493225,
      "high": 32,
      "low": 25
    },
    "gender" : {
    
    
      "probability": 0.9898611307144165,
      "value": "female"
    },
    "mask" : {
    
    
      "probability": 0.9999470710754395,
      "value": "without_mask"
    },
    "embedding" : [ -0.03027934394776821, "...", -0.05117142200469971 ],
    "box" : {
    
    
      "probability" : 0.9987509250640869,
      "x_max" : 376,
      "y_max" : 479,
      "x_min" : 68,
      "y_min" : 77
    },
    "landmarks" : [ [ 156, 245 ], [ 277, 253 ], [ 202, 311 ], [ 148, 358 ], [ 274, 365 ] ],
    "execution_time" : {
    
    
      "age" : 30.0,
      "gender" : 26.0,
      "detector" : 130.0,
      "calculator" : 49.0,
      "mask": 36.0
    }
  } ],
  "plugins_versions" : {
    
    
    "age" : "agegender.AgeDetector",
    "gender" : "agegender.GenderDetector",
    "detector" : "facenet.FaceDetector",
    "calculator" : "facenet.Calculator",
    "mask": "facemask.MaskDetector"
  }
}

元素	类型	描述
age	object	检测到的年龄范围。 仅在启用 age 插件 时返回
gender	object	检测到性别。 仅在启用 性别插件 时返回
mask	object	检测到面具。 仅在启用面罩插件时返回。
embedding	array	人脸嵌入。 仅在启用 计算器插件 时返回
box	object	该人脸的边界框参数列表（在processedImage上）
probability	float	找到的人脸实际上是人脸的概率（在processedImage上）
x_max, y_max, x_min, y_min	integer	包含脸部的帧的坐标（在processedImage上）
landmarks	array	包含面部标志的框架的坐标列表。 仅在启用 landmarks 插件 时返回
execution_time	object	所有插件的执行时间
plugins_versions	object	包含有关插件版本的信息

此 JSON 响应被反序列化为FaceDetectionResponse数据传输对象 (DTO)。

public class FaceDetectionResponse
{
	public IList<BaseResult> Result { get; set; }

	public PluginVersions PluginsVersions { get; set; }
}

BaseResult 类:

public class BaseResult
{
    public Age Age { get; set; }

    public Gender Gender { get; set; }

    public Mask Mask { get; set; }

    public Box Box { get; set; }

    public IList<List<int>> Landmarks { get; set; }

    public ExecutionTime ExecutionTime { get; set; }

    public IList<decimal> Embedding { get; set; }
}

人脸验证服务

人脸验证服务用于比较两个图像。
源图像应仅包含一张面孔，该面孔将与目标图像上的所有面孔进行比较。

方法：

Verify

await faceVerificationService.VerifyAsync(request);

比较参数中提供的两个图像。 源图像应仅包含一张人脸，它将与目标图像中的所有人脸进行比较。

参数	类型	是否必须	解释
request	FaceVerificationRequestByFilePath	是否必须

FaceVerificationRequestByFilePath 这是序列化为 JSON 的数据传输对象。

public class FaceVerificationRequestByFilePath : BaseFaceRequest
{
    public string SourceImageFilePath { get; set; }

    public string TargetImageFilePath { get; set; }
}

BaseFaceRequest 类包含 可选 属性：

public class BaseFaceRequest
{
    public int? Limit { get; set; }

    public decimal DetProbThreshold { get; set; }

    public IList<string> FacePlugins { get; set; }

    public bool Status { get; set; }
}

选项	类型	解释
det_prob_threshold	float	所识别的面孔实际上是面孔所需的最低置信度。 值介于 0.0 和 1.0 之间
limit	integer	图像上要识别的最大人脸数量。 它首先识别最大的面孔。 值为 0 表示没有限制。 默认值：0
prediction_count	integer	每张脸的主题预测的最大数量。 它返回最相似的主题。 默认值：1
face_plugins	string	以逗号分隔的面部插件。 如果为空，则不返回任何附加信息。Learn more
status	boolean	如果 true 包含系统信息，例如execution_time 和plugin_version 字段。 默认值为 false

Response:

{
    
    
  "result" : [{
    
    
    "source_image_face" : {
    
    
      "age" : {
    
    
        "probability": 0.9308982491493225,
        "high": 32,
        "low": 25
      },
      "gender" : {
    
    
        "probability": 0.9898611307144165,
        "value": "female"
      },
      "mask" : {
    
    
        "probability": 0.9999470710754395,
        "value": "without_mask"
      },
      "embedding" : [ -0.0010271212086081505, "...", -0.008746841922402382 ],
      "box" : {
    
    
        "probability" : 0.9997453093528748,
        "x_max" : 205,
        "y_max" : 167,
        "x_min" : 48,
        "y_min" : 0
      },
      "landmarks" : [ [ 92, 44 ], [ 130, 68 ], [ 71, 76 ], [ 60, 104 ], [ 95, 125 ] ],
      "execution_time" : {
    
    
        "age" : 85.0,
        "gender" : 51.0,
        "detector" : 67.0,
        "calculator" : 116.0,
        "mask": 36.0
      }
    },
    "face_matches": [
      {
    
    
        "age" : {
    
    
          "probability": 0.9308982491493225,
          "high": 32,
          "low": 25
        },
        "gender" : {
    
    
          "probability": 0.9898611307144165,
          "value": "female"
        },
        "mask" : {
    
    
          "probability": 0.9999470710754395,
          "value": "without_mask"
        },
        "embedding" : [ -0.049007344990968704, "...", -0.01753818802535534 ],
        "box" : {
    
    
          "probability" : 0.99975,
          "x_max" : 308,
          "y_max" : 180,
          "x_min" : 235,
          "y_min" : 98
        },
        "landmarks" : [ [ 260, 129 ], [ 273, 127 ], [ 258, 136 ], [ 257, 150 ], [ 269, 148 ] ],
        "similarity" : 0.97858,
        "execution_time" : {
    
    
          "age" : 59.0,
          "gender" : 30.0,
          "detector" : 177.0,
          "calculator" : 70.0,
          "mask": 36.0
        }
      }],
    "plugins_versions" : {
    
    
      "age" : "agegender.AgeDetector",
      "gender" : "agegender.GenderDetector",
      "detector" : "facenet.FaceDetector",
      "calculator" : "facenet.Calculator",
      "mask": "facemask.MaskDetector"
    }
  }]
}

元素	类型	描述
source_image_face	object	有关源图像脸部的附加信息
face_matches	array	人脸验证结果
age	object	检测到的年龄范围。 仅在启用 age 插件 时返回
gender	object	检测到性别。 仅在启用 性别插件 时返回
mask	object	检测到面具。 仅在启用面罩插件时返回。
embedding	array	人脸嵌入。 仅在启用 计算器插件 时返回
box	object	该面的边界框参数列表
probability	float	找到的人脸实际上是人脸的概率
x_max, y_max, x_min, y_min	integer	包含脸部的框架的坐标
landmarks	array	包含面部标志的框架的坐标列表。 仅在启用 landmarks 插件 时返回
similarity	float	该脸部与源图像上的脸部之间的相似度
execution_time	object	所有插件的执行时间
plugins_versions	object	包含有关插件版本的信息

此 JSON 响应被反序列化为FaceVerificationResponse数据传输对象 (DTO)。

public class FaceVerificationResponse 
{
    public IList<Result> Result { get; set; }
}

public class Result
{
    public SourceImageFace SourceImageFace { get; set; }
    
    public IList<FaceMatches> FaceMatches { get; set; }
    
    public PluginVersions PluginsVersions { get; set; }
}

public class SourceImageFace : BaseResult
{ }

public class FaceMatches : BaseResult
{
    public decimal Similarity { get; set; }
}

BaseResult 类:

public class BaseResult
{
    public Age Age { get; set; }

    public Gender Gender { get; set; }

    public Mask Mask { get; set; }

    public Box Box { get; set; }

    public IList<List<int>> Landmarks { get; set; }

    public ExecutionTime ExecutionTime { get; set; }

    public IList<decimal> Embedding { get; set; }
}

| float   | 找到的人脸实际上是人脸的概率                                 |

| x_max, y_max, x_min, y_min | integer | 包含脸部的框架的坐标 |
| landmarks | array | 包含面部标志的框架的坐标列表。 仅在启用 landmarks 插件 时返回 |
| similarity | float | 该脸部与源图像上的脸部之间的相似度 |
| execution_time | object | 所有插件的执行时间 |
| plugins_versions | object | 包含有关插件版本的信息 |

此 JSON 响应被反序列化为FaceVerificationResponse数据传输对象 (DTO)。

public class FaceVerificationResponse 
{
    public IList<Result> Result { get; set; }
}

public class Result
{
    public SourceImageFace SourceImageFace { get; set; }
    
    public IList<FaceMatches> FaceMatches { get; set; }
    
    public PluginVersions PluginsVersions { get; set; }
}

public class SourceImageFace : BaseResult
{ }

public class FaceMatches : BaseResult
{
    public decimal Similarity { get; set; }
}

BaseResult 类:

public class BaseResult
{
    public Age Age { get; set; }

    public Gender Gender { get; set; }

    public Mask Mask { get; set; }

    public Box Box { get; set; }

    public IList<List<int>> Landmarks { get; set; }

    public ExecutionTime ExecutionTime { get; set; }

    public IList<decimal> Embedding { get; set; }
}