Cognitive Services in Unity

In questo semplice tutorial vedremo come integrare i servizi cognitivi e in particolar modo la Computer Vision all'interno di una applicazione sviluppata con il motore grafico Unity.
Se sei interessato all'integrazione di altri servizi di Azure ti potrebbe interessare anche questo articolo.
Il risultato finale sarà il seguente:

Il codice sorgente di questo esempio è disponibile su un repository github qui.
L'esempio è come si suol dire un esempio giocattolo, ovvero vuole solo dimostrare come integrare il servizio semplicemente.
Consideriamo un'applicazione che deve riconoscere il Colosseo in una fotografia.

Per prima cosa cominciamo con il creare la risorsa su Azure.
Collegarsi al sito portal.azure.com e selezionare Crea una risorsa.

Cercare una risorsa di tipo Visione artificiale e crearla.

Durante la creazione ci vengono richieste le seguenti informazioni:

  • Sottoscrizione
    Rappresenta la sottoscrizione da utilizzare per il bot che stiamo creando

  • Gruppo di risorse
    Rappresenta un contenitore con risorse correlate per una soluzione Azure da noi organizzato
    Creiamo un gruppo di risorse test_unity

  • Area
    Scegliamo l'area dell'Europa occidentale con nome testunity-area

  • Piano tariffario
    Definisce il piano di pagamento per l'utilizzo del servizio
    Scegliamo F0

Una volta creata e distribuita la risorsa è possibile ottenere le chiavi di accesso private; esse ci permetteranno di connetterci al servizio tramite API.

La risorsa è pronta per essere richiamata tramite API.
Per avere maggiori informazioni è possibile accedere al seguente indirizzo.
Qui è possibile avere tutte le informazioni riguardo a come richiamare il servizio e come ricevere - e in che formato è - la risposta.
L'url di richiesta è https://{endpoint}/vision/v2.1/analyze[?visualFeatures][&details][&language] dove

  • endpoint
    È l'endpoint della richiesta. Si può utilizzare quello present su Azure oppure https://westeurope.api.cognitive.microsoft.com/

  • visualFeatures
    È una stringa che indica quali tipi di funzionalità visive restituire.

  • details
    È una stringa che indica i dettagli specifici del dominio da restituire.

  • language
    È la lingua di risposta che di default è impostata su en.

L'url che ci interessa è https://westeurope.api.cognitive.microsoft.com/vision/v3.0/analyze?details=Landmarks

Vediamo ora come impostare i componenti nella scena di Unity.
Essa contiene i seguenti gameobject:

  • Main Camera
    È un oggetto di default della scena di Unity utile per il render

  • EventSystem
    È responsabile di elaborare e gestire gli eventi all'interno di una scena

  • Canvas
    Rappresenta la tela sulla quale sono disegnati i diversi elementi dell'interfaccia utente

  • Background
    È l'immagine di sfondo

  • Button
    È il bottone che scatena la chiamata al server per l'analisi dell'immagine

  • Response
    È la sezione in cui sarà mostrato il messaggio di risposta

  • Panel
    È contenitore dei tre loghi sottostanti

La logica di funzionamento è la seguente.
Quando si effettua il clic sul pulsante Button è richiamata una funzione nel code-behind che si interfaccia con il server.
Si trasforma l'immagine una sequenza di byte, si compone il messaggio di richiesta e si invia.
Si rimane in attesa di ottenere la risposta e la si mostra a schermo interagendo con i componenti della UI.
Un oggetto Button implementa il metodo On Click().
Si noti come all'evento On Click() sia stato associato il metodo CallApi.Analyze.
CallApi è una classe realizzata e assegnata come componente all'oggetto EventSystem.

Prima di analizzare la classe CallApi è utile vedere un messaggio di risposta del server.
Un esempio è disponibile qui.
Per facilitare l'analisi di questo file è possibile effettuare il mapping dal file JSON creato a un oggetto istanziato.
Per fare ciò è necessario creare una classe che rispecchia la struttura del file JSON. Per semplificare tale meccanismo è possibile usare diversi tool online che prendono in input un esempio di file JSON. Personalmente ho usato diverse volte json2csharp.com.

Analizziamo ora la classe CallApi.
Commentiamo passo per passo ciò che avviene durante la chiamata alla funzione Analyze();

  • imageName = Path.Combine(Application.streamingAssetsPath, "foto.jpeg");
byte[] bytesImage = UnityEngine.Windows.File.ReadAllBytes(imageName);
    Si acqiuisisce l'immagine da un file e la si trasforma in una sequenza di byte. 

  • var headers = new Dictionary() {
  { "Ocp-Apim-Subscription-Key", visionKey },
  { "Content-Type", "application/octet-stream" }
};
    Si costruisce l'header del pacchetto da inviare inserendoci la chiave segreta presente su Azure. 

  • WWW www = new WWW(resourceURL, bytesImage, headers);
yield return www;
responseData = www.text;
    Si invia la richiesta e si aspetta la risposta contenuta in response data 

  • JSONApi answer = JsonConvert.DeserializeObject(www.text);
    Tramite la libreria Newtonsoft.Json e la classe a somiglianza del JSON è possibile istanziare come oggetto la risposta data dal server

Tutto è pronto per essere utilizzato.
Ci vediamo al prossimo tutorial!
Non scordare di seguirmi sui canali social!
👇

Riguardo me

Mario Cuomo
Unity Student Ambassadors & Microsoft Student Ambassadors

Seguimi sui social