Chamar a API de Detecção
Cuidado
O acesso ao serviço de Detecção Facial é limitado com base em critérios de qualificação e uso para dar suporte aos nossos princípios de IA responsável. O serviço de Detecção Facial só está disponível para clientes e parceiros gerenciados da Microsoft. Use o Formulário de admissão de reconhecimento facial para solicitar acesso. Para obter mais informações, consulte a página Acesso limitado facial.
Cuidado
A Microsoft desativará as funcionalidades de reconhecimento facial que podem ser usadas para tentar inferir estados emocionais e atributos de identidade que, se mal utilizados, podem submeter as pessoas a estereótipos, discriminação ou recusa injusta de serviços. Isso inclui recursos que preveem emoção, gênero, idade, sorriso, pelos faciais, cabelo e maquiagem. Leia mais sobre essa decisão aqui.
Este guia demonstra como usar a API de detecção facial para extrair atributos de uma determinada imagem. Você aprenderá as diversas maneiras de configurar o comportamento dessa API para atender às suas necessidades.
Os códigos dos snippets deste guia foram escritos em C# com a biblioteca de clientes da Detecção Facial da IA do Azure. O mesmo recurso está disponível por meio da API REST.
Instalação
Este guia considera que você já tenha construído um objeto FaceClient chamado faceClient
, usando uma chave de Detecção Facial e uma URL de ponto de extremidade. Para obter instruções sobre como configurar esse recurso, siga um dos guias de início rápido.
Enviar dados ao serviço
Para encontrar rostos e obter suas localizações em uma imagem, chame o método DetectWithUrlAsync ou DetectWithStreamAsync. DetectWithUrlAsync usa uma cadeia de caracteres de URL como entrada, e DetectWithStreamAsync usa o fluxo de byte bruto de uma imagem como entrada.
IList<DetectedFace> faces = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, detectionModel: DetectionModel.Detection03);
O serviço retorna um objeto DetectedFace, que você pode consultar para diferentes tipos de informações, especificado abaixo.
Para obter informações sobre como analisar a localização e as dimensões do rosto, confira FaceRectangle. Normalmente, esse retângulo contém os olhos, as sobrancelhas, o nariz e a boca. A parte superior da cabeça, os ouvidos e o queixo não estão necessariamente incluídos. Para usar o retângulo de rosto para recortar totalmente uma cabeça ou obter um retrato de média distância, expanda o retângulo em todas as direções.
Determinar como processar os dados
Este guia concentra-se nas especificidades da chamada da Detecção, como os argumentos que você pode passar e o que pode fazer com os dados retornados. Recomendamos que você consulte apenas os recursos necessários. Cada operação demora mais para ser concluída.
A ID da face
Caso você defina o parâmetro returnFaceId como true
(somente clientes aprovados), poderá obter a ID exclusiva de cada rosto, que pode ser usada nas tarefas de reconhecimento facial posteriores.
foreach (var face in faces)
{
string id = face.FaceId.ToString();
FaceRectangle rect = face.FaceRectangle;
}
O parâmetro faceIdTimeToLive opcional especifica quanto tempo (em segundos) a ID da face deve ser armazenada no servidor. Depois que esse tempo expirar, a ID da face será removida. O valor padrão é 86400 (24 horas).
Obter pontos de referência facial
Os pontos de referência faciais são um conjunto de pontos fáceis de encontrar em um rosto, como as pupilas ou a ponta do nariz. Para obter dados de referência do rosto, defina o parâmetro detectionModel como DetectionModel.Detection01
e o parâmetro returnFaceLandmarks como 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);
Obter atributos faciais
Além dos retângulos e pontos de referência faciais, a API de Detecção Facial pode analisar vários atributos conceituais de um rosto. Para obter uma lista completa, confira a seção conceitual de Atributos de rosto.
Para analisar os atributos de rosto, defina o parâmetro detectionModel como DetectionModel.Detection01
e o parâmetro returnFaceAttributes como uma lista de valores de FaceAttributeType Enum.
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);
Obter resultados do serviço
Resultados da referência do rosto
O seguinte código demonstra como você pode recuperar as localizações do nariz e das pupilas:
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;
Você também pode usar dados de referência do rosto para calcular precisamente a direção do rosto. Por exemplo, você pode definir a rotação do rosto como um vetor partindo do centro da boca para o centro dos olhos. O seguinte código calcula esse vetor:
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);
}
Quando você sabe a direção do rosto, pode girar o quadro de rosto retangular para alinhá-lo mais adequadamente. Para recortar rostos em uma imagem, você pode girar a imagem de maneira programática para que os rostos sempre apareçam na vertical.
Resultados de atributo do rosto
O código a seguir mostra como você pode recuperar os dados de atributo de rosto solicitados na chamada original.
foreach (var face in faces3)
{
var attributes = face.FaceAttributes;
var headPose = attributes.HeadPose;
var glasses = attributes.Glasses;
var qualityForRecognition = attributes.QualityForRecognition;
}
Para saber mais sobre cada um dos atributos, confira o guia conceitual de Detecção e atributos de rosto.
Próximas etapas
Neste guia, você aprendeu a usar as várias funcionalidades da detecção e análise facial. Em seguida, integre esses recursos em um aplicativo para adicionar dados do rosto de usuários.