Premiers pas avec Earth Engine

Ce guide de démarrage vous permet de commencer à programmer rapidement avec l'API JavaScript Earth Engine. Pour découvrir JavaScript et effectuer des exercices plus approfondis avec l'API Earth Engine, consultez les tutoriels. Pour connaître le style de codage JavaScript recommandé, consultez le guide de style JavaScript de Google.

Google Earth Engine permet aux utilisateurs d'exécuter des algorithmes sur des images et des vecteurs géoréférencés stockés sur l'infrastructure de Google. L'API Google Earth Engine fournit une bibliothèque de fonctions pouvant être appliquées aux données pour les afficher et les analyser. Le catalogue de données publiques d'Earth Engine contient un grand nombre d'images et d'ensembles de données vectoriels accessibles au public. Vous pouvez également créer des composants privés dans les dossiers personnels des utilisateurs.

Comment utiliser ces documents

La documentation Earth Engine s'adresse aux personnes familiarisées avec l'analyse de données géospatiales. Les documents sont principalement structurés par type de données. Par exemple, le panneau de navigation de gauche contient des liens vers des sections ou des pages sur des types de données importants tels que Image, ImageCollection, Feature, FeatureCollection, Geometry, Reducer, Chart, Join et Array. Ce guide ne décrit ces types que suffisamment pour vous lancer. Vous trouverez également des sections sur le machine learning, les algorithmes spécialisés ou spécifiques aux capteurs (par exemple, les algorithmes Landsat), les applications publiques, la gestion des données (composants) et des informations importantes sur le fonctionnement interne d'Earth Engine. Avant de vous lancer dans tout cela, commencez par ceci !

Éditeur de code

L'éditeur de code est un environnement interactif permettant de développer des applications Earth Engine (figure 1). Le panneau central fournit un éditeur de code JavaScript. Au-dessus de l'éditeur se trouvent des boutons permettant d'enregistrer le script actuel, de l'exécuter et d'effacer la carte. Le bouton Obtenir le lien génère une URL unique pour le script dans la barre d'adresse. La carte du panneau inférieur contient les calques ajoutés par le script. Un champ de recherche pour les ensembles de données et les lieux s'affiche en haut. Le panneau de gauche contient des exemples de code, vos scripts enregistrés, une référence API pouvant être recherchée et un gestionnaire d'éléments pour les données privées. Le panneau de droite comporte un inspecteur pour interroger la carte, une console de sortie et un gestionnaire pour les tâches de longue durée. Le bouton d'aide help en haut à droite contient des liens vers ce guide et d'autres ressources pour obtenir de l'aide. Pour en savoir plus, consultez le guide de l'éditeur de code et le guide d'obtention d'aide.

Ouvrir et exécuter du code dans l'éditeur de code

Les étapes ci-dessous montrent comment ouvrir Earth Engine et exécuter un script personnalisé qui affiche une image. Pour un résultat optimal, nous vous recommandons d'installer la dernière version de Chrome, le navigateur Web de Google, disponible sur cette page.

1. Ouvrez l'éditeur de code Earth Engine à l'adresse code.earthengine.google.com.
2. Accédez à l'onglet Scripts situé tout à gauche de l'éditeur de code. Vous y trouverez une collection d'exemples de scripts qui accèdent, affichent et analysent les données Earth Engine.
3. Sous "Collection d'images", sélectionnez l'exemple "Composite filtré". Un script s'affiche dans la console centrale. Appuyez sur le bouton Run (Exécuter) pour exécuter le script. L'exemple de composite filtré sélectionne les images Landsat 7 qui se croisent ou se trouvent dans les limites du Colorado et de l'Utah. Il affiche ensuite un composite en couleurs réelles des images sélectionnées. Les exemples vous présentent des méthodes couramment utilisées, telles que filter(), clip() et Map.addLayer().

Structures de données Earth Engine

