Herramienta de línea de comandos

La herramienta earthengine es un programa de utilidad que te permite administrar los recursos y las tareas de Earth Engine desde la línea de comandos. Se instala automáticamente cuando instalas la API de Python. Para comprobar si la herramienta está instalada y funciona correctamente, escribe lo siguiente en una línea de comandos:

    earthengine

Si la herramienta está instalada correctamente, imprime un breve resumen de los comandos disponibles. Para obtener ayuda sobre un comando específico, usa lo siguiente:

    earthengine command -h

Cuando instalas la API de Python por primera vez, debes acceder con el comando authenticate que se describe a continuación. En las siguientes secciones, se describen los comandos disponibles con más detalle.

Credenciales de cuenta de servicio

Para usar la CLI con las credenciales de una cuenta de servicio, usa la marca service_account_file para apuntar a un archivo JSON que contenga la clave de la cuenta de servicio.

    earthengine --service_account_file=service_account_creds.json

Uso en Colab

La herramienta de línea de comandos de Earth Engine está preinstalada y lista para usarse en Google Colab.

Autenticación

Realiza la autenticación para cada sesión nueva de Colab o si la máquina virtual caduca por inactividad (las credenciales no se guardan en todas las sesiones).

Importa la biblioteca cliente de Python y llama a ee.Authenticate() para activar el flujo de autenticación. Sigue las indicaciones para completar la autenticación. El auth_mode predeterminado en Colab es colab. Consulta la Guía de autenticación para ver otras opciones.

import ee
ee.Authenticate()

Ejecución de comandos

Para ejecutar utilidades de línea de comandos, como la CLI de Earth Engine, debes anteponer llames de comando con un signo de exclamación.

!earthengine -h

Configura un proyecto de Cloud

Usa la opción --project para configurar un proyecto de Cloud para cada comando earthengine individual.

!earthengine --project my-project <command>

Como alternativa, establece un proyecto predeterminado que usarán todas las llamadas a earthengine con el comando set_project. El proyecto se agregará a un archivo de credenciales (~/.config/earthengine/credentials) y se usará para los comandos posteriores, a menos que se anule con la opción --project. Establece un proyecto predeterminado para cada sesión nueva de Colab o si la máquina virtual caduca por inactividad (las credenciales no se guardan en todas las sesiones).

!earthengine set_project my-project

Referencia de comandos

autenticar

Autentica la herramienta de línea de comandos y la biblioteca cliente de Python en Earth Engine. Ejemplo:

    earthengine authenticate

Earth Engine usa el protocolo OAuth 2.0 para autenticar clientes. El comando earthengine authenticate te guiará a través del proceso de autenticación con tu navegador web.

Deberás instalar gcloud si usas el modo de autenticación predeterminado de gcloud. Consulta otros modos de autenticación disponibles a través del parámetro auth_mode en la guía de autenticación.

acl

Imprime o actualiza la lista de control de acceso (LCA) de un recurso de Earth Engine. La LCA controla quién puede leer o escribir en un recurso. Ejemplos:

    earthengine acl get projects/my-project/assets/asset_id
    earthengine acl set public projects/my-project/assets/asset_id
    earthengine acl ch -u [e-mail]:R projects/my-project/assets/asset_id

El subcomando get imprime una descripción JSON de la ACL. El subcomando set establece una LCA proporcionada en un archivo con el mismo formato JSON. Para copiar una ACL de un recurso a otros, guarda el resultado de get y proporciónalo a set.

El subcomando set también acepta dos nombres de LCA especiales:

• private: Quita los permisos de todos, excepto del propietario.
• public: Otorga permiso de lectura a todos los usuarios.

El subcomando ch te permite realizar cambios individuales en una LCA. Para otorgar el permiso de lectura, especifica -u [e-mail]:R; para otorgar el permiso de escritura, especifica -u [e-mail]:W; y para quitar los permisos de un usuario, especifica -d [e-mail]. El identificador de usuario especial AllUsers se puede usar para otorgar o revocar permisos de lectura a todos los usuarios o desde ellos. (Ten en cuenta que revocar los permisos de AllUsers no revoca los permisos adicionales que también les hayas otorgado a usuarios individuales).

recurso

Imprime o actualiza los metadatos asociados con un activo de Earth Engine. Ejemplos:

    earthengine asset info projects/my-project/assets/asset_id
    earthengine asset set -p name=value projects/my-project/assets/asset_id

El subcomando info imprime información detallada sobre el activo, incluidos sus metadatos, en formato JSON. El subcomando set establece propiedades de metadatos individuales en un activo.

