Instalação do Python

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Suporte ao Python

A biblioteca de cliente Python do Earth Engine é compatível com as versões do Python com suporte do Google Cloud. O suporte é atualizado anualmente de acordo com o cronograma de lançamentos do Python (PEP 602; Status das versões do Python). O uso de versões do Python sem suporte pode causar falhas de autenticação, comportamento inesperado ou falha em determinadas operações.

Opções de instalação

Se você estiver usando o Google Colab, a versão mais recente da biblioteca de cliente Python do Earth Engine já estará instalada (pelo pip). Teste o notebook a seguir para começar a usar o Earth Engine e o Colab:

Executar no Google Colab

Ver código-fonte no GitHub

Se você não usa o Colab, a biblioteca de cliente do Earth Engine pode ser instalada e atualizada manualmente no seu sistema usando o conda (recomendado) ou o pip:

pip install earthengine-api

pip install earthengine-api --upgrade

Importação de pacotes

O pacote da API Python é chamado de ee. Ele precisa ser importado e inicializado para cada nova sessão e script do Python:

import ee

Autenticação e inicialização

Antes de usar a biblioteca de cliente Python do Earth Engine, é necessário autenticar e usar as credenciais resultantes para inicializar o cliente Python. Execute:

ee.Authenticate()

Isso vai selecionar o melhor modo de autenticação para seu ambiente e solicitar que você confirme o acesso aos scripts. Para inicializar, você precisa fornecer um projeto que seja seu ou que tenha permissões para usar. Esse projeto será usado para executar todas as operações do Earth Engine:

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

Consulte o guia de autenticação para resolver problemas e saber mais sobre os modos de autenticação e os projetos do Cloud.

Olá, mundo!

Confira um script curto para testar se você está pronto para trabalhar com o Earth Engine.

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

Sintaxe

As APIs Python e JavaScript acessam a mesma funcionalidade do lado do servidor, mas as expressões do lado do cliente (saiba mais sobre o cliente e o servidor) podem variar devido a diferenças na sintaxe do idioma. A tabela a seguir inclui uma lista das diferenças de sintaxe comuns que você vai encontrar ao trabalhar com a API Python em relação à API JavaScript.

function myFun(arg) {
  return arg;
}

var myFun = function(arg) {
  return arg;
};

def my_fun(arg):
  return arg

var foo = col.map(function(arg) {
  return arg;
});

foo = col.map(lambda arg: arg)

var myVar = 'var';

my_var = 'var'

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)

var foo = my.really()
              .reallyLong()
              .methodChain();

foo = (my.really()
       .reallyLong()
       .methodChain())

var dic = {'key': value};
var dic = {key: value};

dic = {'key': value}

var value = dic.key;
var value = dic['key'];

value = dic['key']

// 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)

var t = true;
var f = false;

t = True
f = False

var na = null;

na = None

//

#

Objetos de data

Defina e manipule objetos de data do lado do cliente com o módulo datetime. Inclua o módulo no script:

import datetime

Converta ee.Date em data do lado do cliente:

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

Converter a data do lado do cliente em ee.Date:

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

Exportação de dados

A exportação de dados com a API Python requer o uso do módulo ee.batch, que fornece uma interface para as funções Export. Transmita argumentos de parâmetro como faria com a API JavaScript, observando as diferenças indicadas na tabela de sintaxe acima. As tarefas de exportação precisam ser iniciadas chamando o método start() em uma tarefa definida. Consulte o status de uma tarefa chamando o método status() nela. O exemplo a seguir demonstra como exportar um objeto ee.Image.

Crie uma tarefa de exportação:

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')

Inicie uma tarefa de exportação:

task.start()

Verificar o status da tarefa de exportação:

task.status()

O resultado de task.status() é um dicionário que contém informações como o estado da tarefa e o ID dela.

{
  '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'
}

É possível monitorar o progresso da tarefa usando o campo state. Consulte a página Ambientes de processamento para conferir uma listagem de valores de state e mais informações sobre o ciclo de vida da tarefa.

Como imprimir objetos

A impressão de um objeto do Earth Engine no Python imprime a solicitação serializada para o objeto, não o objeto em si. Consulte a página Cliente x servidor para entender o motivo.

Chame getInfo() nos objetos do Earth Engine para transferir o objeto desejado do servidor para o 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())

Objetos da interface

O módulo ui do Earth Engine só está disponível pelo editor de código da API JavaScript. Use bibliotecas de terceiros para elementos da interface em Python. Bibliotecas como geemap, Folium e ipyleaflet fornecem a exibição de mapas interativos, enquanto a criação de gráficos pode ser feita com Matplotlib, Altair ou seaborn, para citar alguns. Confira exemplos no notebook de configuração do Earth Engine no Colab para usar o geemap e o Matplotlib.

Python no guia para desenvolvedores

O código Python está incluído em todo o Guia do desenvolvedor do Earth Engine. Quando disponíveis, os exemplos de código podem ser visualizados clicando na guia "Colab (Python)" na parte de cima dos blocos de código. As páginas de guia também podem incluir botões na parte de cima para executar a página como um notebook do Colab ou visualizá-la no GitHub. Os exemplos de código Python devem ser executados usando o Google Colab. A exploração de mapas e objetos interativos é processada pela biblioteca geemap. A biblioteca de cliente Python da Earth Engine e o geemap são pré-instalados no Colab.

Configuração do Earth Engine

Para executar o código Python, é necessário importar, autenticar e inicializar a biblioteca do Earth Engine. Os comandos a seguir são usados nos exemplos. Consulte a página Autenticação e inicialização para conferir alternativas.

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

Análise interativa com geemap

A biblioteca geemap é usada para mostrar blocos de mapa e imprimir representações ricas de objetos do Earth Engine. A biblioteca depende respectivamente de ipyleaflet e eerepr para esses recursos. A biblioteca geemap e as dependências dela são pré-instaladas no Google Colab. Importe-a para cada sessão.

import geemap.core as geemap

As classes de dados geográficos do Earth Engine, como ee.Image e ee.FeatureCollection, podem ser visualizadas usando o objeto geemap.Map. Primeiro, defina o objeto do mapa. Em seguida, adicione camadas ou altere a janela de visualização.

# 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)