Les deux structures de données géographiques les plus fondamentales dans Earth Engine sont Image et Feature, qui correspondent respectivement aux types de données raster et vectorielles. Les images sont composées de bandes et d'un dictionnaire de propriétés. Les éléments géographiques sont composés d'un Geometry et d'un dictionnaire de propriétés. Une pile d'images (par exemple, une série temporelle d'images) est gérée par un ImageCollection. Une collection d'éléments géographiques est gérée par un FeatureCollection. D'autres structures de données fondamentales dans Earth Engine incluent Dictionary, List, Array, Date, Number et String (pour en savoir plus sur les types de données de base, consultez ce tutoriel). Il est important de se rappeler qu'il s'agit de tous des objets côté serveur et qu'ils ne sont pas manipulés de la même manière que les objets JavaScript côté client (en savoir plus).

Algorithmes Earth Engine

Il existe plusieurs façons d'exécuter des opérations dans l'API:

• Appel des méthodes associées à des objets.
• Appel des algorithmes.
• Appeler des fonctions spécifiques à l'éditeur de code
• Définir de nouvelles fonctions

L'onglet Documentation de l'éditeur de code liste les méthodes de chaque classe d'API. Par exemple, la classe Image possède une méthode add():

var image3 = image1.add(image2);

Cette méthode ajoute les bandes de image2 aux bandes de image1. La catégorie ee.Algorithms contient une liste des algorithmes actuellement compatibles pour le traitement spécialisé ou spécifique au domaine. Par exemple, pour créer des calques topographiques à partir d'un modèle numérique d'élévation (DEM) d'entrée :

var terrainImage = ee.Algorithms.Terrain(dem);

Les fonctions spécifiques à l'éditeur de code incluent les méthodes Map et Export, qui contrôlent respectivement l'ajout de calques au panneau de la carte ou l'exportation vers Google Drive. Vous pouvez également créer des fonctions en JavaScript à l'aide de

var myFunction = function(args) {
  // do something
  return something;
};

Comme illustré dans la section "Mappage", les fonctions définies par l'utilisateur sont utiles pour créer des fonctionnalités personnalisées ou modifier les éléments d'une collection à l'aide des éléments suivants:

var collection2 = collection1.map(aFunction);

Les sections suivantes illustrent ces concepts pour différents cas d'utilisation simples.

"Hello world!" JavaScript

L'impression d'informations dans la console est une tâche de base pour obtenir des informations sur un objet, afficher le résultat numérique d'un calcul, afficher les métadonnées de l'objet ou faciliter le débogage. L'exemple emblématique "Hello World!" dans l'éditeur de code est le suivant:

print('Hello world!');

Copiez cette ligne dans l'éditeur de code, puis cliquez sur Exécuter. Notez que la sortie s'affiche dans l'onglet Console, à droite de l'éditeur de code. Pour un exemple plus pertinent pour le télédétection, la commande suivante imprime les métadonnées d'une image Landsat 8:

print(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318'));

Examinez attentivement la sortie dans la console pour voir les métadonnées disponibles pour les images Landsat.

Ajouter des données à la carte

En plus d'imprimer des informations dans la console, ajouter des données à Map permet de visualiser des données géographiques. Pour ce faire, utilisez Map.addLayer(). Dans l'exemple suivant, un Image est instancié (la façon de trouver ces images est abordée plus loin) à l'aide de ee.Image(), ajouté à la carte avec Map.addLayer() et la carte est centrée sur l'image:

// Load an image.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');

// Center the map on the image.
Map.centerObject(image, 9);

// Display the image.
Map.addLayer(image);

Le deuxième paramètre de Map.centerObject() est un niveau de zoom, où les nombres plus élevés indiquent une échelle plus grande (plus rapprochée). Les paramètres des fonctions Map sont décrits en détail dans la documentation de référence de l'API accessible depuis l'onglet Documentation. Si l'apparence de l'image n'est pas satisfaisante, configurez les paramètres d'affichage avec un argument supplémentaire pour Map.addLayer(). Par exemple :

// Load the image from the archive.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');

// Define visualization parameters in an object literal.
var vizParams = {bands: ['B5', 'B4', 'B3'], min: 0.02, max: 0.4, gamma: 1.3};

// Center the map on the image and display.
Map.centerObject(image, 9);
Map.addLayer(image, vizParams, 'Landsat 8 false color');

Notez que les paramètres de visualisation sont définis par un littéral d'objet, qui inclut une liste de bandes à afficher, une valeur de réflectance minimale et maximale, ainsi qu'une valeur de gamma. (En savoir plus sur les bandes Landsat) Pour en savoir plus sur la visualisation d'images, cliquez ici.

Utilisez Map.addLayer() pour ajouter des éléments géographiques et des collections d'éléments géographiques à la carte. Par exemple,

var counties = ee.FeatureCollection('TIGER/2018/Counties');
Map.addLayer(counties, {}, 'counties');

Rechercher des images, des collections d'images et des collections d'éléments géographiques

Vous pouvez rechercher des images, des collections d'images et des collections d'éléments dans le catalogue de données Earth Engine. Par exemple, si vous saisissez "Landsat 8" dans le champ de recherche, une liste d'ensembles de données raster s'affiche. (La liste complète des ensembles de données Earth Engine est disponible dans le catalogue de données Earth Engine.) Cliquez sur le nom de l'ensemble de données pour obtenir une brève description, des informations sur la disponibilité temporelle, le fournisseur de données et l'ID de collection. Cliquez sur le bouton Importer pour créer automatiquement une section Importations en haut de votre script avec une variable pour cette collection.

Vous pouvez également copier l'ID de collection et le coller dans votre code. Par exemple, choisissez le résultat de la recherche "Landsat 8" de l'ordre de priorité 1 et copiez l'ID comme suit:

var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA');

Comme il s'agit d'une collection de nombreuses images couvrant la surface terrestre, trouver une image spécifique dans la collection nécessite un filtrage afin d'affiner la recherche. Vous pouvez également réduire la collection d'images à une seule image à l'aide de techniques de composition et de mosaïque. Pour en savoir plus sur le filtrage et la composition (voir Réduction), consultez les sections suivantes.

Les collections d'éléments géographiques sont également disponibles dans Data Catalog. Leur représentation est plus petite que celle des collections d'images, mais vous trouverez des limites internationales, des limites de recensement, des limites de bassin hydrographique et des limites d'aires protégées, pour n'en citer que quelques-unes. Cliquez ici pour en savoir plus sur l'importation de vos propres ensembles de données vectoriels.

Filtrage et tri

Il est souvent nécessaire de filtrer une collection par espace et/ou par temps afin de limiter le nombre de résultats. Prenons l'exemple de la tâche consistant à trier la collection de scènes Landsat 8 afin de trouver une scène sans nuage pour San Francisco. Tout d'abord, il est nécessaire de définir la région d'intérêt. Un point est souvent utile pour cela. Activez l'onglet Inspecteur sur le côté droit de l'éditeur de code, puis cliquez près du centre de la zone d'intérêt. Copiez les coordonnées de l'onglet Inspecteur, puis créez un Point à l'aide de:

var point = ee.Geometry.Point(-122.262, 37.8719);

Créez les dates de début et de fin:

var start = ee.Date('2014-06-01');
var finish = ee.Date('2014-10-01');

Filtrez la collection Landsat 8 à l'aide du point et des dates, puis triez-la à l'aide d'une propriété de métadonnées (découverte lors de l'inspection des métadonnées de la scène Landsat 8):

var filteredCollection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(point)
  .filterDate(start, finish)
  .sort('CLOUD_COVER', true);

Cette collection peut être imprimée et inspectée sans risque. (Si la collection contient trop d'images, l'impression sera très lente, le délai avant expiration sera dépassé ou une erreur sera renvoyée.) Notez que les images de la collection sont des List stockées dans la propriété "features" de ImageCollection. L'ID de n'importe quelle image de la collection peut être copié dans le constructeur Image, comme ci-dessus. Vous pouvez également obtenir la première image (couverture nuageuse la plus faible):

var first = filteredCollection.first();

Accédez à l'ensemble des fonctionnalités de filtrage Earth Engine à l'aide de filter() avec un ee.Filter comme argument. (Les méthodes filterBounds() et filterDate() utilisées ci-dessus sont des raccourcis.) Par exemple, le code suivant crée un Filter, l'utilise pour filtrer un FeatureCollection et affiche le résultat:

// Load a feature collection.
var featureCollection = ee.FeatureCollection('TIGER/2016/States');

// Filter the collection.
var filteredFC = featureCollection.filter(ee.Filter.eq('NAME', 'California'));

// Display the collection.
Map.setCenter(-119.604, 37.798, 6);
Map.addLayer(filteredFC, {}, 'California');

Calcul des bandes

Effectuez des opérations mathématiques sur des images à l'aide des méthodes Image. Cela peut inclure des recombinaisons de bandes (indices spectraux), des différences d'images ou des opérations mathématiques telles que la multiplication par une constante. Par exemple, calculez la différence entre des images de l'indice de végétation par différence normalisée (NDVI) prises à 20 ans d'intervalle:

// This function gets NDVI from Landsat 5 imagery.
var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.
var image1 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_20100611');

// Compute NDVI from the scenes.
var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);

