Client et serveur

Les bibliothèques clientes Earth Engine pour Python et JavaScript traduisent des analyses géospatiales complexes en requêtes Earth Engine. Le code que vous écrivez pour une bibliothèque cliente peut contenir un mélange de références à des objets côté client et de variables représentant des objets côté serveur.

Il est important de distinguer les objets Earth Engine des autres objets ou primitives Python ou JavaScript qui peuvent se trouver dans votre code. Vous pouvez manipuler des objets sur le serveur en manipulant des objets "proxy" côté client dans votre script. Vous pouvez reconnaître un objet proxy comme tout élément commençant par ee. Ces objets proxy Earth Engine ne contiennent aucune donnée réelle et ne sont que des poignées d'objets sur le serveur. Pour commencer, considérons un objet de chaîne côté client (qui n'est PAS un objet proxy):

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

import ee
import geemap.core as geemap

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

À partir de la sortie, observez que le client (le navigateur Web ou le notebook) a interprété ce code et l'a exécuté, déterminant que la variable est de type string. Imaginons maintenant que vous souhaitiez que Earth Engine puisse effectuer une action avec cette chaîne. Pour ce faire, vous devez encapsuler la chaîne dans un conteneur approprié et l'envoyer à Google. Ce conteneur est l'objet proxy. Exemple :

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

import ee
import geemap.core as geemap

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

À partir de la sortie, vous pouvez constater que ee.String est un object, et non un string. Plus précisément, il s'agit d'un ee.computedObject, ce qui signifie qu'il s'agit d'un objet proxy pour quelque chose sur le serveur. Considérez ee.Thing comme un moyen de placer un élément dans un conteneur pour l'envoyer à Google. Votre client ne sait pas ce qu'il y a dans le conteneur, mais vous pouvez le découvrir en l'imprimant:

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

import ee
import geemap.core as geemap

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

Pour voir à quoi ressemble le conteneur lui-même, imprimez la représentation de la chaîne de l'objet:

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

import ee
import geemap.core as geemap

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

Si, pour une raison quelconque, vous devez utiliser Python ou JavaScript exécuté dans le client pour manipuler tout ce qui se trouve dans le conteneur, utilisez getInfo() pour obtenir le contenu du conteneur et l'attribuer à une variable:

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

import ee
import geemap.core as geemap

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

Lecture en boucle

Comme le client ne sait pas ce qui se trouve dans les objets ee.Thing côté serveur, les opérations côté client telles que les conditions et les boucles for ne fonctionnent pas avec eux. Pour cette raison et pour éviter les appels synchrones à getInfo(), utilisez autant que possible les fonctions de serveur. Prenons l'exemple des deux méthodes suivantes pour créer une liste:

Non recommandé : boucle for côté client

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

import ee
import geemap.core as geemap

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

Recommandé : mappage côté serveur

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

import ee
import geemap.core as geemap

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

L'exemple de mappage côté serveur est un peu idiot, car vous pouvez créer la même liste simplement avec ee.List.sequence(1, 8), mais il illustre certains concepts importants. Le premier concept est map(), qui applique simplement la même fonction à tous les éléments de la liste. Étant donné que cette fonction est exécutée sur le serveur, les fonctions côté client telles que getInfo() et print() ne fonctionneront pas dans une fonction mappée. Pour cette raison, le code i + 1 doit être remplacé par le code côté serveur équivalent: ee.Number(n).add(1). Il est important de noter que n est un objet qui n'existe que sur le serveur. Étant donné que la fonction ne connaît pas le type de son argument, elle doit être convertie en ee.Number.

Notez également que les fonctionnalités côté client sont parfois pratiques. Par exemple, la boucle for précédente peut être utilisée pour créer une liste et l'encapsuler avec un objet côté serveur:

var toServerList = ee.List(clientList);

import ee
import geemap.core as geemap

to_server_list = ee.List(client_list)

Sachez que le traitement côté client est effectué dans votre ordinateur portable ou votre navigateur, c'est-à-dire sur le processeur de la machine hôte. Il peut donc être moins efficace que d'utiliser Earth Engine pour effectuer le travail sur le serveur. De plus, pour éviter des résultats potentiellement surprenants, il est recommandé d'éviter de mélanger les fonctionnalités client et serveur dans vos scripts. La section Conditions fournit un exemple de conséquences inattendues.

Expressions conditionnelles

Les objets côté serveur ne fonctionnent pas nécessairement avec les fonctions côté client, et inversement. Prenons l'exemple d'une variable booléenne côté serveur:

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

import ee
import geemap.core as geemap

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

Comme illustré dans l'exemple suivant, la variable ne se comporte pas dans une condition côté client, car il s'agit d'un objet côté serveur. Pour vérifier correctement une valeur booléenne côté serveur, utilisez une fonction côté serveur:

Non recommandé : conditionnel côté client

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

import ee
import geemap.core as geemap

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

Recommandé : conditionnel côté serveur

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

import ee
import geemap.core as geemap

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

Fonctions client et serveur

Les sections précédentes décrivent plusieurs raisons pour lesquelles il est inefficace ou illogique de mélanger les objets et les fonctions client et serveur. Quels objets et fonctions sont côté client et côté serveur ? En général, tout élément initialisé en tant que ee.Thing est un objet serveur, et toute méthode de cet objet, ee.Thing.method(), est une fonction de serveur. Les objets et les fonctions qui apparaissent dans la documentation Python ou JavaScript sont côté client. Comme indiqué précédemment, vous pouvez utiliser la fonctionnalité côté client pour créer un objet, puis l'encapsuler en fournissant l'objet côté client à un constructeur Earth Engine, par exemple ee.String().