Client e server

Le librerie client di Earth Engine per Python e JavaScript traducono complesse analisi geospaziali in richieste di Earth Engine. Il codice scritto per una libreria client può contenere una combinazione di riferimenti a oggetti e variabili lato client che rappresentano oggetti lato server.

Nota: il recupero dei valori dagli oggetti lato server richiede una chiamata a getInfo(). Nell'editor di codice JavaScript, getInfo() viene chiamato automaticamente quando viene stampato un oggetto lato server. Nella libreria client Python, devi chiamare esplicitamente getInfo() quando stampi oggetti lato server. Alcune librerie, come geemap o eerepr, potrebbero chiamare automaticamente getInfo() per te quando mostri un oggetto in un notebook simile a Jupyter. Nei seguenti esempi di codice Python, getInfo() viene chiamato esplicitamente per chiarire meglio quando vengono stampati gli oggetti client e server.

È importante distinguere gli oggetti Earth Engine da altri oggetti o primitive di Python o JavaScript che potrebbero essere presenti nel codice. Puoi manipolare gli oggetti sul server manipolando gli oggetti "proxy" lato client nello script. Puoi riconoscere un oggetto proxy come qualsiasi elemento che inizia con ee. Questi oggetti proxy di Earth Engine non contengono dati effettivi e sono solo handle per gli oggetti sul server. Per iniziare, considera un oggetto stringa lato client (che NON è un oggetto proxy):

Editor di codice (JavaScript)

var clientString = 'I am a String';
print(typeof clientString);  // string

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

client_string = 'I am a String'
print(type(client_string))  # str

Dall'output puoi vedere che il client (il browser web o il notebook) ha interpretato questo codice ed eseguito, determinando che la variabile è di tipo string. Supponiamo ora che tu voglia che Earth Engine possa fare qualcosa con questa stringa. Per farlo, devi racchiudere la stringa in un contenitore adeguato e inviarla a Google. Questo contenitore è l'oggetto proxy. Ecco un esempio:

Editor di codice (JavaScript)

var serverString = ee.String('I am not a String!');
print(typeof serverString);  // object
print('Is this an EE object?',
    serverString instanceof ee.ComputedObject);  // true

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

server_string = ee.String('I am not a String!')
print(type(server_string))  # ee.ee_string.String
print(
    'Is this an EE object?', isinstance(server_string, ee.ee_string.String)
)  # True

Dall'output, osserva che ee.String è un object, NON un string. Nello specifico, si tratta di un ee.computedObject, che significa che è un oggetto proxy per qualcosa sul server. Pensa a ee.Thing come al modo per mettere qualcosa in un contenitore per l'invio a Google. Il cliente non sa cosa contiene il contenitore, ma puoi scoprirlo stampandolo:

Editor di codice (JavaScript)

print(serverString);  // I am not a String

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

print(server_string.getInfo())  # I am not a String

Per vedere l'aspetto del contenitore stesso, stampa la rappresentazione di stringa dell'oggetto:

Editor di codice (JavaScript)

print(serverString.toString());  // ee.String("I am not a String!")

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

print(server_string)  # ee.String({"constantValue": "I am not a String!"})

Se, per qualche motivo, devi utilizzare Python o JavaScript in esecuzione nel client per manipolare i contenuti del contenitore, utilizza getInfo() per recuperare i contenuti del contenitore e assegnarli a una variabile:

Editor di codice (JavaScript)

var someString = serverString.getInfo();
var strings = someString + '  Am I?';
print(strings);  // I am not a String!  Am I?

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

some_string = server_string.getInfo()
strings = some_string + '  Am I?'
print(strings)  # I am not a String!  Am I?

Avviso: utilizza getInfo() con cautela. Se chiami getInfo() nel codice, Earth Engine aprirà il contenitore e ti dirà cosa contiene, ma bloccherà il resto del codice fino al termine dell'operazione. Ove possibile, è meglio eseguire tutto sul server.

Loop

Poiché il client non sa cosa contiene gli oggetti ee.Thing lato server, le operazioni lato client come i controlli condizionali e i cicli for non funzionano con questi oggetti. Per questo motivo, e per evitare chiamate sincrone a getInfo(), utilizza le funzioni del server nella misura del possibile. Ad esempio, prendi in considerazione i seguenti due modi per creare un elenco:

Sconsigliato: ciclo for lato client

Editor di codice (JavaScript)

var clientList = [];
for(var i = 0; i < 8; i++) {
  clientList.push(i + 1);
}
print(clientList);

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

client_list = []
for i in range(8):
  client_list.append(i + 1)