Notez que dans cet exemple, une function définie par l'utilisateur est utilisée. Pour en savoir plus sur les fonctions, consultez la section suivante.

Mappage (que faire à la place d'une boucle for)

Utilisez map() pour itérer les éléments d'une collection. (Les boucles for ne sont PAS la bonne méthode pour ce faire dans Earth Engine et doivent être évitées.) La fonction map() peut être appliquée à un ImageCollection, un FeatureCollection ou un List, et accepte un function comme argument. L'argument de la fonction est un élément de la collection sur laquelle elle est mappée. Cela permet de modifier chaque élément de la collection de la même manière, par exemple en ajoutant. Par exemple, le code suivant ajoute une bande NDVI à chaque image d'un ImageCollection:

// This function gets NDVI from Landsat 8 imagery.
var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// Load the Landsat 8 TOA data, filter by location and date.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the collection.
var ndviCollection = collection.map(addNDVI);

Une autre tâche courante consiste à ajouter une propriété (ou un "attribut" ou un "champ") aux éléments géographiques d'une FeatureCollection. Dans l'exemple suivant, la nouvelle propriété est un calcul impliquant deux attributs existants:

// This function creates a new property that is the sum of two existing properties.
var addField = function(feature) {
  var sum = ee.Number(feature.get('property1')).add(feature.get('property2'));
  return feature.set({'sum': sum});
};

// Create a FeatureCollection from a list of Features.
var features = ee.FeatureCollection([
  ee.Feature(ee.Geometry.Point(-122.4536, 37.7403),
    {property1: 100, property2: 100}),
    ee.Feature(ee.Geometry.Point(-118.2294, 34.039),
    {property1: 200, property2: 300}),
]);

// Map the function over the collection.
var featureCollection = features.map(addField);

// Print a selected property of one Feature.
print(featureCollection.first().get('sum'));

// Print the entire FeatureCollection.
print(featureCollection);

Notez que la conversion en ee.Number est nécessaire pour que la valeur de la propriété soit reconnue comme un nombre afin d'utiliser la méthode add(). Le type de la collection peut être modifié par map(). Exemple :

// This function returns the image centroid as a new Feature.
var getGeom = function(image) {
  return ee.Feature(image.geometry().centroid(), {foo: 1});
};

// Load a Landsat 8 TOA collection.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the ImageCollection.
var featureCollection = ee.FeatureCollection(collection.map(getGeom));

// Print the collection.
print(featureCollection);

Notez la propriété ajoutée (foo) pour chaque élément géographique créé à partir du centroïde de l'image. Dans la dernière ligne, le casting permet de reconnaître la collection résultante comme un FeatureCollection.

Réduction

La réduction permet d'agréger des données sur la durée, l'espace, les bandes, les tableaux et d'autres structures de données dans Earth Engine. L'API propose différentes méthodes à cet effet. Par exemple, pour créer un composite d'un ImageCollection, utilisez reduce() pour réduire les images de la collection à une seule image. Voici un exemple simple : la création du composite médian des cinq scènes les moins nuageuses de la collection Landsat 8 définie précédemment :

// Load a Landsat 8 TOA collection.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  // Filter by date and location.
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-01-01', '2014-12-31')
  // Sort by increasing cloudiness.
  .sort('CLOUD_COVER');

// Compute the median of each pixel for each band of the 5 least cloudy scenes.
var median = collection.limit(5).reduce(ee.Reducer.median());

La réduction permet également d'obtenir des statistiques sur une image dans les régions définies par un Feature ou un FeatureCollection. Supposons que la tâche consiste à calculer les valeurs moyennes des pixels dans une zone d'intérêt. Utilisez reduceRegion() à cette fin. Exemple :

// Load and display a Landsat TOA image.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');
Map.addLayer(image, {bands: ['B4', 'B3', 'B2'], max: 0.3});

// Create an arbitrary rectangle as a region and display it.
var region = ee.Geometry.Rectangle(-122.2806, 37.1209, -122.0554, 37.2413);
Map.addLayer(region);

// Get a dictionary of means in the region.  Keys are bandnames.
var mean = image.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: region,
  scale: 30
});

