L’articolo si riferisce alla versione 6.0.x dell’SDK di Intel® RealSense™ attualmente scaricabile all’indirizzo https://software.intel.com/en-us/intel-realsense-sdk/download

Cosa sono i Face Alerts

I Face Alerts fanno parte del gruppo delle funzionalità relative al face tracking e sono una sorta di “eventi” che vengono sollevati dall’SDK quando l’SDK stesso rileva degli accadimenti relativamente al face detection.
Per essere più precisi, il meccanismo utilizzato dall’SDK (lo vedremo in dettaglio più avanti nell’articolo) è più simile all’utilizzo della callback che non all’evento classico che gli sviluppatori .NET sono abituati a conoscere. 
Ricordiamo che l’SDK di RealSense ha un approccio molto C++ oriented ed è pensato per differenti linguaggi, da qui si capisce facilmente perché è stato scelto l’approccio con callback, più cross-language rispetto all’evento caratteristico dei soli linguaggi .NET.
L’SDK, quindi, richiama una callback da noi fornita (per chi non ha confidenza con il concetto di callback, lo può immaginare a tutti gli effetti come un gestore di evento) ogni volta che rileva un cambiamento dello stato del face detection (per esempio una faccia viene rilevata oppure una faccia esce da campo visivo) e ci fornisce non solo l’eventuale id della faccia rilevata ma anche il tipo di evento accaduto

Abilitare il modulo di Face

Come già detto in precedenza, i Face Alerts sono una funzionalità di face tracking e, quindi, abbiamo la necessità di attivare il modulo stesso attraverso l’istanza di PXCMSenseManager ed in particolare utilizzando il metodo EnableFace:

SenseManager = PXCMSenseManager.CreateInstance();
SenseManager.EnableStream(PXCMCapture.StreamType.STREAM_TYPE_COLOR, 1280, 720);
SenseManager.EnableFace();

Una volta abilitato l’utilizzo del modulo di face tracking, è necessario recuperare l’istanza del modulo stesso e lo possiamo fare utilizzando il metodo QueryFace della PXCMSenseManager:

FaceModule = SenseManager.QueryFace();

Il valore di ritorno del metodo è un’istanza della classe PXCMFaceModule.

Il modulo PXCMFaceModule

La classe PXCMFaceModule incapsula tutte le funzionalità che riguardano il face tracking degli utenti.
La sua struttura è la seguente:
 

 
La classe espone due metodi il cui utilizzo è il seguente:

• CreateActiveConfiguration: restituisce un oggetto di tipo che ci consente di configurare il modulo per decidere quali funzionalità vogliamo utilizzare (ad esempio il tracking o i landmarks);
• CreateOutput: permette di ottenere un oggetto di tipo che è l’handler attraverso il quale recuperare effettivamente i dati del viso che ci interessano.

Configurare il modulo di face tracking

La configurazione del modulo di face tracking (una volta abilitato tramite la PXCMSenseManager) avviene attraverso l’istanza della classe PXCMFaceConfiguration recuperata grazie al metodo CreateActiveConfiguration della classe PXCMFaceModule.
 

 
La classe di configurazione espone una serie di metodi che ci permettono di gestire gli alerts ed in particolare:

• EnableAlert: permette di abilitare il riconoscimento di un particolare alert (identificato dall’enumerazione PXCMFaceData.AlertData.AlertType). L’SDK richiamerà l’eventuale callback di gestione dell’alert solo se si verifica il particolare tipo di alert;
• EnableAllAlerts: abilita il rilevamento degli alert per tutti gli alert previsti dall’SDK;
• DisableAlert: disabilita il rilevamento degli alert per tutti gli alert previsti dall’SDK;
• DisableAllAlerts: disabilita il rilevamento di un particolare tipo di alert;
• SubscribeAlert: consente di impostare la callback di gestione dell’alert (vedremo in dettaglio in seguito);
• UnsubscribeAlert: consente di rimuovere la callback di gestione degli alert;
• IsAlertEnabled: permette di verificare se gli alert sono stati abilitati o meno.

Abbiamo la necessità di abilitare il face detection (agli alert sono riferiti, infatti alla presenza o meno di una faccia rilevata), impostare quali alert gestire (tramite i metodi Enable..) e sottoscrivere la callback di gestione degli stessi:

var config = FaceModule.CreateActiveConfiguration();
config.detection.isEnabled = true;
config.landmarks.isEnabled = false;
config.pose.isEnabled = false;
config.EnableAllAlerts();
config.strategy = PXCMFaceConfiguration.TrackingStrategyType.STRATEGY_FARTHEST_TO_CLOSEST;
PXCMFaceConfiguration.OnFiredAlertDelegate alertHandler = new PXCMFaceConfiguration.OnFiredAlertDelegate(OnAlertHandler);
config.SubscribeAlert(alertHandler);
if (config.ApplyChanges().IsSuccessful())
{
    if (SenseManager.Init().IsError())
    {
        MessageBox.Show("Errore nell'inizializzazione della camera");
        Close();
    }
}
config.Dispose();

La callback di gestione degli alert è impostata utilizzando la classe PXCMFAceConfiguration.OnFiredAlertDelegate la cui struttura è la seguente:

 
Per poter impostare quale “pezzo” di codice deve essere invocato al verificarsi di un alert, è necessario creare un oggetto di classe OnFireAlertDelegate passando, nel costruttore, il delegate della nostra funzione e, quindi, utilizzare questo oggetto nel metodo SubscriberAlert:

PXCMFaceConfiguration.OnFiredAlertDelegate alertHandler = new PXCMFaceConfiguration.OnFiredAlertDelegate(OnAlertHandler);
config.SubscribeAlert(alertHandler);
.
.
.
private void OnAlertHandler(PXCMFaceData.AlertData alertData)
{
    DisplayAlertData(alertData);
}

La firma della callback utilizzata prevede un oggetto PXCMFaceData.AlertData come parametro. Tale oggetto contiene tutti i dati relativi all’alert rilevato:

Il campo faceId contiene l’eventuale identificativo della faccia rilevata (nel caso di alert che contempli la presenza di una faccia), il campo timeStamp contiene il maker temporale (in 100 ns) relativo a quando si è verificato l’alert mentre il campo label contiene un valore dell’enumerazione AlertType (già vista in precedenza) che identifica l’alert. Nella versione corrente dell’SDK, i valori possibili per l’enumerazione AlertType sono:

• ALERT_NEW_FACE_DETECTED: è stata riconosciuto un nuovo volto nella scena;
• ALERT_FACE_OUT_OF_FOV: una faccia è uscita dal campo visivo della camera;
• ALERT_FACE_BACK_TO_FOV: una faccia è ritornata all’interno del campo visivo della camera;
• ALERT_FACE_OCCLUDED: una faccia è diventata non più visibile perché’ coperta da altro (ad esempio un utente mette le due mani davanti alla faccia);
• ALERT_FACE_NO_LONGER_OCCLUDED: una faccia è tornata visibile;
• ALERT_FACE_LOST: una faccia è stata persa dal tracking.

Gestire i frame

Come già visto in precedenti articoli riguardanti le funzionalità di Face Tracking, anche per quanto riguarda gli alert possiamo gestire il riconoscimento degli stessi utilizzando un approccio a polling.
Il primo step fondamentale è, come al solito, quello di ottenere l’istanza di PXCMFaceData che ci occorre per effettuare le opportune query allo scopo di ottenere le informazioni sugli alert:

PXCMFaceData faceData = FaceModule.CreateOutput();

La classe PXCMFaceData ha la seguente struttura:

 

 
I metodi che ci interessano in questo caso sono:

• Update: permette di aggiornare l’handler PXCMFaceData con i dati correnti recuperati dalla camera relativamente ai volti tracciati;
• IsAlertFired: consente di verificare se un alert di un certo tipo si è verificato o meno e, in caso affermativo, restituisce i dati dell’alert;
• IsAlertFiredByFace: permette di verificare se un determinato alert si è verificato per un viso (identificato dall’indice) e, in caso affermativo, restituisce i dati dell’alert;
• QueryFiredAlertData: restituisce i dati relativi all’i-esimo alert verificatosi a partire dal suo indice;
• QueryFiredAlertsNumber: consente di sapere il numero degli alert che si sono verificati;
• QueryAlertNameById: permette di recuperare il nome dell’alert a partire dal suo tipo.

Possiamo, dunque sfruttare i metodi della classe PXCMFaceData per ottenere, ad ogni frame recuperato tramite un’istanza della PXCMSenseManager, tutti gli alert generati:

if (SenseManager.AcquireFrame().IsSuccessful())
{
    faceData.Update();
    PXCMFaceData.AlertData alertData = null;
    for (int i = 0; i < faceData.QueryFiredAlertsNumber(); i++)
    {
        if (faceData.QueryFiredAlertData(i, out alertData).IsSuccessful())
            DisplayAlertData(alertData);
    }
    var sample = SenseManager.QuerySample();
}

Conclusioni

Il modulo di face tracking espone molte funzionalità interessanti e di pronto utilizzo nelle nostre applicazioni. Il modo con cui si approccia a ciascuna di esse è sempre simile, l’unica variazione è l’impostazione della configurazione (in modo da abilitare le funzionalità che ci servono) e l’utilizzo degli opportuni metodi della classe Face.
L’esempio riportato in questo articolo è disponibile all’indirizzo https://github.com/massimobonanni/RealSenseSamples in cui potete trovare tutte le demo presenti nei miei articoli su RealSense.