검색 API 호출

  • 아티클

주의

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

주의

Microsoft는 오용할 경우 사람들이 고정관념, 차별 또는 불공정한 서비스 거부를 당할 수 있는 감정 상태 및 신원 속성을 추론하는 데 사용할 수 있는 얼굴 인식 기능을 중단했습니다. 여기에는 감정, 성별, 나이, 미소, 수염, 헤어 및 메이크업을 예측하는 기능이 포함됩니다. 여기에서 이 결정에 대해 자세히 알아봅니다.

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

이 가이드의 코드 조각은 Azure AI 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 개체를 반환합니다.

얼굴의 위치 및 크기를 구문 분석하는 방법에 대한 자세한 내용은 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 매개 변수를 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;
}

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

다음 단계

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