Installazione di Python

Supporto di Python

La libreria client Python di Earth Engine è compatibile con le versioni di Python supportate da Google Cloud. Il supporto viene aggiornato annualmente in base alla programmazione delle release di Python (PEP 602; Stato delle versioni di Python). L'utilizzo di versioni di Python non supportate potrebbe causare errori di autenticazione, comportamenti imprevisti o il fallimento di determinate operazioni.

Opzioni di installazione

Se utilizzi Google Colab, la versione più recente della libreria client Earth Engine per Python è già stata installata (tramite pip). Prova il seguente notebook per iniziare a utilizzare Earth Engine e Colab:

Esegui in Google Colab

Visualizza il codice sorgente su GitHub

Se non utilizzi Colab, la libreria client di Earth Engine può essere installata e aggiornata manualmente sul tuo sistema utilizzando conda (opzione consigliata) o pip:

pip install earthengine-api

pip install earthengine-api --upgrade

Importazione del pacchetto

Il pacchetto dell'API Python si chiama ee. Deve essere importato e inizializzato per ogni nuova sessione e script Python:

import ee

Autenticazione e inizializzazione

Prima di utilizzare la libreria client Python di Earth Engine, devi eseguire l'autenticazione e utilizzare le credenziali risultanti per inizializzare il client Python. Esegui:

ee.Authenticate()

Verrà selezionata la modalità di autenticazione migliore per il tuo ambiente e ti verrà chiesto di confermare l'accesso per i tuoi script. Per l'inizializzazione, dovrai fornire un progetto di tua proprietà o di cui disponi delle autorizzazioni per l'utilizzo. Questo progetto verrà utilizzato per eseguire tutte le operazioni di Earth Engine:

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

Consulta la guida sull'autenticazione per la risoluzione dei problemi e per scoprire di più sulle modalità di autenticazione e sui progetti Cloud.

Ciao mondo!

Ecco un breve script per verificare che sia tutto pronto per lavorare con Earth Engine.

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

Sintassi

Sia le API Python che quelle JavaScript accedono alla stessa funzionalità lato server, ma le espressioni lato client (scopri di più su client e server) possono variare a causa delle differenze di sintassi del linguaggio. La tabella seguente include un elenco delle differenze di sintassi comuni che riscontrerai quando utilizzi l'API Python rispetto all'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

//

#

Oggetti Date

Definisci e manipola gli oggetti Data lato client con il modulo datetime. Includi il modulo nello script:

import datetime

Converti ee.Date in data lato client:

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

Converti la data lato client in ee.Date:

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

Esportazione di dati

L'esportazione dei dati con l'API Python richiede l'utilizzo del modulo ee.batch che fornisce un'interfaccia alle funzioni Export. Passa gli argomenti del parametro come faresti con l'API JavaScript, facendo attenzione alle differenze indicate nella tabella della sintassi sopra. Le attività di esportazione devono essere avviate chiamando il metodo start() su un'attività definita. Esegui una query sullo stato di un'attività chiamando il metodo status(). L'esempio seguente mostra l'esportazione di un oggetto ee.Image.

Crea un'attività di esportazione:

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

Avvia un'attività di esportazione:

task.start()

Controlla lo stato dell'attività di esportazione:

task.status()

Il risultato di task.status() è un dizionario contenente informazioni come lo stato dell'attività e il relativo 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'
}

Puoi monitorare l'avanzamento delle attività utilizzando il campo state. Consulta la pagina Ambienti di elaborazione per un elenco dei valori di state e ulteriori informazioni sul ciclo di vita delle attività.

Stampa di oggetti

La stampa di un oggetto Earth Engine in Python stampa la richiesta serializzata per l'oggetto, non l'oggetto stesso. Per comprendere il motivo, consulta la pagina Client e server.

Chiama getInfo() sugli oggetti Earth Engine per ottenere l'oggetto desiderato dal server al client:

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

Oggetti UI

Il modulo ui di Earth Engine è disponibile solo tramite l'editor di codice dell'API JavaScript. Utilizza librerie di terze parti per gli elementi dell'interfaccia utente in Python. Librerie come geemap, Folium e ipyleaflet forniscono la visualizzazione di mappe interattive, mentre i grafici possono essere creati con Matplotlib, Altair o seaborn, per citarne alcuni. Consulta gli esempi nel notebook di configurazione di Earth Engine in Colab per l'utilizzo di geemap e Matplotlib.

Python nella Guida per gli sviluppatori

Il codice Python è incluso nella Guida per gli sviluppatori di Earth Engine. Se disponibili, gli esempi di codice possono essere visualizzati facendo clic sulla scheda "Colab (Python)" nella parte superiore dei blocchi di codice. Le pagine delle guide possono includere anche pulsanti in alto per eseguire la pagina come blocco note di Colab o visualizzarla su GitHub. Gli esempi di codice Python devono essere eseguiti utilizzando Google Colab. L'esplorazione di mappe e oggetti interattivi è gestita dalla libreria geemap. Sia la libreria client Python di Earth Engine sia geemap sono preinstallate in Colab.

Configurazione di Earth Engine

Per eseguire il codice Python devi importare la libreria Earth Engine, autenticarti e inizializzarla. Nei seguenti esempi vengono utilizzati i seguenti comandi (per le alternative, consulta la pagina Autenticazione e inizializzazione).

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

Esplorazione interattiva con geemap

La libreria geemap viene utilizzata per visualizzare i tessere della mappa e stampare rappresentazioni dettagliate degli oggetti Earth Engine. La libreria dipende rispettivamente da ipyleaflet e eerepr per queste funzionalità. La libreria geemap e le relative dipendenze sono preinstallate in Google Colab; importala in ogni sessione.

import geemap.core as geemap

Le classi di dati geografici di Earth Engine, come ee.Image e ee.FeatureCollection, possono essere visualizzate utilizzando l'oggetto geemap.Map. Innanzitutto, definisci l'oggetto mappa. Aggiungi livelli o modifica l'area visibile.

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