Pour en savoir plus sur les réducteurs, consultez la documentation sur les réducteurs.

Masquage

Chaque pixel d'un ee.Image possède à la fois une valeur et un masque, qui vont de 0 (pas de données) à 1. Les pixels masqués (pour lesquels mask==0) sont considérés comme ne contenant aucune donnée. Les pixels dont le masque est compris entre 0 et 1 ont une valeur, mais elle est pondérée par le masque pour les calculs numériques.

Vous pouvez rendre les pixels transparents ou les exclure de l'analyse à l'aide de masques. Les pixels sont masqués lorsque la valeur du masque est nulle. Poursuivant l'exemple de différence d'images, utilisez un masque pour afficher les zones où l'indice NDVI a augmenté et diminué au cours de l'intervalle de différence:

// This function gets NDVI from Landsat 5 imagery.
var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.
var image1 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_20100611');

// Compute NDVI from the scenes.
var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);
// Load the land mask from the SRTM DEM.
var landMask = ee.Image('CGIAR/SRTM90_V4').mask();

// Update the NDVI difference mask with the land mask.
var maskedDifference = ndviDifference.updateMask(landMask);

// Display the masked result.
var vizParams = {min: -0.5, max: 0.5, palette: ['FF0000', 'FFFFFF', '0000FF']};
Map.setCenter(-122.2531, 37.6295, 9);
Map.addLayer(maskedDifference, vizParams, 'NDVI difference');

