Распознавание эмоций с помощью API распознавания лицEmotion Recognition Using the Face API

Загрузить образец загрузить примерDownload Sample Download the sample

API распознавания лиц принимает данные о выражении лица на изображении в качестве входных данных и возвращает данные, которые содержат уровней достоверности между набором эмоции на каждом лице на изображении. В этой статье описывается использование API распознавания лиц для распознавания эмоций для оценки приложения Xamarin.Forms.The Face API takes a facial expression in an image as an input, and returns data that includes confidence levels across a set of emotions for each face in the image. This article explains how to use the Face API to recognize emotion, to rate a Xamarin.Forms application.

ОбзорOverview

API распознавания лиц можно выполнить обнаружение эмоций на лице для обнаружения, гнев, презрение, отвращение, страх, счастье, Нейтральное, грусть и удивление, в выражении лица.The Face API can perform emotion detection to detect anger, contempt, disgust, fear, happiness, neutral, sadness, and surprise, in a facial expression. Эти эмоции, глобально и что взаимодействуют через те же базовые выражения лиц.These emotions are universally and cross-culturally communicated via the same basic facial expressions. А также Возврат результата распознавания эмоций для выражения лиц, API распознавания лиц можно также Возвращает ограничивающий прямоугольник для обнаруженных лиц.As well as returning an emotion result for a facial expression, the Face API can also returns a bounding box for detected faces. Обратите внимание, что необходимо получить ключ API для использования API распознавания лиц.Note that an API key must be obtained to use the Face API. Его можно получить в попробуйте Cognitive Services.This can be obtained at Try Cognitive Services.

Распознавание эмоций лица могут выполняться через клиентскую библиотеку, а также через REST API.Emotion recognition can be performed via a client library, and via a REST API. Эта статья посвящена распознавания эмоций с помощью REST API.This article focuses on performing emotion recognition via the REST API. Дополнительные сведения о REST API, см. в разделе REST API распознавания лиц.For more information about the REST API, see Face REST API.

API распознавания лиц могут также использоваться для распознавания выражений лиц людей на видео и может возвращать сводка об их эмоциях.The Face API can also be used to recognize the facial expressions of people in video, and can return a summary of their emotions. Дополнительные сведения см. в разделе как анализ видео в реальном времени.For more information, see How to Analyze Videos in Real-time.

Дополнительные сведения о API распознавания лиц, см. в разделе API распознавания лиц.For more information about the Face API, see Face API.

Проверка подлинностиAuthentication

Каждый запрос к API распознавания лиц требуется ключ API, который должен быть указан для параметра Ocp-Apim-Subscription-Key заголовка.Every request made to the Face API requires an API key that should be specified as the value of the Ocp-Apim-Subscription-Key header. В следующем примере кода показано, как добавить ключ API, чтобы Ocp-Apim-Subscription-Key заголовка запроса:The following code example shows how to add the API key to the Ocp-Apim-Subscription-Key header of a request:

public FaceRecognitionService()
{
  _client = new HttpClient();
  _client.DefaultRequestHeaders.Add("ocp-apim-subscription-key", Constants.FaceApiKey);
}

Не удалось передать допустимый ключ API для API распознавания лиц приведет к ошибке с ответом 401.Failure to pass a valid API key to the Face API will result in a 401 response error.

Распознавания эмоцийPerforming Emotion Recognition

Распознавание эмоций выполняется путем отправки запроса POST, содержащего изображение detect API в https://[location].api.cognitive.microsoft.com/face/v1.0, где [location]] — регион, используемый для получения ключа API.Emotion recognition is performed by making a POST request containing an image to the detect API at https://[location].api.cognitive.microsoft.com/face/v1.0, where [location]] is the region you used to obtain your API key. Используются следующие параметры необязательные параметры запроса.The optional request parameters are:

  • returnFaceId — следует ли возвращать faceIds обнаруженных лиц.returnFaceId – whether to return faceIds of the detected faces. Значение по умолчанию — true.The default value is true.
  • returnFaceLandmarks — следует ли возвращать позу обнаруженных лиц.returnFaceLandmarks – whether to return face landmarks of the detected faces. Значение по умолчанию — false.The default value is false.
  • returnFaceAttributes — следует ли анализировать и возвращать один или несколько указанных лицевым атрибутам.returnFaceAttributes – whether to analyze and return one or more specified face attributes. Поддерживаемые атрибуты включают age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure, и noise.Supported face attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure, and noise. Обратите внимание, что атрибут analysis лиц дополнительных затрат времени и вычислений.Note that face attribute analysis has additional computational and time cost.

