La API de Cloud Vision le permite comprender el contenido de una imagen mediante el encapsulamiento de modelos de aprendizaje automáticos potentes en una API de REST sencilla.
En este lab, enviará imágenes a la API de Vision para que esta identifique objetos, rostros y puntos de referencia.
Qué aprenderás
- Crear una solicitud a la API de Vision y llamar a la API con curl
- Usar los métodos de detección de etiquetas, Web, rostro y punto de referencia de la API de Vision
Qué necesitarás:
¿Cómo usarás este instructivo?
¿Cómo calificarías tu experiencia con Google Cloud Platform?
Configuración del entorno a su propio ritmo
Si aún no tienes una Cuenta de Google (Gmail o Google Apps), debes crear una. Accede a Google Cloud Platform Console (console.cloud.google.com) y crea un proyecto nuevo:
Recuerde el ID de proyecto, un nombre único en todos los proyectos de Google Cloud (el nombre anterior ya se encuentra en uso y no lo podrá usar). Se mencionará más adelante en este codelab como PROJECT_ID.
A continuación, debes habilitar la facturación en Cloud Console para usar los recursos de Google Cloud.
Ejecutar este codelab debería costar solo unos pocos dólares, pero su costo podría aumentar si decides usar más recursos o si los dejas en ejecución (consulta la sección “Limpiar” al final de este documento).
Los usuarios nuevos de Google Cloud Platform son aptos para obtener una prueba gratuita de USD 300.
Haga clic en el ícono de menú ubicado en la parte superior izquierda de la pantalla.
Selecciona API y servicios en la lista desplegable y haz clic en Panel.
Haga clic en Habilitar API y servicios.
Luego, busca &vision en el cuadro de búsqueda. Haga clic en API de Google Cloud Vision:
Haga clic en Habilitar para habilitar la API de Cloud Vision:
Espera a que se habilite. Cuando la habilites, verás lo siguiente:
Google Cloud Shell es un entorno de línea de comandos que se ejecuta en la nube. Esta máquina virtual basada en Debian está cargada con todas las herramientas para desarrolladores que necesitarás (gcloud, bq, git y otras) y ofrece un directorio principal persistente de 5 GB. Usaremos Cloud Shell para crear la solicitud a la API de Speech.
Para comenzar a usar Cloud Shell, haz clic en el ícono "Activar Google Cloud Shell" 
en la esquina superior derecha de la barra del encabezado.
Se abrirá una sesión de Cloud Shell en un marco nuevo en la parte inferior de la consola, que mostrará una línea de comandos. Espera hasta que aparezca el mensaje user@project:~$
Debido a que usaremos curl para enviar una solicitud a la API de Vision, necesitaremos generar una clave de API a fin de pasar la URL de la solicitud. Para crear una clave de API, navega a la sección Credenciales de API y servicios en Cloud Console:
En el menú desplegable, seleccione Clave de API:
A continuación, copie la clave generada.
Ahora que tiene una clave de API, guárdela en una variable de entorno para no tener que ingresar el valor de la clave de API en cada solicitud. Puede hacerlo en Cloud Shell. Asegúrate de reemplazar <your_api_key> por la clave que acabas de copiar.
export API_KEY=<YOUR_API_KEY>Cree un bucket de Cloud Storage
Existen dos maneras de enviar una imagen a la API de Vision para la detección de la imagen: enviar a la API una string de imagen codificada en base64 o pasarla a la URL de un archivo almacenado en Google Cloud Storage. Usaremos una URL de Cloud Storage. Crearemos un bucket de Google Cloud Storage para almacenar nuestras imágenes.
Navega al navegador de Storage de tu proyecto en Cloud Console:
A continuación, haga clic en Crear depósito. Asigne un nombre único a su bucket (como el ID de su proyecto) y haga clic en Crear.
Suba una imagen a su bucket
Haz clic con el botón derecho en la siguiente imagen de donas y, luego, haz clic en Save image as (Guardar imagen) y guárdala en la carpeta Descargas como donuts.png.
Navegue al depósito que acaba de crear en el navegador de Storage y haga clic en Subir archivos. Luego, seleccione donuts.png.
Debería ver el archivo en su bucket:
A continuación, edita el permiso de la imagen.
Haz clic en Agregar elemento.
Agrega una Entity nueva de Group y un Name de allUsers:
Haz clic en Guardar.
Ahora que el archivo está en su bucket, ya puede crear una solicitud a la API de Vision y pasarle la URL de esta imagen de donas.
En su entorno de Cloud Shell, cree un archivo request.json con el siguiente código y asegúrese de reemplazar my-bucket-name por el nombre del bucket de Cloud Storage que creó. Puede crear el archivo con uno de sus editores de línea de comandos preferidos (nano, vim, emacs) o usar el editor de Orion integrado en Cloud Shell:
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/donuts.png"
}
},
"features": [
{
"type": "LABEL_DETECTION",
"maxResults": 10
}
]
}
]
}La primera función de la API de Cloud Vision que exploraremos es la detección de etiquetas. Este método mostrará una lista de etiquetas (palabras) de lo que hay en su imagen.
Ahora estamos listos para llamar a la API de 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}Su respuesta debería ser similar a la siguiente:
{
"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
}
]
}
]
}La API pudo identificar el tipo específico de donas que se conoce (como beignets). ¡Genial! Por cada etiqueta que la API de Vision encontró, muestra un description con el nombre del elemento. También muestra un score, un número del 0 al 100, que indica el grado de confianza de que la descripción coincide con el contenido de la imagen. El valor mid se asigna al elemento en el Gráfico de conocimiento de Google. Puedes usar el mid cuando llames a la API de Knowledge Graph para obtener más información sobre el elemento.
Además de obtener etiquetas sobre lo que se muestra en la imagen, la API de Vision también puede realizar búsquedas en Internet para obtener más detalles sobre la imagen. Mediante el método webDetection de la API, obtenemos muchos datos interesantes:
- Una lista de entidades encontradas en nuestra imagen, según el contenido de páginas con imágenes similares
- URL de imágenes que coinciden total o parcialmente y que fueron encontradas en la Web, junto con las URL de dichas páginas
- URL de imágenes similares, como realizar una búsqueda de imagen inversa
Para probar la detección en la Web, usaremos la misma imagen de beignets de arriba, por lo que todo lo que necesitamos cambiar es una línea en nuestro archivo request.json (también puedes aventurarte en lo desconocido y usar una imagen completamente diferente). En la lista de funciones, solo cambia el tipo de LABEL_DETECTION a WEB_DETECTION. request.json ahora debería verse de la siguiente manera:
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/donuts.png"
}
},
"features": [
{
"type": "WEB_DETECTION",
"maxResults": 10
}
]
}
]
}Para enviarlo a la API de Vision, puede usar el mismo comando curl que antes (solo presione la flecha hacia arriba en 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}Analicemos la respuesta y comience con webEntities. Estas son algunas de las entidades que mostró esta imagen:
"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"
},
...
]
Esta imagen se volvió a usar en varias presentaciones en nuestras API de Cloud ML. Por eso, la API encontró las entidades “Aprendizaje automático”, “Computación en la nube” y “Computación en la nube”.
Si inspeccionamos las URL en fullMatchingImages, partialMatchingImages y pagesWithMatchingImages, notamos que muchas de las URL apuntan a este sitio de codelab (¡súper meta!).
Supongamos que queremos encontrar otras imágenes de beignets, pero no exactamente las mismas. Ahí es donde la parte visuallySimilarImages de la respuesta de la API resulta útil. Estas son algunas de las imágenes visualmente similares que encontró:
"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"
},
...
]Podemos navegar a esas URL para ver las imágenes similares:
Genial. Y ahora probablemente quieras un beignet (perdón). Esto es similar a buscar una imagen en Google Imágenes:
Pero con Cloud Vision, podemos acceder a esta funcionalidad con una API de REST fácil de usar, además de integrarla a nuestras aplicaciones.
A continuación, exploraremos los métodos de detección de rostro y punto de referencia de la API de Vision. El método de detección de rostro muestra datos de rostros encontrados en una imagen, que incluyen las emociones de los rostros y su ubicación en la imagen. La detección de puntos de referencia puede identificar puntos de referencia comunes (y desconocidos), es decir, muestra el nombre del punto de referencia, las coordenadas de latitud y longitud, y la ubicación de donde se identificó el punto de referencia en una imagen.
Sube una imagen nueva
Para usar estos dos métodos nuevos, vamos a subir una imagen nueva con rostros y puntos de referencia a nuestro bucket de Cloud Storage. Haz clic con el botón derecho en la siguiente imagen. Luego, haz clic en Guardar imagen como y guárdala en la carpeta Descargas como selfie.png.
Luego, súbelo a tu bucket de Cloud Storage de la misma manera que lo hiciste en el paso anterior y asegúrate de marcar la casilla de verificación "Compartir públicamente".
Actualiza nuestra solicitud
A continuación, actualizaremos nuestro archivo request.json para incluir la URL de la imagen nueva y usar la detección de rostro y punto de referencia en lugar de la detección de etiquetas. Asegúrese de reemplazar my-bucket-name por el nombre de nuestro bucket de Cloud Storage:
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/selfie.png"
}
},
"features": [
{
"type": "FACE_DETECTION"
},
{
"type": "LANDMARK_DETECTION"
}
]
}
]
}Llamar a la API de Vision y analizar la respuesta
Ahora está listo para llamar a la API de Vision con el mismo comando curl que usó antes:
curl -s -X POST -H "Content-Type: application/json" --data-binary @request.json https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}Veamos primero el objeto faceAnnotations en nuestra respuesta. Notará que la API muestra un objeto para cada rostro encontrado en la imagen (en este caso, tres). Esta es una versión recortada de nuestra respuesta:
{
"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"
}
...
}
}El objeto boundingPoly nos proporciona las coordenadas x-y alrededor del rostro en la imagen. fdBoundingPoly es una caja más pequeña que boundingPoly y codifica en la parte de la piel del rostro. landmarks es un array de objetos para cada rasgo facial (es posible que algunos no los conozcas). Esto nos indica el tipo de punto de referencia, junto con la posición 3D de ese rasgo (coordenadas x,y,z), donde la coordenada z es la profundidad. Los valores restantes nos proporcionan detalles sobre el rostro, incluida la probabilidad de alegría, tristeza, enojo y sorpresa. El objeto anterior es para la persona más lejana de la imagen. Puedes ver cómo se ve un rostro gracioso que explica el joyLikelihood de POSSIBLE.
Ahora veamos la landmarkAnnotations parte de nuestra respuesta:
"landmarkAnnotations": [
{
"mid": "/m/0c7zy",
"description": "Petra",
"score": 0.5403372,
"boundingPoly": {
"vertices": [
{
"x": 153,
"y": 64
},
...
]
},
"locations": [
{
"latLng": {
"latitude": 30.323975,
"longitude": 35.449361
}
}
]Aquí, la API de Vision pudo decir que esta imagen se tomó en Petra. Eso es impresionante dado que las pistas visuales en la imagen son mínimas. Los valores en esta respuesta deben ser similares a la respuesta labelAnnotations anterior.
Se obtiene la mid del punto de referencia, su nombre (description), junto con una score de confianza. boundingPoly muestra la región de la imagen en la que se identificó el punto de referencia. La tecla locations indica las coordenadas de latitud y longitud de este punto de referencia.
Analizamos los métodos de detección de etiquetas, rostro y punto de referencia de la API de Vision, pero hay otros tres que no vimos. Consulte los documentos para aprender sobre ellos:
- Detección de logotipo: identifique logotipos comunes y su ubicación en la imagen.
- Búsqueda segura: determine si una imagen incluye contenido explícito o no. Esto es útil para cualquier aplicación con contenido generado por usuarios. Puede filtrar imágenes en función de cuatro factores: contenido adulto, médico, violento y falso.
- Detección de texto: ejecute el OCR para extraer texto de las imágenes. Este método incluso puede identificar el idioma del texto presente en una imagen.
Aprendiste a analizar imágenes con la API de Vision. En este ejemplo, pasó a la API la URL de Google Cloud Storage de su imagen. De forma alternativa, puede pasar una string codificada en base64 de su imagen.
Temas abordados
- Cómo llamar a la API de Vision con curl si le pasa la URL de una imagen almacenada en un bucket de Cloud Storage
- Usar los métodos de detección de etiquetas, Web, rostro y punto de referencia de la API de Vision
Próximos pasos
- Consulte los instructivos de la API de Vision en la documentación.
- Encuentra una muestra de la API de Vision en tu lenguaje favorito.
- Prueba los codelabs API de voz y API de Natural Language.