Instalación de Python

Compatibilidad con Python

La biblioteca cliente de Python de Earth Engine es compatible con las versiones de Python que admite Google Cloud. La compatibilidad se actualiza anualmente según el programa de lanzamientos de Python (PEP 602; Estado de las versiones de Python). El uso de versiones de Python no compatibles puede causar fallas de autenticación, un comportamiento inesperado o fallas de ciertas operaciones.

Opciones de instalación

Si usas Google Colab, ya se instaló la versión más reciente de la biblioteca cliente de Earth Engine para Python (a través de pip). Prueba el siguiente notebook para comenzar a usar Earth Engine y Colab:

Logotipo de Colab Ejecutar en Google Colab Logotipo de GitHub Ver código fuente en GitHub

Si no usas Colab, la biblioteca cliente de Earth Engine se puede instalar y actualizar manualmente en tu sistema con conda (recomendado) o pip:


Instala la API en un entorno de Python arbitrario con pip. Desde una terminal o un símbolo del sistema, haz lo siguiente:

pip install earthengine-api

Una vez instalada, puedes importar, autenticar e inicializar la API de Earth Engine como se describe aquí.

Actualiza la API:

pip install earthengine-api --upgrade

Importación de paquetes

El paquete de la API de Python se llama ee. Se debe importar y, luego, inicializar para cada sesión y secuencia de comandos de Python nuevas:

import ee

Autenticación e inicialización

Antes de usar la biblioteca cliente de Python de Earth Engine, debes autenticarte y usar las credenciales resultantes para inicializar el cliente de Python. Ejecuta lo siguiente: 

ee.Authenticate()

Se seleccionará el mejor modo de autenticación para tu entorno y se te solicitará que confirmes el acceso de tus secuencias de comandos. Para inicializarlo, deberás proporcionar un proyecto que te pertenezca o para el que tengas permisos de uso. Este proyecto se usará para ejecutar todas las operaciones de Earth Engine: 

ee.Initialize(project='my-project')

Consulta la guía de autenticación para solucionar problemas y obtener más información sobre los modos de autenticación y los proyectos de Cloud.

¡Hola, mundo!

Esta es una secuencia de comandos breve para probar que tienes todo listo para trabajar con Earth Engine. 

import ee
ee.Authenticate()
ee.Initialize(project='my-project')
print(ee.String('Hello from the Earth Engine servers!').getInfo())

Sintaxis

Tanto las APIs de Python como las de JavaScript acceden a la misma funcionalidad del servidor, pero las expresiones del cliente (obtén más información sobre el cliente y el servidor) pueden variar debido a las diferencias de sintaxis del lenguaje. En la siguiente tabla, se incluye una lista de las diferencias comunes de sintaxis que encontrarás cuando trabajes con la API de Python en relación con la API de JavaScript.

Diferencias comunes de sintaxis entre JavaScript y Python
Propiedad JavaScript Python
Definición de la función 
function myFun(arg) {
  return arg;
}

var myFun = function(arg) {
  return arg;
};
 
def my_fun(arg):
  return arg
Asignación de funciones anónimas 
var foo = col.map(function(arg) {
  return arg;
});
 
foo = col.map(lambda arg: arg)
Definición de variables 
var myVar = 'var';
 
my_var = 'var'
Operadores lógicos 
var match = such.and(that);
var match = such.or(that);
var match = such.not(that);
 
match = such.And(that)
match = such.Or(that)
match = such.Not(that)
Cadena de métodos de varias líneas 
var foo = my.really()
              .reallyLong()
              .methodChain();
 
foo = (my.really()
       .reallyLong()
       .methodChain())
Claves del diccionario 
var dic = {'key': value};
var dic = {key: value};
 
dic = {'key': value}
Acceso a objetos de diccionario 
var value = dic.key;
var value = dic['key'];
 
value = dic['key']
Definición del argumento de la función 
// Positional arguments.
var foo = fun(argX, argY, argZ);
// Keyword arguments object.
var foo = fun({y: argY});
 
# Positional arguments.
foo = fun(arg_x, arg_y, arg_z)
# Keyword arguments dictionary.
foo = fun(**{'y': arg_y})
# Keyword arguments.
foo = fun(x=arg_x, z=arg_z)
Booleano 
var t = true;
var f = false;
 
t = True
f = False
Valores nulos 
var na = null;
 
na = None
Comentario 
//
 
#

Objetos de fecha

Define y manipula objetos de fecha del cliente con el módulo datetime. Incluye el módulo en la secuencia de comandos:

import datetime

Convierte ee.Date a fecha del cliente:

ee_date = ee.Date('2020-01-01')
py_date = datetime.datetime.utcfromtimestamp(ee_date.getInfo()['value']/1000.0)

Convierte la fecha del cliente a ee.Date:

py_date = datetime.datetime.utcnow()
ee_date = ee.Date(py_date)

Exporta datos

