La API de Cloud Vision te permite comprender el contenido de una imagen a través del encapsulamiento de modelos de aprendizaje automático 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
- Cómo 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 de autoaprendizaje
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, deberás habilitar la facturación en la consola de Cloud 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.
Haz clic en el ícono de menú ubicado en la parte superior izquierda de la pantalla.
Selecciona APIs & services en el menú desplegable y haz clic en Panel.
Haz clic en Habilitar APIs y servicios.
Luego, busca "visión" en el cuadro de búsqueda. Haz clic en Google Cloud Vision API:
Haz clic en Habilitar para habilitar la API de Cloud Vision:
Espera unos segundos para que se habilite. Verás este mensaje cuando se habilite:
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 de desarrollo que necesitarás (gcloud, bq, git y otras) y ofrece un directorio principal persistente de 5 GB. Usaremos Cloud Shell para crear nuestra 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 de 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:~$
Dado que usaremos curl para enviar una solicitud a la API de Vision, tendremos que generar una clave de API para pasar la URL de nuestra solicitud. Para crear una clave de API, navega a la sección Credenciales de APIs y servicios en Cloud Console:
En el menú desplegable, selecciona Clave de API:
A continuación, copia la clave generada.
Ahora que tienes una clave de API, guárdala en una variable de entorno para no tener que ingresar el valor de la clave de API en cada solicitud. Puedes hacer esto en Cloud Shell. Asegúrate de reemplazar <your_api_key> por la clave que acabas de copiar.
export API_KEY=<YOUR_API_KEY>Crea un bucket de Cloud Storage
Hay dos maneras de enviar una imagen a la API de Vision para que la detecte: enviar a la API una cadena de imagen codificada en base64 o pasarle a la API 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 en la consola de Cloud de tu proyecto:
A continuación, haz clic en Crear bucket. Asígnale a tu bucket un nombre único (como el ID de tu proyecto) y haz clic en Crear.
Sube una imagen a tu bucket
Haz clic con el botón derecho en la siguiente imagen de donas. Luego, haz clic en Guardar imagen como y guárdala en la carpeta Descargas como donuts.png.
Navega al bucket que acabas de crear en el navegador de Storage y haz clic en Subir archivos. Luego, selecciona donuts.png.
Deberías ver el archivo en tu bucket:
A continuación, edita el permiso de la imagen.
Haz clic en Agregar elemento.
Agrega una nueva entidad de Group y un nombre 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 tu entorno de Cloud Shell, crea un archivo request.json con el siguiente código. Asegúrate de reemplazar my-bucket-name por el nombre del bucket de Cloud Storage que creaste. Puedes crear el archivo con uno de tus editores de línea de comandos preferidos (nano, vim, emacs) o usar el editor integrado Orion en Cloud Shell:
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/donuts.png"
}
},
"features": [
{
"type": "LABEL_DETECTION",
"maxResults": 10
}
]
}
]
}El primer atributo 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 tu imagen.
Ahora ya puedes 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 (beignets). ¡Qué bien! Por cada etiqueta que la API de Vision encuentra, muestra un description con el nombre del elemento. También devuelve un score, un número entre 0 y 100 que indica qué tan seguro está de que la descripción coincide con lo que está en la imagen. El valor mid se asigna al MID del elemento en el Gráfico de conocimiento de Google. Puedes usar mid cuando llames a la API de Gráfico de conocimiento para obtener más información sobre el elemento.
Además de obtener etiquetas sobre lo que hay en nuestra imagen, la API de Vision también puede realizar búsquedas en Internet para obtener detalles adicionales sobre nuestra imagen. A través del método webDetection de la API, recibimos mucha información interesante:
- 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 que se mostró anteriormente, por lo que solo debemos cambiar una línea en nuestro archivo request.json (también puedes aventurarte en lo desconocido y utilizar una imagen completamente diferente). En la lista de atributos, solo cambia el tipo de LABEL_DETECTION a WEB_DETECTION. request.json 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, puedes usar el mismo comando curl que antes (solo presiona 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. Comencemos 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 reutilizó en muchas presentaciones sobre nuestras APIs de Cloud ML, razón por la cual la API encontró las entidades “Aprendizaje automático”, “Google Cloud Platform” y “Computación en la nube”.
Si inspeccionamos las URLs en fullMatchingImages, partialMatchingImages y pagesWithMatchingImages, notaremos que muchas de las URLs apuntan al sitio de este codelab (¡qué coincidencia!).
Supongamos que quieres encontrar otras imágenes de beignets, pero no exactamente las mismas. Aquí es donde resulta útil la parte visuallySimilarImages de la respuesta de la API. 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 URLs para ver las imágenes similares:
Genial. Y, ahora, probablemente tengas muchas ganas de un beignet (¡perdón!). Esto es parecido a buscar por una imagen en Google Imágenes:
Sin embargo, con Cloud Vision, podemos acceder a esta funcionalidad con una API de REST fácil de usar y, a su vez, integrarla a nuestras aplicaciones.
A continuación, exploraremos los métodos de detección de rostro y de 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). Muestra el nombre del punto de referencia, las coordenadas de latitud y longitud, y la ubicación donde se identificó el punto de referencia en una imagen.
Cómo subir una imagen nueva
Para usar estos dos métodos nuevos, subamos 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úbela a tu bucket de Cloud Storage del mismo modo en que lo hiciste en el paso anterior. Asegúrate de marcar la casilla de verificación "Compartir públicamente".
Actualizamos 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úrate de reemplazar my-bucket-name por el nombre de tu bucket de Cloud Storage:
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/selfie.png"
}
},
"features": [
{
"type": "FACE_DETECTION"
},
{
"type": "LANDMARK_DETECTION"
}
]
}
]
}Cómo llamar a la API de Vision y analizar la respuesta
Ya tienes todo listo para llamar a la API de Vision con el mismo comando curl que usaste antes:
curl -s -X POST -H "Content-Type: application/json" --data-binary @request.json https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}Primero, veamos el objeto faceAnnotations en nuestra respuesta. Notarás que la API muestra un objeto para cada rostro encontrado en la imagen (en este caso, tres). Aquí puedes ver una versión reducida 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 boundingPoly nos proporciona las coordenadas X e Y alrededor del rostro en la imagen. fdBoundingPoly es una caja más pequeña que boundingPoly y codifica la parte de la piel del rostro. landmarks es un array de objetos para cada rasgo facial (¡algunos de los cuales puede que no conozcas!). Esto nos indica el tipo de punto de referencia, junto con la posición 3D de ese rasgo (coordenadas x,y,z), en el que la coordenada z es la profundidad. Los valores restantes nos proporcionan más detalles sobre el rostro, incluida la probabilidad de alegría, tristeza, enojo y sorpresa. El objeto anterior es para la persona que se encuentra más atrás en la imagen: puedes ver que está haciendo una especie de gesto gracioso que explica el joyLikelihood de POSSIBLE.
A continuación, veamos la parte landmarkAnnotations 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 deberían ser similares a la respuesta labelAnnotations anterior.
Obtenemos el mid del punto de referencia, su nombre (description) y una confianza score. boundingPoly muestra la región de la imagen en la que se identificó el punto de referencia. La clave locations nos proporciona 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 exploramos aún. Consulta los documentos para obtener información sobre los otros tres:
- 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, pasaste a la API la URL de Google Cloud Storage de tu 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
- Cómo usar los métodos de detección de etiquetas, web, rostro y punto de referencia de la API de Vision
Próximos pasos
- Consulta 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 de la API de Speech y la API de Natural Language.