검색 API 호출

  • 아티클

주의

Face 서비스 액세스는 책임 있는 AI 원칙을 지원하기 위해 자격 및 사용 기준에 따라 제한됩니다. Face 서비스는 Microsoft 관리 고객 및 파트너만 사용할 수 있습니다. 얼굴 인식 접수 양식을 사용하여 액세스를 적용합니다. 자세한 내용은 얼굴 제한 액세스 페이지를 참조하세요.

주의

Microsoft는 오용될 경우 고정관념, 차별 또는 불공정한 서비스 거부의 대상이 될 수 있는 감정 상태 및 ID 특성을 유추하는 데 사용할 수 있는 얼굴 인식 기능을 사용 중지할 예정입니다. 여기에는 감정, 성별, 나이, 미소, 수염, 헤어 및 메이크업을 예측하는 기능이 포함됩니다. 기존 고객은 2023년 6월 30일까지 이러한 기능의 사용을 중단하기 전에 사용 중지해야 합니다. 여기에서 이 결정에 대해 자세히 알아봅니다.

이 가이드에서는 얼굴 감지 API를 사용하여 지정된 이미지에서 연령, 감정, 머리 포즈와 같은 특성을 추출하는 방법을 보여 줍니다. 사용자 요구에 맞게 이 API의 동작을 구성하는 다양한 방법을 알아봅니다.

이 가이드의 코드 조각은 Azure Cognitive Services Face 클라이언트 라이브러리를 사용하여 C#으로 작성되었습니다. 이 기능은 REST API를 통해 사용할 수 있습니다.

설정

이 가이드에서는 Face 키와 엔드포인트 URL을 사용하여 faceClient라는 FaceClient 개체를 이미 생성했다고 가정합니다. 이 기능을 설정하는 방법에 대한 지침은 빠른 시작 중 하나를 수행합니다.

서비스에 데이터 제출

이미지에서 얼굴을 찾고 해당 위치를 가져오려면 DetectWithUrlAsync 또는 DetectWithStreamAsync 메서드를 호출합니다. DetectWithUrlAsync는 URL 문자열을 입력으로 사용하고 DetectWithStreamAsync는 이미지의 원시 바이트 스트림을 입력으로 사용합니다.

IList<DetectedFace> faces = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, detectionModel: DetectionModel.Detection03);

반환된 DetectedFace 개체에서 각 얼굴의 픽셀 좌표를 제공하는 사각형을 쿼리할 수 있습니다. returnFaceId를 true로 설정하면(승인된 고객만 해당) 각 얼굴의 고유 ID를 가져올 수 있으며, 이후 얼굴 인식 작업에서 사용할 수 있습니다.

foreach (var face in faces)
{
    string id = face.FaceId.ToString();
    FaceRectangle rect = face.FaceRectangle;
}

얼굴의 위치 및 크기를 구문 분석하는 방법에 대한 자세한 내용은 FaceRectangle을 참조하세요. 일반적으로 이 직사각형에는 눈, 눈섭, 코 및 입이 포함됩니다. 정수리, 귀 및 턱은 반드시 포함되는 것은 아닙니다. 얼굴 사각형을 사용하여 전체 머리를 자르거나 중거리 인물 사진을 가져오려면 사각형을 각 방향으로 확장해야 합니다.

데이터 처리 방법 결정

이 가이드는 전달할 수 있는 인수와 반환된 데이터로 수행할 수 있는 작업을 비롯하여 감지 호출의 세부 사항을 중점적으로 설명합니다. 필요한 기능만 쿼리하는 것이 좋습니다. 각 작업을 완료하려면 더 많은 시간이 걸립니다.

얼굴 랜드마크 가져오기

얼굴 랜드마크는 눈동자나 코끝과 같이 얼굴에서 찾기 쉬운 지점의 집합입니다. 얼굴 랜드마크 데이터를 가져오려면 detectionModel 매개 변수를 DetectionModel.Detection01로 설정하고 returnFaceLandmarks 매개 변수를 true로 설정합니다.

// Note DetectionModel.Detection02 cannot be used with returnFaceLandmarks.
IList<DetectedFace> faces2 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, returnFaceLandmarks: true, detectionModel: DetectionModel.Detection01);

얼굴 특성 가져오기

얼굴 감지 API는 얼굴 직사각형과 랜드마크 외에도 얼굴의 여러 개념 특성을 분석할 수 있습니다. 전체 목록은 얼굴 특성 개념 섹션을 참조하세요.

얼굴 특성을 분석하려면 detectionModel 매개 변수를 DetectionModel.Detection01로 설정하고 returnFaceAttributes 매개 변수를 FaceAttributeType 열거형 값 목록으로 설정합니다.

var requiredFaceAttributes = new FaceAttributeType[] {
    FaceAttributeType.HeadPose,
    FaceAttributeType.Glasses,
    FaceAttributeType.QualityForRecognition
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var faces3 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, returnFaceAttributes: requiredFaceAttributes, detectionModel: DetectionModel.Detection01, recognitionModel: RecognitionModel.Recognition04);

서비스에서 결과 가져오기

얼굴 랜드마크 결과

다음 코드는 코와 눈동자의 위치를 검색하는 방법을 보여줍니다.

foreach (var face in faces2)
{
    var landmarks = face.FaceLandmarks;

    double noseX = landmarks.NoseTip.X;
    double noseY = landmarks.NoseTip.Y;

    double leftPupilX = landmarks.PupilLeft.X;
    double leftPupilY = landmarks.PupilLeft.Y;

    double rightPupilX = landmarks.PupilRight.X;
    double rightPupilY = landmarks.PupilRight.Y;

얼굴 랜드마크 데이터를 사용하여 얼굴의 방향을 정확하게 계산할 수도 있습니다. 예를 들어 얼굴의 방향을 입의 가운데부터 눈의 가운데까지 벡터로 정의할 수 있습니다. 다음 코드는 이 벡터를 계산합니다.

    var upperLipBottom = landmarks.UpperLipBottom;
    var underLipTop = landmarks.UnderLipTop;

    var centerOfMouth = new Point(
        (upperLipBottom.X + underLipTop.X) / 2,
        (upperLipBottom.Y + underLipTop.Y) / 2);

    var eyeLeftInner = landmarks.EyeLeftInner;
    var eyeRightInner = landmarks.EyeRightInner;

    var centerOfTwoEyes = new Point(
        (eyeLeftInner.X + eyeRightInner.X) / 2,
        (eyeLeftInner.Y + eyeRightInner.Y) / 2);

    Vector faceDirection = new Vector(
        centerOfTwoEyes.X - centerOfMouth.X,
        centerOfTwoEyes.Y - centerOfMouth.Y);
}

얼굴 방향을 알고 있는 경우 직사각형 얼굴을 회전하여 더 정확하게 정렬할 수 있습니다. 이미지에서 얼굴을 자르려면 얼굴이 항상 똑바로 나타나도록 이미지를 프로그래밍 방식으로 회전할 수 있습니다.

얼굴 특성 결과

다음 코드는 원래 호출에서 요청한 얼굴 특성 데이터를 검색하는 방법을 보여 줍니다.

foreach (var face in faces3)
{
    var attributes = face.FaceAttributes;
    var headPose = attributes.HeadPose;
    var glasses = attributes.Glasses;
    var qualityForRecognition = attributes.QualityForRecognition;
}

각 특성에 대해 자세히 알아보려면 얼굴 감지 및 특성 개념 가이드를 참조하세요.

다음 단계

이 가이드에서는 얼굴 감지 및 분석의 다양한 기능을 사용하는 방법을 알아보았습니다. 다음으로, 이러한 기능을 앱에 통합하여 사용자의 얼굴 데이터를 추가합니다.