Objets Earth Engine

Maintenant que vous êtes à l'aise avec JavaScript, découvrez comment placer des objets et des primitives JavaScript dans des conteneurs Earth Engine pour les envoyer au serveur et les traiter chez Google.

Cordes

Par exemple, définissez une chaîne, puis placez-la dans le conteneur ee.String() à envoyer à Earth Engine :

Éditeur de code (JavaScript)

// Define a string, then put it into an EE container.
var aString = 'To the cloud!';
var eeString = ee.String(aString);
print('Where to?', eeString);

Considérez ee.Thing comme un conteneur pour un élément qui existe sur le serveur. Dans cet exemple, la chaîne est d'abord définie, puis placée dans le conteneur. Vous pouvez également définir le conteneur et son contenu en une seule fois. Exemple :

Éditeur de code (JavaScript)

// Define a string that exists on the server.
var serverString = ee.String('This is on the server.');
print('String on the server:', serverString);

Bien que le premier argument de print() ne soit qu'une chaîne côté client, le deuxième argument est en fait envoyé au serveur pour être évalué, puis renvoyé.

Numbers

Utilisez ee.Number() pour créer des objets numériques sur le serveur. Par exemple, utilisez la méthode JavaScript Math.E pour créer une valeur constante sur le serveur :

Éditeur de code (JavaScript)

// Define a number that exists on the server.
var serverNumber = ee.Number(Math.E);
print('e=', serverNumber);