Содержимое изображения должны находиться в тексте запроса POST, как URL-адрес или двоичные данные.Image content must be placed in the body of the POST request as a URL, or binary data.

Примечание

Поддерживаемые форматы используются JPEG, PNG, GIF и BMP и допустимый размер файла — от 1 КБ до 4 МБ.Supported image file formats are JPEG, PNG, GIF, and BMP, and the allowed file size is from 1KB to 4MB.

В примере приложения, процесс распознавания эмоций вызывается путем вызова метода DetectAsync метод:In the sample application, the emotion recognition process is invoked by calling the DetectAsync method:

Face[] faces = await _faceRecognitionService.DetectAsync(photoStream, true, false, new FaceAttributeType[] { FaceAttributeType.Emotion });

Вызов этого метода указывает поток, содержащий данные изображения, который должен быть возвращен faceIds, что не должны возвращаться позу и эмоций изображения должны быть проанализированы.This method call specifies the stream containing the image data, that faceIds should be returned, that face landmarks shouldn't be returned, and that the emotion of the image should be analyzed. Он также указывает, что результаты возвращаются в виде массива Face объектов.It also specifies that the results will be returned as an array of Face objects. В свою очередь DetectAsync вызывает метод detect REST API, который выполняет распознавание эмоций лица:In turn, the DetectAsync method invokes the detect REST API that performs emotion recognition:

public async Task<Face[]> DetectAsync(Stream imageStream, bool returnFaceId, bool returnFaceLandmarks, IEnumerable<FaceAttributeType> returnFaceAttributes)
{
  var requestUrl =
    $"{Constants.FaceEndpoint}/detect?returnFaceId={returnFaceId}" +
    "&returnFaceLandmarks={returnFaceLandmarks}" +
    "&returnFaceAttributes={GetAttributeString(returnFaceAttributes)}";
  return await SendRequestAsync<Stream, Face[]>(HttpMethod.Post, requestUrl, imageStream);
}

Этот метод создает URI запроса, а затем отправляет запрос на detect API через SendRequestAsync метод.This method generates a request URI and then sends the request to the detect API via the SendRequestAsync method.

Примечание

В вызовах API распознавания лиц как можно использовать для получения ключи подписки, необходимо использовать тот же регион.You must use the same region in your Face API calls as you used to obtain your subscription keys. Например, если вы приобрели ключи подписки из westus регион, конечная точка обнаружения лиц будут https://westus.api.cognitive.microsoft.com/face/v1.0/detect.For example, if you obtained your subscription keys from the westus region, the face detection endpoint will be https://westus.api.cognitive.microsoft.com/face/v1.0/detect.

Отправка запросаSending the Request

SendRequestAsync Метод выполняет запрос POST для API распознавания лиц и возвращает результат в виде Face массива:The SendRequestAsync method makes the POST request to the Face API and returns the result as a Face array:

async Task<TResponse> SendRequestAsync<TRequest, TResponse>(HttpMethod httpMethod, string requestUrl, TRequest requestBody)
{
  var request = new HttpRequestMessage(httpMethod, Constants.FaceEndpoint);
  request.RequestUri = new Uri(requestUrl);
  if (requestBody != null)
  {
    if (requestBody is Stream)
    {
      request.Content = new StreamContent(requestBody as Stream);
      request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
    }
    else
    {
      // If the image is supplied via a URL
      request.Content = new StringContent(JsonConvert.SerializeObject(requestBody, s_settings), Encoding.UTF8, "application/json");
    }
  }

  HttpResponseMessage responseMessage = await _client.SendAsync(request);
  if (responseMessage.IsSuccessStatusCode)
  {
    string responseContent = null;
    if (responseMessage.Content != null)
    {
      responseContent = await responseMessage.Content.ReadAsStringAsync();
    }
    if (!string.IsNullOrWhiteSpace(responseContent))
    {
      return JsonConvert.DeserializeObject<TResponse>(responseContent, s_settings);
    }
    return default(TResponse);
  }
  else
  {
    ...
  }
  return default(TResponse);
}