print(client_list)

Consigliato: mappatura lato server

Editor di codice (JavaScript)

var serverList = ee.List.sequence(0, 7);
serverList = serverList.map(function(n) {
  return ee.Number(n).add(1);
});
print(serverList);

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

server_list = ee.List.sequence(0, 7)
server_list = server_list.map(lambda n: ee.Number(n).add(1))
print(server_list.getInfo())

L'esempio di mappatura lato server è un po' sciocco perché potresti creare lo stesso elenco semplicemente con ee.List.sequence(1, 8), ma illustra alcuni concetti importanti. Il primo concetto è map(), che applica semplicemente la stessa funzione a tutti gli elementi dell'elenco. Poiché questa funzione viene eseguita sul server, le funzioni sul lato client come getInfo() e print() non funzioneranno in una funzione mappata. Per questo motivo, il codice i + 1 deve essere sostituito con il codice lato server equivalente: ee.Number(n).add(1). È importante sottolineare che n è un oggetto che esiste solo sul server. Poiché la funzione non conosce il tipo del suo argomento, deve essere eseguita la conversione a un ee.Number.

(consulta la sezione sulle funzioni lato client e lato server per una descrizione delle funzioni eseguite sul client).

Vale anche la pena notare che a volte la funzionalità lato client è comoda. Ad esempio, il ciclo for precedente potrebbe essere utilizzato per creare un elenco e racchiuderlo in un oggetto lato server:

Editor di codice (JavaScript)

var toServerList = ee.List(clientList);

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

to_server_list = ee.List(client_list)

Tieni presente che l'elaborazione lato client viene eseguita nel notebook o nel browser, ovvero sulla CPU della macchina host, pertanto può essere meno efficiente dell'utilizzo di Earth Engine per eseguire il lavoro sul server. Inoltre, per evitare risultati potenzialmente sorprendenti, è buona prassi evitare di combinare funzionalità di client e server negli script. La sezione Condizionali fornisce un esempio di conseguenze potenzialmente indesiderate.

Condizionali

Gli oggetti lato server non funzionano necessariamente con le funzioni lato client e viceversa. Ad esempio, prendi in considerazione il caso di una variabile booleana lato server:

Editor di codice (JavaScript)

var myList = ee.List([1, 2, 3]);
var serverBoolean = myList.contains(5);
print(serverBoolean);  // false

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

my_list = ee.List([1, 2, 3])
server_boolean = my_list.contains(5)
print(server_boolean.getInfo())  # False

Come mostrato nell'esempio seguente, la variabile non si comporta in un'istruzione condizionale lato client perché è un oggetto lato server. Per verificare correttamente un valore booleano lato server, utilizza una funzione lato server:

Non consigliato: condizione lato client

Editor di codice (JavaScript)

var clientConditional;
if (serverBoolean) {
  clientConditional = true;
} else {
  clientConditional = false;
}
print('Should be false:', clientConditional);  // True!

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

if server_boolean:
  client_conditional = True
else:
  client_conditional = False
print('Should be False:', client_conditional)  # True!

Consigliata: condizione lato server

Editor di codice (JavaScript)

var serverConditional = ee.Algorithms.If(serverBoolean, 'True!', 'False!');
print('Should be false:', serverConditional);  // False!

Configurazione di Python

Per informazioni sull'API Python e sull'utilizzo di geemap per lo sviluppo interattivo, consulta la pagina Ambiente Python.

import ee
import geemap.core as geemap

Colab (Python)

server_conditional = ee.Algorithms.If(server_boolean, 'True!', 'False!')
print('Should be False:', server_conditional.getInfo())  # False!

Avviso: utilizza ee.Algorithms.If() con cautela. Il modo migliore per eseguire test condizionali sul server è con i filtri. Ad esempio, consulta Filtrare un ImageCollection e Filtrare un FeatureCollection.

Funzioni client e server

Le sezioni precedenti descrivono diversi motivi per cui è inefficiente o illogico mescolare oggetti e funzioni client e server. Quali oggetti e funzioni sono lato client e quali sono lato server? In generale, qualsiasi elemento inizializzato come ee.Thing è un oggetto server e qualsiasi metodo su quell'oggetto, ee.Thing.method(), è una funzione del server. Gli oggetti e le funzioni visualizzati nella documentazione di Python o JavaScript sono lato client. Come indicato in precedenza, puoi utilizzare la funzionalità lato client per creare un oggetto, quindi racchiuderlo passando l'oggetto lato client a un costruttore Earth Engine, ad esempio ee.String().