Chiamare l'API di rilevamento

Questa guida spiega come usare l'API di rilevamento viso per estrarre gli attributi da una determinata immagine. Verranno illustrati i diversi modi per configurare il comportamento di questa API in modo da soddisfare le proprie esigenze.

I frammenti di codice sono scritti in C# usando la libreria client del servizio Viso di Azure per intelligenza artificiale. 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 istruzioni di avvio rapido.

Inviare dati al servizio

Per trovare i visi e ottenere le relative posizioni in un'immagine, chiamare DetectAsync. Come input accetta una stringa URL o il file binario dell'immagine non elaborata.

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

Il servizio restituisce un oggetto FaceDetectionResult, su cui è possibile eseguire una query per recuperare diversi tipi di informazioni, come specificato di seguito.

Per informazioni su come analizzare la posizione e le dimensioni del viso, vedere FaceRectangle. In genere, il 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 del 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 del viso deve essere archiviato nel server. Dopo la scadenza specificata, l'ID del 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 volto, come le pupille o la punta del naso. Per ottenere i dati dei punti di riferimento del viso, impostare il parametro detectionModel su FaceDetectionModel.Detection03 e il parametro returnFaceLandmarks su 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;

Recuperare gli attributi del viso

Oltre ai rettangoli e ai punti di riferimento del viso, l'API di rilevamento dei volti è in grado di 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 FaceDetectionModel.Detection03 e il parametro returnFaceAttributes su un elenco di valori FaceAttributeType Enum.

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;

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(
        (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;
}

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 blur = attributes.Blur;
    var headPose = attributes.HeadPose;
    var mask = attributes.Mask;
    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.

• Esercitazione: aggiungere utenti a un servizio Viso

Articoli correlati

• Documentazione di riferimento (REST)
• Documentazione di riferimento (.NET SDK)