Если изображение предоставляется через поток, метод создает запрос POST путем заключения поток изображения в StreamContent экземпляр, который предоставляет содержимое HTTP на основе потока.If the image is supplied via a stream, the method builds the POST request by wrapping the image stream in a StreamContent instance, which provides HTTP content based on a stream. Кроме того, если изображение предоставляется через URL-адрес, метод сборки запрос POST, заключая URL-адрес в StringContent экземпляр, который предоставляет содержимое HTTP на основе строки.Alternatively, if the image is supplied via a URL, the method builds the POST request by wrapping the URL in a StringContent instance, which provides HTTP content based on a string.

Затем отправляется запрос POST detect API.The POST request is then sent to detect API. Ответ считывается, десериализации и возвращается вызывающему методу.The response is read, deserialized, and returned to the calling method.

detect API отправит код состояния HTTP 200 (ОК) в ответе, при условии, что запрос является допустимым, который указывает, что запрос успешно выполнен, и что запрашиваемые данные находятся в ответе.The detect API will send HTTP status code 200 (OK) in the response, provided that the request is valid, which indicates that the request succeeded and that the requested information is in the response. Список возможные сообщения об ошибках, см. в разделе REST API распознавания лиц.For a list of possible error responses, see Face REST API.

Обработка ответаProcessing the Response

В ответе API возвращаются в формате JSON.The API response is returned in JSON format. Следующие данные JSON показывает сообщение обычно успешный ответ, предоставляющий данные, запрашиваемые примера приложения:The following JSON data shows a typical successful response message that supplies the data requested by the sample application:

[  
   {  
      "faceId":"8a1a80fe-1027-48cf-a7f0-e61c0f005051",
      "faceRectangle":{  
         "top":192,
         "left":164,
         "width":339,
         "height":339
      },
      "faceAttributes":{  
         "emotion":{  
            "anger":0.0,
            "contempt":0.0,
            "disgust":0.0,
            "fear":0.0,
            "happiness":1.0,
            "neutral":0.0,
            "sadness":0.0,
            "surprise":0.0
         }
      }
   }
]

Успешный ответ сообщение состоит из массив записей лиц, отсортированные по размеру прямоугольник лиц в нисходящем порядке, в то время как пустой ответ указывает лица не обнаружены.A successful response message consists of an array of face entries ranked by face rectangle size in descending order, while an empty response indicates no faces detected. Каждый распознан лиц включает ряд атрибутов необязательно лиц, которые задаются returnFaceAttributes аргумент DetectAsync метод.Each recognized face includes a series of optional face attributes, which are specified by the returnFaceAttributes argument to the DetectAsync method.

В примере приложения, ответ JSON десериализуются в массив Face объектов.In the sample application, the JSON response is deserialized into an array of Face objects. При интерпретации результатов из API распознавания лиц, обнаруженных эмоций должны интерпретироваться как эмоций с наивысшей оценкой, как показатели нормализуются суммируемые к одному.When interpreting results from the Face API, the detected emotion should be interpreted as the emotion with the highest score, as scores are normalized to sum to one. Таким образом в примере приложения отображались распознанных эмоций с наивысшей оценкой для наибольшего обнаруженного лица на изображении.Therefore, the sample application displays the recognized emotion with the highest score for the largest detected face in the image. Это достигается следующим кодом:This is achieved with the following code:

emotionResultLabel.Text = faces.FirstOrDefault().FaceAttributes.Emotion.ToRankedList().FirstOrDefault().Key;

На следующем рисунке показан результат распознавания эмоций в приложении-примере:The following screenshot shows the result of the emotion recognition process in the sample application:

СводкаSummary

В этой статье было рассмотрено, как использовать API распознавания лиц для распознавания эмоций для оценки приложения Xamarin.Forms.This article explained how to use the Face API to recognize emotion, to rate a Xamarin.Forms application. API распознавания лиц принимает данные о выражении лица на изображении в качестве входных данных и возвращает данные, которые содержат уверенность в наборе точные сведения об эмоциях на каждом лице на изображении.The Face API takes a facial expression in an image as an input, and returns data that includes the confidence across a set of emotions for each face in the image.