Los valores de las propiedades de metadatos que establezcas pueden ser números o cadenas. Cuando configures los nombres de las propiedades con la marca --property o -p, separa el nombre y el valor de la propiedad con un signo igual. El tipo de datos se detecta automáticamente, o bien puedes especificarlo de forma explícita anteponiendo el nombre de la propiedad con (string), (number) o (date). Por ejemplo, esto establece una propiedad con valor de cadena con el valor "42":

    earthengine asset set -p '(string)name=42' projects/my-project/assets/asset_id

(Las comillas en este ejemplo evitan que la shell interprete los paréntesis. Pueden ser necesarios o no, según el shell y la plataforma).

Para borrar una propiedad, configúrala como null sin un tipo:

    earthengine asset set -p name=null projects/my-project/assets/asset_id

Las propiedades de fecha son solo números que representan una cantidad de milisegundos desde la época de Unix (es decir, la medianoche del 1 de enero de 1970) y se pueden especificar directamente como un número o en uno de los siguientes formatos:

    YYYY-MM-DD
    YYYY-MM-DDThh:mm:ss
    YYYY-MM-DDThh:mm:ss.f

Se supone que la zona horaria es UTC. Puedes establecer las propiedades de hora de inicio y finalización especiales con las marcas --time_start y --time_end:

    earthengine asset set --time_start 1978-10-15T12:34:56 projects/my-project/assets/asset_id

cp

Copia un recurso. Ejemplo:

    earthengine cp projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

create

Crea carpetas y colecciones de imágenes nuevas. Ejemplo:

    earthengine create folder projects/my-project/assets/folder_id
    earthengine create collection projects/my-project/assets/collection_id

Usa el subcomando folder para crear carpetas y collection para crear colecciones de imágenes. Puedes especificar la opción -p para crear carpetas superiores de forma recursiva según sea necesario. Las carpetas y las imágenes recién creadas tienen LCA privadas de forma predeterminada.

ls

Muestra el contenido de una o más carpetas o colecciones. Ejemplo:

    earthengine ls users/username

La opción -l solicita un formato largo con más información sobre cada activo (actualmente, solo su tipo). Puedes especificar --max_items number (o -m para abreviar) para limitar la cantidad de elementos de cada carpeta o colección que enumeres:

    earthengine ls -m 10 projects/my-project/assets/my_large_collection

Si ejecutas el comando ls sin argumentos, se mostrará una lista de las carpetas de nivel superior que son de tu propiedad.

modelo

Herramienta con la que se pueden manipular los modelos guardados de TensorFlow.

model prepare

Prepara un modelo guardado para la entrega en Earth Engine. Específicamente, esto transforma tu SavedModel en un formato adecuado para procesar solicitudes de Earth Engine. (Obtén más información sobre SavedModel).

    earthengine model prepare my_source_dir my_dest_dir '{"Conv2D:0":"my_input_band"}' '{"Sigmoid:0":"my_output_band"}'

Obtén más información sobre los modelos de AI Platform aquí. Consulta un ejemplo completo aquí.

mv

Mueve un recurso o le cambia el nombre. Ejemplo:

    earthengine mv projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

project_config

Versión preliminar: La configuración del proyecto es una función de versión preliminar, por lo que las invocaciones deben incluir la palabra clave alpha.

Establece los valores de configuración del proyecto. Antes de usar este comando, asegúrate de configurar un proyecto con set_project.

get

Para ver la configuración de un proyecto, usa el subcomando get:

    earthengine alpha project_config get

Si tienes permiso para ver la configuración de la tarea por lotes del proyecto, el resultado contiene lo siguiente:

• maxConcurrentExports: Es un número que indica la cantidad máxima de tareas por lotes que se pueden ejecutar en paralelo en todos los usuarios para el proyecto determinado. De forma predeterminada, se establece en el máximo permitido por el plan de suscripción de la cuenta de facturación asociada.

Además, si tienes permiso para ver la configuración del plan, el resultado contendrá lo siguiente:

• planMaxConcurrentExports, un número que indica la cantidad máxima de tareas por lotes que se pueden ejecutar en paralelo en todos los usuarios y proyectos que usan la cuenta de facturación.

set

Para actualizar la configuración del proyecto, usa el subcomando set. Se pueden configurar los siguientes parámetros:

• max_concurrent_exports, para controlar el paralelismo de tareas por lotes máximo del proyecto
  • requiere los permisos correctos.

Por ejemplo, para configurar un proyecto de modo que solo permita que se ejecuten 10 tareas en paralelo para el proyecto determinado, haz lo siguiente:

    earthengine alpha project_config set --max_concurrent_exports=10

En el resultado, se muestra la configuración del proyecto actualizada, idéntica a la que muestra get.

