Chiamare l'API di rilevamento
Attenzione
L'accesso al servizio Viso è limitato in base ai criteri di idoneità e utilizzo per supportare i principi di IA responsabile. Il servizio Viso è disponibile solo per i clienti e i partner gestiti da Microsoft. Usare il modulo di assunzione riconoscimento del viso per richiedere l'accesso. Per altre informazioni, vedere la pagina Viso con accesso limitato.
Attenzione
Microsoft ha ritirato le funzionalità di riconoscimento facciale che possono essere usate per provare a dedurre gli stati emotivi e gli attributi di identità che, se usati in modo improprio, possono essere soggetti a stereotipi, discriminazione o negazione ingiusta dei servizi. Queste includono funzionalità che prevedono emozioni, sesso, età, sorriso, capelli facciali, capelli e trucco. Altre informazioni su questa decisione sono disponibili qui.
Questa guida illustra come usare l'API di rilevamento dei volti per estrarre gli attributi da una determinata immagine. Verranno illustrati i diversi modi per configurare il comportamento di questa API per soddisfare le proprie esigenze.
I frammenti di codice in questa guida vengono scritti in C# usando la libreria client viso di Intelligenza artificiale di Azure. La stessa funzionalità è disponibile tramite l'API REST.
Impostazione
Questa guida presuppone che sia già stato creato un oggetto FaceClient , denominato faceClient, usando una chiave Viso e un URL dell'endpoint. Per istruzioni su come configurare questa funzionalità, seguire una delle guide introduttive.
Inviare dati al servizio
Per trovare i visi e ottenere le posizioni in un'immagine, chiamare il metodo DetectWithUrlAsync o DetectWithStreamAsync . DetectWithUrlAsync accetta una stringa URL come input e DetectWithStreamAsync accetta il flusso di byte non elaborato di un'immagine come input.
IList<DetectedFace> faces = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, detectionModel: DetectionModel.Detection03);
Il servizio restituisce un oggetto DetectedFace , che è possibile eseguire una query per tipi diversi di informazioni, specificato di seguito.
Per informazioni su come analizzare la posizione e le dimensioni del viso, vedere FaceRectangle. In genere, questo rettangolo contiene gli occhi, le sopracciglia, il naso e la bocca. La parte superiore della testa, delle orecchie e del mento non sono necessariamente incluse. Per usare il rettangolo del viso per ritagliare una testa completa o ottenere un ritratto medio, è necessario espandere il rettangolo in ogni direzione.
Determinare come elaborare i dati
Questa guida è incentrata sulle specifiche della chiamata Detect, ad esempio sugli argomenti che è possibile passare e sulle operazioni che è possibile eseguire con i dati restituiti. È consigliabile eseguire una query solo per le funzionalità necessarie. Il completamento di ogni operazione richiede più tempo.
Ottenere l'ID viso
Se si imposta il parametro returnFaceId su true (solo clienti approvati), è possibile ottenere l'ID univoco per ogni viso, che è possibile usare nelle attività di riconoscimento dei visi successive.
foreach (var face in faces)
{
string id = face.FaceId.ToString();
FaceRectangle rect = face.FaceRectangle;
}
Il parametro facoltativo faceIdTimeToLive specifica per quanto tempo (in secondi) l'ID viso deve essere archiviato nel server. Dopo questa scadenza, l'ID viso viene rimosso. Il valore predefinito è 86400 (24 ore).
Ottenere punti di riferimento del viso
I punti di riferimento del viso sono una serie di punti facili da trovare su un viso, come le pupille o la punta del naso. Per ottenere i dati dei punti di riferimento del viso, impostare il parametro detectionModel su DetectionModel.Detection01 e il parametro returnFaceLandmarks su 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);
Recuperare gli attributi del viso
Oltre ai rettangoli del viso e ai punti di riferimento, l'API di rilevamento dei volti può analizzare diversi attributi concettuali di un viso. Per un elenco completo, vedere la sezione concettuale Attributi viso.
Per analizzare gli attributi del viso, impostare il parametro detectionModel su DetectionModel.Detection01 e il parametro returnFaceAttributes su un elenco di valori EnumFaceAttributeType.
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);
Ottenere risultati dal servizio
Risultati dei punti di riferimento del viso
Il codice seguente illustra come recuperare le posizioni del naso e delle pupille:
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;
È anche possibile usare i dati dei punti di riferimento del viso per calcolare accuratamente la direzione del viso. Ad esempio, è possibile definire la rotazione del viso come vettore dal centro della bocca al centro degli occhi. Il codice seguente calcola questo vettore:
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 si conosce la direzione del viso, è possibile ruotare la cornice rettangolare del viso per allinearla più correttamente. Per ritagliare i visi in un'immagine, è possibile ruotare a livello di codice l'immagine in modo che i visi vengano sempre visualizzati in verticale.
Risultati dell'attributo Viso
Il codice seguente illustra come recuperare i dati dell'attributo viso richiesti nella chiamata originale.
foreach (var face in faces3)
{
var attributes = face.FaceAttributes;
var headPose = attributes.HeadPose;
var glasses = attributes.Glasses;
var qualityForRecognition = attributes.QualityForRecognition;
}
Per altre informazioni su ognuno degli attributi, vedere la guida concettuale rilevamento dei volti e attributi .
Passaggi successivi
In questa guida si è appreso come usare le varie funzionalità di rilevamento e analisi dei volti. Integrare quindi queste funzionalità in un'app per aggiungere dati sul viso dagli utenti.