Dans cet exemple, notez que le masque de la différence NDVI est mis à jour par le masque de terrain avec updateMask(). Cela définit le masque des pixels de différence NDVI sur le masque de terrain partout où le masque de différence NDVI est différent de zéro.

Le masquage est également utile pour exclure des données de l'analyse. Prenons l'exemple reduceRegion() de la section Réduction. Supposons que la tâche consiste à calculer une moyenne saisonnière du NDVI pour le comté de Santa Clara, en Californie, en excluant les pixels nuageux. L'exemple suivant illustre plusieurs concepts : filtrage, cartographie, réduction et utilisation d'un masque nuage:

// This function gets NDVI from a Landsat 8 image.
var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// This function masks cloudy pixels.
var cloudMask = function(image) {
  var clouds = ee.Algorithms.Landsat.simpleCloudScore(image).select(['cloud']);
  return image.updateMask(clouds.lt(10));
};

// Load a Landsat collection, map the NDVI and cloud masking functions over it.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point([-122.262, 37.8719]))
  .filterDate('2014-03-01', '2014-05-31')
  .map(addNDVI)
  .map(cloudMask);

// Reduce the collection to the mean of each pixel and display.
var meanImage = collection.reduce(ee.Reducer.mean());
var vizParams = {bands: ['B5_mean', 'B4_mean', 'B3_mean'], min: 0.02, max: 0.4};
Map.addLayer(meanImage, vizParams, 'mean');

// Load a region in which to compute the mean and display it.
var counties = ee.FeatureCollection('TIGER/2018/Counties');
var santaClara = ee.Feature(counties.filter(ee.Filter.eq('NAME', 'Santa Clara')).first());
Map.addLayer(santaClara);

// Get the mean of NDVI in the region.
var mean = meanImage.select(['nd_mean']).reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: santaClara.geometry(),
  scale: 30
});

// Print mean NDVI for the region.
mean.get('nd_mean').evaluate(function(val){
  print('Santa Clara spring mean NDVI:', val);
});