Face API를 사용 하는 인식 된 Emotion 인식Perceived Emotion Recognition Using the Face API

샘플 다운로드 샘플 다운로드Download Sample Download the sample

이 Face API는 휴먼 coders의 인식 된 주석을 기반으로 하는 얼굴 식에서 분노, 경 멸, 혐오, emotion, 행복, 중립, sadness을 검색 하는 데 검색을 수행할 수 있습니다.The Face API can perform emotion detection to detect anger, contempt, disgust, fear, happiness, neutral, sadness, and surprise, in a facial expression based on perceived annotations by human coders. 그러나 얼굴 식 만으로는 사용자의 내부 상태를 반드시 나타내는 것은 아닙니다.It is important to note, however, that facial expressions alone may not necessarily represent the internal states of people.

얼굴 식에 대 한 emotion 결과를 반환 하는 것 외에도, 검색 Face API 된 면에 대 한 경계 상자를 반환할 수 있습니다.In addition to returning an emotion result for a facial expression, the Face API can also returns a bounding box for detected faces. Face 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에 대 한 자세한 내용은 참조 하세요. Face REST API합니다.For more information about the REST API, see Face REST API.

Face 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.

Face API에 대 한 자세한 내용은 참조 하세요. Face API합니다.For more information about the Face API, see Face API.

인증Authentication

Face 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);
}

Face API에 유효한 API 키를 전달 하는 오류 401 응답 오류가 발생 합니다.Failure to pass a valid API key to the Face API will result in a 401 response error.

Emotion 인식 수행Perform 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, facialHairglasses, emotion, hair, makeupocclusion, accessories, blur하십시오 exposure, 및 noise합니다.Supported face attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure, and noise. 얼굴 특성 분석에 추가 계산 시간 및 비용을 참고 합니다.Note that face attribute analysis has additional computational and time cost.

이미지 콘텐츠 URL 또는 이진 데이터를 POST 요청의 본문에 배치 되어야 합니다.Image content must be placed in the body of the POST request as a URL, or binary data.

참고

지원 되는 이미지 파일은 JPEG, PNG, GIF 및 BMP, 및 허용 되는 파일 크기가 1KB에서 4mb입니다.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.

참고

동일한 지역으로 구독 키를 가져오는 데 사용 하 여 Face 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.

요청 보내기Send the request

합니다 SendRequestAsync Face API에 POST 요청 메서드와으로 결과 반환을 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. 응답을 deserialize 읽고 호출 메서드로 반환 합니다.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. 가능한 오류 응답의 목록을 참조 하세요 Face REST API합니다.For a list of possible error responses, see Face REST API.

응답 처리Process 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 응답의 배열으로 deserialize Face 개체입니다.In the sample application, the JSON response is deserialized into an array of Face objects. Face 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. 따라서 샘플 응용 프로그램 이미지의 최대 검색 된 얼굴에 대 한 점수가 가장 높은 인식된 emotion을 표시합니다.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: