다음을 통해 공유

검색 API 호출

  • 아티클

주의

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

주의

Microsoft는 감정 상태 및 신원 특성을 추론하는 데 사용할 수 있는 얼굴 인식 기능 중 오용될 경우 사람들이 고정 관념, 차별 또는 불공정한 서비스 거부를 겪는 원인이 될 수 있는 기능을 중단하거나 제한했습니다. 사용 중지된 기능은 감정과 성별입니다. 제한된 기능으로는 나이, 미소, 수염, 머리 스타일, 화장 등이 있습니다. 제한된 기능을 사용하여 이점을 얻을 수 있으며 책임감 있게 사용할 수 있는 시나리오가 있는 경우 Azure Face API에 이메일을 보내세요. 여기에서 이 결정에 대해 자세히 알아봅니다.

이 가이드에서는 얼굴 감지 API를 사용하여 특정 이미지에서 특성을 추출하는 방법을 보여 줍니다. 사용자 요구에 맞게 이 API의 동작을 구성하는 다양한 방법을 알아봅니다.

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

설정

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

서비스에 데이터 제출

얼굴을 찾고 이미지에서 해당 위치를 가져오려면 DetectAsync를 호출합니다. URL 문자열 또는 원시 이미지 이진 파일을 입력으로 사용합니다.

var response = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false);
IReadOnlyList<FaceDetectionResult> faces = response.Value;

서비스는 아래에 지정된 다양한 종류의 정보를 쿼리할 수 있는 FaceDetectionResult 개체를 반환합니다.

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

데이터 처리 방법 결정

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

얼굴 ID 가져오기

매개 변수 returnFaceId를 true로 설정하면(승인된 고객만 해당) 각 얼굴의 고유 ID를 가져올 수 있으며, 이후 얼굴 인식 작업에서 사용할 수 있습니다.

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

선택적 faceIdTimeToLive 매개 변수는 얼굴 ID를 서버에 저장할 기간(초)을 지정합니다. 이 시간이 만료되면 얼굴 ID가 제거됩니다. 기본값은 86400(24시간)입니다.

얼굴 랜드마크 가져오기

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

// Note DetectionModel.Detection02 cannot be used with returnFaceLandmarks.
var response2 = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false, returnFaceLandmarks: true);
IReadOnlyList<FaceDetectionResult> faces2 = response2.Value;

얼굴 특성 가져오기

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

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

var requiredFaceAttributes = new FaceAttributeType[] {
    FaceAttributeType.Detection03.Blur,
    FaceAttributeType.Detection03.HeadPose,
    FaceAttributeType.Detection03.Mask,
    FaceAttributeType.Recognition04.QualityForRecognition
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var response3 = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false, returnFaceAttributes: requiredFaceAttributes);
IReadOnlyList<FaceDetectionResult> faces3 = response3.Value;

서비스에서 결과 가져오기

얼굴 랜드마크 결과

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

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(
        (int)((upperLipBottom.X + underLipTop.X) / 2),
        (int)((upperLipBottom.Y + underLipTop.Y) / 2));

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

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

    var faceDirectionVectorX = centerOfTwoEyes.X - centerOfMouth.X;
    var faceDirectionVectorY = centerOfTwoEyes.Y - centerOfMouth.Y;
}

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

얼굴 특성 결과

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

foreach (var face in faces3)
{
    var attributes = face.FaceAttributes;
    var blur = attributes.Blur;
    var headPose = attributes.HeadPose;
    var mask = attributes.Mask;
    var qualityForRecognition = attributes.QualityForRecognition;
}

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

다음 단계

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