Para exportar datos con la API de Python, debes usar el módulo ee.batch, que proporciona una interfaz a las funciones Export. Pasa los argumentos de los parámetros como lo harías con la API de JavaScript, teniendo en cuenta las diferencias que se indican en la tabla de sintaxis anterior. Para iniciar las tareas de exportación, debes llamar al método start() en una tarea definida. Para consultar el estado de una tarea, llama al método status(). En el siguiente ejemplo, se muestra cómo exportar un objeto ee.Image.

Crea una tarea de exportación:

task = ee.batch.Export.image.toDrive(image=my_image,  # an ee.Image object.
                                     region=my_geometry,  # an ee.Geometry object.
                                     description='mock_export',
                                     folder='gdrive_folder',
                                     fileNamePrefix='mock_export',
                                     scale=1000,
                                     crs='EPSG:4326')

Inicia una tarea de exportación:

task.start()

Verifica el estado de la tarea de exportación:

task.status()

El resultado de task.status() es un diccionario que contiene información como el estado de la tarea y su ID. 

{
  'state': 'READY',
  'description': 'my_export_task',
  'creation_timestamp_ms': 1647567508236,
  'update_timestamp_ms': 1647567508236,
  'start_timestamp_ms': 0,
  'task_type': 'EXPORT_IMAGE',
  'id': '56TVJIZABUMTD5CJ5YHTMYK4',
  'name': 'projects/earthengine-legacy/operations/56TVJIZABUMTX5CJ5HHTMYK4'
}

Puedes supervisar el progreso de las tareas con el campo state. Consulta la página de entornos de procesamiento para obtener una lista de valores de state y más información sobre el ciclo de vida de las tareas.

Cómo imprimir objetos

Cuando se imprime un objeto de Earth Engine en Python, se imprime la solicitud serializada del objeto, no el objeto en sí. Consulta la página Cliente frente a servidor para comprender el motivo.

Llama a getInfo() en los objetos de Earth Engine para obtener el objeto deseado del servidor al cliente:

# Load a Landsat image.
img = ee.Image('LANDSAT/LT05/C02/T1_L2/LT05_034033_20000913')

# Print image object WITHOUT call to getInfo(); prints serialized request instructions.
print(img)

# Print image object WITH call to getInfo(); prints image metadata.
print(img.getInfo())
 Ten en cuenta que getInfo() es una operación síncrona, lo que significa que la ejecución de las expresiones después de la llamada a getInfo() se bloquea hasta que se muestra el resultado al cliente. Además, las solicitudes de muchos datos o cálculos costosos pueden mostrar un error o colgarse. En general, la práctica recomendada es exportar los resultados y, una vez que se completen, importarlos a una secuencia de comandos nueva para un análisis más detallado.

Objetos de la IU

El módulo ui de Earth Engine solo está disponible a través del editor de código de la API de JavaScript. Usa bibliotecas de terceros para elementos de la IU en Python. Las bibliotecas como geemap, Folium y ipyleaflet proporcionan una visualización de mapas interactivos, mientras que los gráficos se pueden crear con Matplotlib, Altair o seaborn, entre otros. Consulta los ejemplos en el notebook de configuración de Earth Engine en Colab para usar geemap y Matplotlib.

Python en la Guía para desarrolladores

El código de Python se incluye en toda la Guía para desarrolladores de Earth Engine. Cuando estén disponibles, podrás ver los ejemplos de código haciendo clic en la pestaña “Colab (Python)” en la parte superior de los bloques de código. Las páginas de guía también pueden incluir botones en la parte superior para ejecutar la página como un notebook de Colab o verla en GitHub. Los ejemplos de código de Python están diseñados para ejecutarse con Google Colab. La biblioteca geemap controla la exploración de objetos y mapas interactivos. Tanto la biblioteca cliente de Python de Earth Engine como geemap están preinstaladas en Colab.

Configuración de Earth Engine

Para ejecutar código de Python, debes importar la biblioteca de Earth Engine, autenticarla y inicializarla. Los siguientes comandos se usan en los ejemplos (consulta la página Autenticación e inicialización para ver alternativas).

import ee
ee.Authenticate()
ee.Initialize(project='my-project')

Exploración interactiva con geemap

La biblioteca geemap se usa para mostrar mosaicos de mapas y para imprimir representaciones enriquecidas de objetos de Earth Engine. La biblioteca depende, respectivamente, de ipyleaflet y eerepr para estas funciones. La biblioteca geemap y sus dependencias están preinstaladas en Google Colab. Importala en cada sesión.

import geemap.core as geemap

Las clases de datos geográficos de Earth Engine, como ee.Image y ee.FeatureCollection, se pueden ver con el objeto geemap.Map. Primero, define el objeto de mapa. Luego, agrégale capas o altera su viewport.

# Initialize a map object.
m = geemap.Map()

# Define an example image.
img = ee.Image.random()

# Add the image to the map.
m.add_layer(img, None, 'Random image')

# Display the map (you can call the object directly if it is the final line).
display(m)