Para obtener más información sobre el paralelismo de tareas por lotes, consulta la página Cuotas de Earth Engine.

rm

Borra uno o más recursos. Ejemplo:

    earthengine rm projects/my-project/assets/asset_id
    earthengine rm -r projects/my-project/assets/folder_id

Puedes usar la marca -r para borrar el contenido de una carpeta o colección de forma recursiva. Para mayor seguridad cuando borres varios recursos, puedes usar la marca --dry_run para verificar exactamente qué se borrará sin borrar nada.

set_project

Establece el proyecto de Google Cloud a través del cual se enrutan las solicitudes de procesamiento.

    earthengine set_project foo-project

Este comando es necesario antes de ejecutar comandos que requieran la funcionalidad de Cloud, por ejemplo, model.

tarea

Imprime información sobre tareas de larga duración o las administra. Ejemplos:

    earthengine task list
    earthengine task list -l
    earthengine task info TASK_ID
    earthengine task cancel TASK_ID

El subcomando list muestra información básica sobre las tareas que enviaste recientemente. La opción -l solicita un formato largo con más información sobre cada tarea. El subcomando info imprime información detallada sobre tareas individuales. El subcomando cancel cancela una o más tareas en ejecución.

upload

Sube imágenes o tablas de Google Cloud Storage a Earth Engine, o crea recursos respaldados por imágenes externas.

imagen

Para subir un recurso de imagen con la configuración predeterminada, sigue estos pasos:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id gs://bucket/image.tif

Si especificas varios archivos de imagen de entrada, se interpretarán como tarjetas de un solo recurso de imagen. Puedes obtener más información sobre las opciones para subir imágenes a Earth Engine en Cómo subir recursos de imagen: Opciones avanzadas.

Puedes especificar la política de reducción de pirámides con la marca --pyramiding_policy, que se puede establecer en una de las siguientes opciones: mean (la opción predeterminada), sample, mode, min o max. Esto controlará cómo Earth Engine genera la pirámide de versiones de resolución más baja de tu imagen:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --pyramiding_policy=sample gs://bucket/image.tif

Puedes usar --last_band_alpha para indicar que la máscara de la imagen debe tomarse de un canal alfa en la última banda:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --last_band_alpha gs://bucket/image.tif

Puedes especificar un valor sin datos con la marca --nodata_value. Esto enmascarará cualquier píxel de la imagen con ese valor:

    earthengine upload image --asset_id=users/myuser/asset --nodata_value=255 gs://bucket/image.tif

También puedes especificar propiedades de metadatos para establecer en el recurso con las mismas marcas que acepta el comando asset set descrito anteriormente. Las opciones también se describen en la guía del manifiesto de imagen.

mesa

Para subir un archivo Shapefile, CSV o TFRecord desde Google Cloud Storage a un activo de tabla de Earth Engine, puedes usar cualquiera de las siguientes opciones:

    earthengine upload table --asset_id=projects/my-project/assets/myUploadedShapefile gs://bucket/foo.shp
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedCSV gs://bucket/foo.csv
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedTFRecord gs://bucket/foo.tfrecord

Nota: Cuando subas archivos Shapefile, solo deberás especificar la ruta de acceso al archivo .shp. Los archivos .dbf, .shx y .prj relacionados deben estar presentes en la misma posición. Como alternativa, puedes especificar un archivo .zip que contenga los archivos necesarios.

Existen muchas opciones relacionadas con la forma en que se interpretan los archivos CSV y TFRecord. Para ver una lista completa de las opciones de carga de tablas, visita la guía de manifiesto de tablas o usa una de las siguientes opciones:

    earthengine upload table -h

external_image

Versión preliminar: Crear un recurso respaldado por una imagen externa es una función de versión preliminar, por lo que las invocaciones deben incluir la palabra clave alpha.

Para crear un recurso respaldado por una imagen externa, ejecuta el comando upload_image con un manifiesto:

earthengine alpha upload external_image --manifest /tmp/foo.json

Un ejemplo de manifiesto es el siguiente:

{
  "name": "projects/{project}/assets/cogdemo1",
  "tilesets": [
    { "id": "0", "sources": [{ "uris": ["gs://ee-docs-demos/COG_demo.tif"] }] }
  ],
  "properties": {
    "source": "https://code.earthengine.google.com/d541cf8b268b2f9d8f834c255698201d"
  },
  "startTime": "2016-01-01T00:00:00.000000000Z",
  "endTime": "2016-12-31T15:01:23.000000000Z"
}

Consulta la guía de GeoTIFF de Cloud y la guía de manifiesto de imágenes para obtener más detalles sobre la construcción del manifiesto.