In questo articolo daremo un’occhiata alle funzionalità di gesture detection fornite di serie dall’Intel RealSense SDK.
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

Il modulo PXCMHandModule

Tutta la gestione dell’interazione tra l’utente e la nostra applicazione attraverso l’utilizzo delle mani, avviene grazie al classe PXCMHandModule che incapsula il modulo di hand tracking.
La classe ha la seguente struttura:
 

Per poter ottenere una istanza valida di questa classe, abbiamo prima di tutto la necessità di comunicare all’SDK la nostra intenzione di abilitare l’utilizzo delle mani e lo possiamo fare utilizzando il metodo EnableHand di PXCMSenseManager:

SenseManager = PXCMSenseManager.CreateInstance()
SenseManager.EnableHand()

Una volta che abbiamo detto all’SDK che abbiamo intenzione di avvalerci della parte di hand tracking, possiamo recuperare effettivamente il modulo:

HandModule = SenseManager.QueryHand()

A questo punto, prima di poter effettivamente interrogare l’SDK (o gestire le callback di handle degli eventi sollevati dallo stesso) abbiamo la necessità di configurare il modulo stesso.

La classe PXCMHandConfiguration

La configurazione del modulo di hand tracking avviene tramite l’istanza della classe PXCMHandConfiguration ottenibile tramite il metodo CreateActiveConfiguration() della PXCMHandModule.
La classe di configurazione ha la seguente struttura:
 

In particolare, i metodi che ci interessano in questo contesto sono quelli che permettono di abilitare il riconoscimento delle gesture:
 
 

• EnableAllGestures: permette di abilitare il riconoscimento di tutte le gesture fornite dall’SDK contemporaneamente. Il parametro continousGesture consente di scegliere se l’SDK deve sollevare eventi solo all’inizio e alla fine del riconoscimento della singola gesture (false) o pure senza soluzione di continuità;
• EnableGesture: permette  di abilitare il riconoscimento di una singola gesture.

La versione corrente dell’SDK supporta le seguenti gesture:
 

Il seguente pezzo di codice ci consente di abilitare tutte le gesture:

Dim config = HandModule.CreateActiveConfiguration()
config.EnableAllGestures()
If config.ApplyChanges().IsSuccessful() Then'''
End If

Se volessimo, ad esempio, abilitare le sole gesture di ThumbUp o ThuimbDown, avremo:

Dim config = HandModule.CreateActiveConfiguration()
config.EnableGesture("thumb_down")
config.EnableGesture("thumb_up")
If config.ApplyChanges().IsSuccessful() Then'''
End If

E’ sempre necessario richiamare il metodo ApplyChanges() della configurazione per rendere effettive le configurazioni selezionate.
Una volta configurato il modulo di hand tracking, possiamo avviare la pipeline della classe PXCMSenseManager utilizzando il metodo Init():

If SenseManager.Init().IsError() Then
    MessageBox.Show("Errore nell'inizializzazione della camera")
    Close()
End If

La classe PXCMHandData

La classe PXCMHandData contiene i dati recuperati dall’SDK per quanto riguarda un frame di hand tracking.
E’ necessario creare l’istanza della classe PXCMHandData in maniera preventiva utilizzando il metodo CreateOutput() dell’hand module:

Dim handData = HandModule.CreateOutput()

Una volta fatto ciò possiamo chiedere alla PXCMSenseManager di acquisire il frame dalla camera e aggiorniamo l’istanza di PXCMHandData preventivamente creata:

If SenseManager.AcquireFrame().IsSuccessful() Then
    handData.Update()
    ElaborateSample(handData)
    SenseManager.ReleaseFrame()
End If

Il metodo Update della PXCMHandData aggiorna i riferimenti ai frame contenenti i dati delle gesture a cui accedere tramite l’istanza della classe.
La classe PXCMHandData ha la seguente struttura:
 

Come possiamo vedere, la classe, pur avendo la desinenza HandData, non contiene informazioni riguardo l’hand tracking ma fornisce dei metodi per recuperare effettivamente tali dati.
Nel caso che stiamo esaminando, i metodi che possiamo utilizzare sono i seguenti:
 

In particolare:

• IsGestureFired: permette di ottenere i dati della gesture specifica. Se la gesture è stata effettivamente riconosciuta, il risultato e true e il parametro out viene valorizzato con l’istanza di GestureData contenente i dati costitutivi della gesture. Se la gesture non è stata riconosciuta, viene restituito false;
• IsGestureFiredByHand: esattamente come il precedente ma consente anche di specificare quale mano ha eseguito la gesture;
• QueryFiredGestureData: permette di recuperare i dati della i-esima gesture riconosciuta. Se l’indice è maggiore o uguale al numero di gesture riconosciute (vedere il metodo QueryFiredGestureNumber) viene restituito un codice di errore STATUS_PARAM_UNSUPPORTED;
• QueryFiredGestureNumber: permette di conoscere il numero di gesture riconosciute dall’SDK all’interno del frame richiesto.

La classe GestureData, innestata nella PXCMHandData, ha la seguente struttura:
 

All’interno di questa troviamo il nome della gesture (name), lo stato (uno dei valori contenuti nell’enumerazione GestureStateType), l’id della mano che l’ha eseguita (handid), il timestamp in cui è stata rilevata e il numero del frame di cui fa parte.
 

Un esempio di come si possono elaborare tutte le gesture rilevate è il seguente in cui vengono visualizzate tutte le gesture il cui stato è GESTURE_STATE_START:

Private Sub ElaborateSample(handData As PXCMHandData)
    Dim index = 0
    Dim gestureData As PXCMHandData.GestureData = Nothing
    Dim numberOfGesture As Integer = handData.QueryFiredGesturesNumber()
    For handIndex = 0 To numberOfGesture - 1
        If handData.QueryFiredGestureData(handIndex, gestureData).IsSuccessful() Then
            If gestureData.state = PXCMHandData.GestureStateType.GESTURE_STATE_START Then
                DisplayGesture(gestureData)
            End If
        End If
    Next
End Sub

Conclusioni

Le funzionalità di gesture fornite di serie dall’SDK sono, come abbiamo visto, molto semplici da utilizzare ma debbono essere presi alcuni accorgimenti per evitare dei falsi positivi. Uno di questi è, ad esempio, l’abilitare solo le gesture strettamente indispensabili.
In tutti i casi, comunque, le gesture messe a disposizione sono sufficienti nella stragrande maggioranza dei casi.