Les méthodes ee.String() et ee.Number() sont des constructeurs. Un constructeur prend son argument (et éventuellement d'autres paramètres), le place dans un conteneur et renvoie le conteneur et son contenu sous la forme d'un objet Earth Engine que vous pouvez manipuler dans votre code. Tout constructeur commençant par ee renvoie un objet Earth Engine.

Méthodes sur les objets Earth Engine

Notez qu'une fois que vous avez créé un objet Earth Engine, vous devez utiliser les méthodes Earth Engine pour le traiter. Dans cet exemple, vous ne pouvez pas utiliser Math.log() de JavaScript pour traiter cet objet Earth Engine. Vous devez utiliser la méthode équivalente définie pour un ee.Number :

Éditeur de code (JavaScript)

// Use a built-in function to perform an operation on the number.
var logE = serverNumber.log();
print('log(e)=', logE);

Dans cet exemple, log() est une méthode pour un objet ee.Number. (Utilisez l'onglet Docs sur le côté gauche de l'éditeur de code pour afficher la liste de toutes les méthodes pour chaque type d'objet Earth Engine, par exemple ee.Number > log()). Notez que les méthodes des objets Earth Engine renvoient d'autres objets Earth Engine.

Listes

Pour transformer une liste JavaScript en objet ee.List sur le serveur, vous pouvez placer un littéral JavaScript dans un conteneur, comme avec les nombres et les chaînes. Earth Engine fournit également des méthodes pratiques côté serveur pour créer des séquences de nombres. Exemple :

Éditeur de code (JavaScript)

// Make a sequence the hard way.
var eeList = ee.List([1, 2, 3, 4, 5]);
// Make a sequence the easy way!
var sequence = ee.List.sequence(1, 5);
print('Sequence:', sequence);

Étant donné que les objets ee.List n'existent que sur le serveur, utilisez les fonctions fournies par Earth Engine pour interagir avec eux. Par exemple, pour extraire un élément de la liste, utilisez la méthode get() de l'objet ee.List :

Éditeur de code (JavaScript)

// Use a method on an ee.List to extract a value.
var value = sequence.get(2);
print('Value at index 2:', value);

Diffusion

Parfois, Earth Engine ne connaît pas le type d'objet renvoyé par une méthode. En tant que programmeur, vous savez que la variable value de l'exemple précédent est un objet numérique. Toutefois, si vous essayez d'utiliser la méthode add() d'un ee.Number, une erreur s'affiche, par exemple :

value.add n'est pas une fonction

Cela se produit souvent avec la fonction get(), qui peut renvoyer toutes sortes d'objets Earth Engine. Pour le corriger, utilisez le constructeur ee.Number pour caster le résultat :

Éditeur de code (JavaScript)

// Cast the return value of get() to a number.
print('No error:', ee.Number(value).add(3));

Dictionnaires

Vous pouvez construire un Dictionary Earth Engine à partir d'un objet JavaScript, comme avec les chaînes, les nombres et les listes. Au moment de la construction, vous pouvez utiliser la fonctionnalité JavaScript pour initialiser l'objet Earth Engine. Dans ce cas, un ee.Dictionary est construit directement à partir d'un objet littéral JavaScript :

Éditeur de code (JavaScript)

// Make a Dictionary on the server.
var dictionary = ee.Dictionary({
  e: Math.E,
  pi: Math.PI,
  phi: (1 + Math.sqrt(5)) / 2
});

// Get some values from the dictionary.
print('Euler:', dictionary.get('e'));
print('Pi:', dictionary.get('pi'));
print('Golden ratio:', dictionary.get('phi'));

// Get all the keys:
print('Keys: ', dictionary.keys());

Dans cet exemple, notez qu'une fois que vous avez un ee.Dictionary, vous devez utiliser des méthodes sur le ee.Dictionary pour obtenir des valeurs (contrairement au dictionnaire JavaScript de la leçon précédente). Plus précisément, get(key) renvoie la valeur associée à key. Étant donné que le type d'objet renvoyé par get() peut être n'importe quoi, si vous souhaitez effectuer une action sur l'objet autre que l'impression, vous devez le caster au bon type. Notez également que la méthode keys() renvoie un ee.List.

Dates

Les objets Date sont la façon dont Earth Engine représente le temps. Comme dans les exemples précédents, il est important de faire la distinction entre un objet Date JavaScript et un objet ee.Date Earth Engine. Construisez un ee.Date à partir d'une chaîne, d'un Date JavaScript ou à l'aide des méthodes statiques fournies par la classe ee.Date. (Pour en savoir plus, consultez la section "Date" de l'onglet Documentation.) Cet exemple illustre la construction de dates à partir de chaînes ou d'une date JavaScript représentant des millisecondes depuis minuit le 1er janvier 1970 :

Éditeur de code (JavaScript)

// Define a date in Earth Engine.
var date = ee.Date('2015-12-31');
print('Date:', date);

// Get the current time using the JavaScript Date.now() method.
var now = Date.now();
print('Milliseconds since January 1, 1970', now);

// Initialize an ee.Date object.
var eeNow = ee.Date(now);
print('Now:', eeNow);

Les dates sont utiles pour filtrer les collections, en particulier en tant qu'arguments de la méthode filterDate(). Pour en savoir plus sur le tri des collections, consultez cette section de la page "Premiers pas".

Digression : transmettre des paramètres par nom

Les arguments des méthodes Earth Engine peuvent être transmis dans l'ordre. Par exemple, pour créer un ee.Date à partir de l'année, du mois et du jour, vous pouvez transmettre les paramètres de la méthode statique fromYMD() dans l'ordre suivant : année, mois, jour :

Éditeur de code (JavaScript)

var aDate = ee.Date.fromYMD(2017, 1, 13);
print('aDate:', aDate);

Vous pouvez également transmettre les paramètres par nom, dans n'importe quel ordre. Bien que cela puisse nécessiter plus de code, cela peut améliorer la lisibilité et la réutilisabilité. Pour transmettre des paramètres par nom, transmettez un objet JavaScript dans lequel les clés de l'objet sont les noms des paramètres de la méthode et les valeurs sont les arguments de la méthode. Exemple :

Éditeur de code (JavaScript)

var theDate = ee.Date.fromYMD({
  day: 13,
  month: 1,
  year: 2017
});
print('theDate:', theDate);

Notez que les noms des propriétés de l'objet (les clés) correspondent aux noms spécifiés dans la documentation ee.Date.fromYMD(). Notez également que l'objet transmis en tant qu'argument peut être enregistré dans une variable pour être réutilisé, comme illustré dans l'exemple d'objet JavaScript.

Vous avez maintenant suffisamment de connaissances sur JavaScript pour commencer à utiliser Earth Engine. Pour obtenir une explication plus détaillée des objets JavaScript et Earth Engine, consultez la page Client vs. Server (Client vs. Serveur).

Dans la section suivante, découvrez les concepts de programmation fonctionnelle pour utiliser efficacement les boucles for, les conditions if/else et les itérations dans Earth Engine.