L'API Cloud Vision ti consente di comprendere il contenuto di un'immagine tramite l'incapsulamento di modelli avanzati di machine learning in una semplice API REST.
In questo lab, invieremo le immagini all'API Vision e rilevaremo il rilevamento di oggetti, volti e punti di riferimento.
Cosa imparerai a fare:
- Creazione di una richiesta API Vision e chiamata all'API con curl
- Utilizzare i metodi di rilevamento di etichette, Web, volti e punti di riferimento dell'API Vision
Cosa ti serve
Come utilizzerai questo tutorial?
Come giudichi la tua esperienza con Google Cloud Platform?
Configurazione automatica dell'ambiente
Se non hai ancora un Account Google (Gmail o Google Apps), devi crearne uno. Accedi alla console di Google Cloud Platform (console.cloud.google.com) e crea un nuovo progetto.
Ricorda l'ID progetto, un nome univoco in tutti i progetti Google Cloud (il nome sopra riportato è già stato utilizzato e non funzionerà per te). Vi verrà fatto riferimento più avanti in questo codelab come PROJECT_ID.
Il prossimo passaggio consiste nell'attivare la fatturazione in Cloud Console per utilizzare le risorse di Google Cloud.
L'esecuzione di questo codelab non dovrebbe costare più di qualche euro, ma potrebbe essere di più se decidi di utilizzare più risorse o se le lasci in esecuzione (vedi la sezione "pulizia" alla fine di questo documento).
I nuovi utenti di Google Cloud Platform sono idonei per una prova senza costi di 300$.
Fai clic sull'icona del menu nella parte in alto a sinistra dello schermo.
Seleziona API e servizi dal menu a discesa e fai clic su Dashboard.
Fai clic su Abilita API e servizi.
Cerca quindi "visione". nella casella di ricerca. Fai clic sull'API Google Cloud Vision:
Fai clic su Abilita per abilitare l'API Cloud Vision:
Attendi qualche secondo affinché venga attivata. Quando verrà attivato verrà visualizzato il messaggio:
Google Cloud Shell è un ambiente a riga di comando in esecuzione nel cloud. Questa macchina virtuale basata su Debian viene caricata con tutti gli strumenti di sviluppo di cui avrai bisogno (gcloud, bq, git e altri) e offre una home directory permanente da 5 GB. Useremo Cloud Shell per creare la nostra richiesta all'API Speech.
Per iniziare a utilizzare Cloud Shell, fai clic sull'icona "Attiva Google Cloud Shell" 
nell'angolo in alto a destra della barra dell'intestazione
All'interno di un nuovo frame nella parte inferiore della console si apre una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Attendi finché non viene visualizzato il messaggio utente@progetto:~$
Poiché utilizzeremo curl per inviare una richiesta all'API Vision, dobbiamo generare una chiave API da passare nell'URL della richiesta. Per creare una chiave API, vai alla sezione Credenziali di API e servizi in Cloud Console:
Seleziona Chiave API dal menu a discesa:
Ora copia la chiave appena generata.
Ora che hai una chiave API, salvala in una variabile di ambiente per evitare di dover inserire il valore della chiave API in ogni richiesta. Puoi eseguire questa operazione in Cloud Shell. Assicurati di sostituire <your_api_key> con la chiave che hai appena copiato.
export API_KEY=<YOUR_API_KEY>Creazione di un bucket Cloud Storage
Esistono due modi per inviare un'immagine all'API Vision per il rilevamento delle immagini: inviando all'API una stringa immagine con codifica base64 o passando l'URL di un file archiviato in Google Cloud Storage. Useremo un URL Cloud Storage. Creeremo un bucket Google Cloud Storage per archiviare le nostre immagini.
In Cloud Console, vai al browser Cloud Storage per il tuo progetto:
Quindi, fai clic su Crea bucket. Assegna al bucket un nome univoco, ad esempio l'ID progetto, e fai clic su Crea.
Carica un'immagine nel bucket
Fai clic con il pulsante destro del mouse sull'immagine di ciambelle che segue, quindi fai clic su Salva immagine con nome e salvala nella cartella Download come ciambelle.png.
Vai al bucket appena creato nel browser di archiviazione e fai clic su Carica file. Poi seleziona donuts.png.
Dovresti vedere il file nel tuo bucket:
Modifica l'autorizzazione dell'immagine.
Fai clic su Aggiungi articolo.
Aggiungi una nuova Entità di Group e un Nome di allUsers:
Fai clic su Salva.
Ora che hai il file nel tuo bucket, puoi creare una richiesta API Vision, passando l'URL di questa immagine alle ciambelle.
Nel tuo ambiente Cloud Shell, crea un file request.json con il codice riportato di seguito, assicurandoti di sostituire my-bucket-name con il nome del bucket Cloud Storage che hai creato. Puoi creare il file utilizzando uno degli editor a riga di comando che preferisci (nano, vim, emacs) o utilizzare l'editor di Orion integrato in Cloud Shell:
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/donuts.png"
}
},
"features": [
{
"type": "LABEL_DETECTION",
"maxResults": 10
}
]
}
]
}La prima funzionalità dell'API Cloud Vision che esploreremo è il rilevamento delle etichette. Questo metodo restituisce un elenco di etichette (parole) dei contenuti nell'immagine.
Adesso possiamo chiamare l'API Vision con curl:
curl -s -X POST -H "Content-Type: application/json" --data-binary @request.json https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}La tua risposta dovrebbe essere simile alla seguente:
{
"responses": [
{
"labelAnnotations": [
{
"mid": "/m/01dk8s",
"description": "powdered sugar",
"score": 0.9436922
},
{
"mid": "/m/01wydv",
"description": "beignet",
"score": 0.7160288
},
{
"mid": "/m/06_dn",
"description": "snow",
"score": 0.71219236
},
{
"mid": "/m/02wvn_6",
"mid": "/m/0bp3f6m",
"description": "fried food",
"score": 0.7075312
},
{
"mid": "/m/02wvn_6",
"description": "ricciarelli",
"score": 0.5625
},
{
"mid": "/m/052lwg6",
"description": "baked goods",
"score": 0.53270763
}
]
}
]
}L'API è stata in grado di identificare il tipo specifico di ciambelle che sono beignets. Bene! Per ogni etichetta trovata dall'API Vision, restituisce un elemento description con il nome dell'elemento. Restituisce inoltre un score, un numero compreso tra 0 e 100 che indica il grado di certezza che la descrizione corrisponde al testo nell'immagine. Il valore mid corrisponde alla metà dell'elemento nel Knowledge Graph di Google. Puoi utilizzare mid quando chiami l'API Knowledge Graph per ricevere ulteriori informazioni sull'elemento.
Oltre a ricevere etichette sulla nostra immagine, l'API Vision può anche cercare su Internet ulteriori dettagli sulla nostra immagine. Grazie al metodo webDetection dell'API, otteniamo molti dati interessanti:
- Un elenco di entità trovate nella nostra immagine, basate su contenuti di pagine con immagini simili
- URL di immagini con corrispondenza esatta e parziale trovate sul Web, insieme agli URL di tali pagine
- URL di immagini simili, ad esempio la ricerca di un'immagine inversa
Per provare il rilevamento web, utilizzeremo la stessa immagine dei beignet dall'alto, per cui basta modificare una sola riga del file request.json (puoi anche avventurarti nell'ignoto e utilizzare un'immagine completamente diversa). Nell'elenco delle funzionalità, modifica il tipo da LABEL_DETECTION a WEB_DETECTION. request.json dovrebbe avere il seguente aspetto:
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/donuts.png"
}
},
"features": [
{
"type": "WEB_DETECTION",
"maxResults": 10
}
]
}
]
}Per inviarlo all'API Vision, puoi utilizzare lo stesso comando curl del precedente (basta premere la freccia su in Cloud Shell):
curl -s -X POST -H "Content-Type: application/json" --data-binary @request.json https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}Analizziamo la risposta, iniziando con webEntities. Ecco alcune delle entità restituite da questa immagine:
"webEntities": [
{
"entityId": "/m/01hyh_",
"score": 0.7155,
"description": "Machine learning"
},
{
"entityId": "/m/01wydv",
"score": 0.48758492,
"description": "Beignet"
},
{
"entityId": "/m/0105pbj4",
"score": 0.3976,
"description": "Google Cloud Platform"
},
{
"entityId": "/m/02y_9m3",
"score": 0.3782,
"description": "Cloud computing"
},
...
]
Questa immagine è stata riutilizzata in molte presentazioni sulle nostre API Cloud ML, ed è per questo che l'API ha trovato le entità "Machine learning", "Google Cloud Platform" e "Cloud computing".
Se inseriamo gli URL in fullMatchingImages, partialMatchingImages e pagesWithMatchingImages, noteremo che molti URL rimandano a questo sito del codelab (super meta!).
Supponiamo di voler trovare altre immagini di beignet, ma non le stesse immagini. Questa è la parte visuallySimilarImages della risposta API utile. Ecco alcune delle immagini visivamente simili che ha trovato:
"visuallySimilarImages": [
{
"url": "https://igx.4sqi.net/img/general/558x200/21646809_fe8K-bZGnLLqWQeWruymGEhDGfyl-6HSouI2BFPGh8o.jpg"
},
{
"url": "https://spoilednyc.com//2016/02/16/beignetszzzzzz-852.jpg"
},
{
"url": "https://img-global.cpcdn.com/001_recipes/a66a9a6fc2696648/1200x630cq70/photo.jpg"
},
...
]Possiamo accedere a tali URL per visualizzare le immagini simili:
Figo! E ora probabilmente vorrai davvero un beignet (scusa). Si tratta di una ricerca simile a quella di un'immagine su Google Immagini:
ma con Cloud Vision possiamo accedere a questa funzionalità con un'API REST di facile utilizzo e integrarla nelle nostre applicazioni.
A seguire, esploreremo i metodi di rilevamento del volto e dei punti di riferimento dell'API Vision. Il metodo di rilevamento del volto restituisce i dati sui volti rilevati in un'immagine, incluse le emozioni dei volti e la loro posizione nell'immagine. Il rilevamento dei punti di riferimento può identificare punti di riferimento comuni (e oscuri): restituisce il nome del punto di riferimento, le coordinate di latitudine e longitudine e la posizione del punto in cui è stato identificato.
Carica una nuova immagine
Per utilizzare questi due nuovi metodi, caricheremo una nuova immagine con volti e punti di riferimento nel nostro bucket Cloud Storage. Fai clic con il pulsante destro del mouse sull'immagine seguente, quindi fai clic su Salva immagine con nome e salvala nella cartella Download come selfie.png.
Quindi caricalo nel bucket Cloud Storage come hai fatto nel passaggio precedente, assicurandoti di selezionare la casella di controllo "Condividi pubblicamente".
Aggiornamento della nostra richiesta
A questo punto, aggiorneremo il file request.json in modo che includa l'URL della nuova immagine e che utilizzi il rilevamento di volti e punti di riferimento anziché il rilevamento delle etichette. Assicurati di sostituire my-bucket-name con il nome del nostro bucket Cloud Storage:
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/selfie.png"
}
},
"features": [
{
"type": "FACE_DETECTION"
},
{
"type": "LANDMARK_DETECTION"
}
]
}
]
}Chiamare l'API Vision e analizzare la risposta
Ora puoi chiamare l'API Vision utilizzando lo stesso comando curl che hai utilizzato sopra:
curl -s -X POST -H "Content-Type: application/json" --data-binary @request.json https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}Diamo un'occhiata all'oggetto faceAnnotations nella risposta. Noterai che l'API restituisce un oggetto per ogni volto trovato nell'immagine, in questo caso tre. Ecco una versione ritagliata della nostra risposta:
{
"faceAnnotations": [
{
"boundingPoly": {
"vertices": [
{
"x": 669,
"y": 324
},
...
]
},
"fdBoundingPoly": {
...
},
"landmarks": [
{
"type": "LEFT_EYE",
"position": {
"x": 692.05646,
"y": 372.95868,
"z": -0.00025268539
}
},
...
],
"rollAngle": 0.21619819,
"panAngle": -23.027969,
"tiltAngle": -1.5531756,
"detectionConfidence": 0.72354823,
"landmarkingConfidence": 0.20047489,
"joyLikelihood": "POSSIBLE",
"sorrowLikelihood": "VERY_UNLIKELY",
"angerLikelihood": "VERY_UNLIKELY",
"surpriseLikelihood": "VERY_UNLIKELY",
"underExposedLikelihood": "VERY_UNLIKELY",
"blurredLikelihood": "VERY_UNLIKELY",
"headwearLikelihood": "VERY_LIKELY"
}
...
}
}boundingPoly ci fornisce le coordinate x,y intorno al volto nell'immagine. fdBoundingPoly è una scatola più piccola di boundingPoly, che racchiude la parte del viso della pelle. landmarks è un array di oggetti per ogni viso (potrebbero non esserti sfuggiti!). Questo ci indica il tipo di punto di riferimento, insieme alla posizione 3D di quell'elemento (x,y,z), dove la coordinata z è la profondità. I valori rimanenti ci danno ulteriori dettagli sul volto, incluse le probabilità di gioia, dolore, rabbia e sorpresa. L'oggetto sopra riportato è per la persona più lontana nell'immagine: si vede che sta rindo un volto stupido che spiega joyLikelihood di POSSIBLE.
Ora diamo un'occhiata alla parte landmarkAnnotations della nostra risposta:
"landmarkAnnotations": [
{
"mid": "/m/0c7zy",
"description": "Petra",
"score": 0.5403372,
"boundingPoly": {
"vertices": [
{
"x": 153,
"y": 64
},
...
]
},
"locations": [
{
"latLng": {
"latitude": 30.323975,
"longitude": 35.449361
}
}
]In questo caso, l'API Vision ha potuto determinare che l'immagine è stata scattata a Petra, il che è davvero incredibile poiché gli indizi visivi nell'immagine sono minimi. I valori in questa risposta dovrebbero essere simili a quelli della risposta labelAnnotations sopra riportata.
Abbiamo il mid del punto di riferimento, il suo nome (description), insieme a un valore score sicuro. boundingPoly mostra l'area geografica nell'immagine in cui è stato identificato il punto di riferimento. Il tasto locations indica le coordinate di latitudine e longitudine di questo punto di riferimento.
Abbiamo esaminato i metodi di rilevamento di etichette, volti e punti di riferimento dell'API Vision, ma ce ne sono altri che non abbiamo esplorato. Esplora i documenti per scoprire gli altri tre:
- Rilevamento di loghi: identifica i loghi comuni e la loro posizione in un'immagine.
- Rilevamento di SafeSearch: determina se un'immagine include o meno contenuti espliciti. Questa funzionalità è utile per qualsiasi applicazione con contenuti generati dagli utenti. Puoi filtrare le immagini in base a quattro fattori: contenuti per adulti, medici, violenti e di spoofing.
- Rilevamento testo: esegui la funzionalità OCR per estrarre il testo dalle immagini. Questo metodo consente anche di identificare la lingua del testo presente in un'immagine.
Hai imparato ad analizzare le immagini con l'API Vision. In questo esempio, hai trasmesso all'API l'URL Google Cloud Storage della tua immagine. In alternativa, puoi trasmettere una stringa codificata in base64 della tua immagine.
Cosa abbiamo trattato
- Chiamata all'API Vision con curl passando l'URL di un'immagine in un bucket Cloud Storage
- Utilizzare l'API Vision, l'etichetta web, il volto, il volto e i metodi di rilevamento dei punti di riferimento
Passaggi successivi
- Consulta i tutorial dell'API Vision nella documentazione.
- Trova un esempio di API Vision nel tuo linguaggio preferito
- Prova i codelab sull'API Speech e sull'API Natural Language.