Inizia a utilizzare Earth Engine

Questa guida introduttiva è pensata come un modo rapido per iniziare a programmare con l'API JavaScript di Earth Engine. Per un'introduzione a JavaScript ed esercizi più approfonditi con l'API Earth Engine, consulta i tutorial. Per lo stile di programmazione JavaScript consigliato, consulta la Guida allo stile di JavaScript di Google.

Google Earth Engine consente agli utenti di eseguire algoritmi su immagini e vettori georeferenziati archiviati nell'infrastruttura di Google. L'API Google Earth Engine fornisce una libreria di funzioni che possono essere applicate ai dati per la visualizzazione e l'analisi. Il catalogo di dati pubblici di Earth Engine contiene una grande quantità di immagini e set di dati vettoriali disponibili pubblicamente. Gli asset privati possono essere creati anche nelle cartelle personali degli utenti.

Come utilizzare questi documenti

La documentazione di Earth Engine è progettata per chi ha dimestichezza con l'analisi dei dati geospaziali. I documenti sono strutturati principalmente in base al tipo di dati. Ad esempio, il menu di navigazione a sinistra contiene link a sezioni o pagine relative a tipi di dati importanti come Image, ImageCollection, Feature, FeatureCollection, Geometry, Reducer, Chart, Join e Array. Questa guida descrive solo quanto necessario per iniziare a utilizzare questi tipi di annunci. Sono presenti anche sezioni per machine learning, algoritmi specializzati o specifici per i sensori (ad es. algoritmi Landsat), app rivolte al pubblico, gestione dei dati (asset) e dettagli importanti sul funzionamento interno di Earth Engine. Prima di iniziare, dai un'occhiata qui.

L'editor di codice

L'editor di codice è un ambiente interattivo per lo sviluppo di applicazioni Earth Engine (Figura 1). Il riquadro centrale fornisce un editor di codice JavaScript. Sopra l'editor sono presenti pulsanti per salvare lo script corrente, eseguirlo e cancellare la mappa. Il pulsante Ottieni link genera un URL univoco per lo script nella barra degli indirizzi. La mappa nel riquadro in basso contiene i livelli aggiunti dallo script. In alto è presente una casella di ricerca per set di dati e luoghi. Il riquadro a sinistra contiene esempi di codice, gli script salvati, un riferimento API per la ricerca e un gestore di asset per i dati privati. Il riquadro a destra contiene un ispettore per eseguire query sulla mappa, una console di output e un gestore per le attività di lunga durata. Il pulsante Guida help in alto a destra contiene link a questa guida e ad altre risorse per ricevere assistenza. Scopri di più nella guida di Editor di codice e nella guida su come ricevere assistenza.

Aprire ed eseguire il codice nell'editor di codice

I passaggi riportati di seguito mostrano come aprire Earth Engine ed eseguire uno script personalizzato che visualizza un'immagine. Per risultati ottimali, ti consigliamo di installare la versione più recente di Chrome, il browser web di Google, disponibile qui.

1. Apri l'editor di codice di Earth Engine qui: code.earthengine.google.com.
2. Vai alla scheda Script in fondo a sinistra dell'Editor di codice. Troverai una raccolta di script di esempio che accedono, visualizzano e analizzano i dati di Earth Engine.
3. In "Raccolta di immagini", seleziona l'esempio "Composito filtrato". Nella console centrale viene visualizzato un script. Premi il pulsante Esegui per eseguire lo script. L'esempio di composito filtrato seleziona le immagini Landsat 7 che si intersecano o si trovano all'interno dei confini del Colorado e dello Utah. Viene quindi visualizzata un'immagine composita a colori reali delle immagini selezionate. I sample ti presentano metodi di uso comune come filter(), clip() e Map.addLayer().

Strutture di dati di Earth Engine

Le due strutture di dati geografici più fondamentali in Earth Engine sono Image e Feature che corrispondono rispettivamente ai tipi di dati raster e vettoriali. Le immagini sono composte da bande e da un dizionario di proprietà. Le funzionalità sono composte da un Geometry e da un dizionario di proprietà. Una serie di immagini (ad es. una serie temporale di immagini) viene gestita da un ImageCollection. Una raccolta di funzionalità viene gestita da un FeatureCollection. Altre strutture di dati fondamentali in Earth Engine includono Dictionary, List, Array, Date, Number e String (scopri di più sui tipi di dati di base da questo tutorial. È importante ricordare che si tratta di oggetti lato server e non vengono manipolati come gli oggetti JavaScript lato client (scopri di più).

Algoritmi di Earth Engine

Esistono diversi modi per eseguire operazioni nell'API:

• Metodi di chiamata associati a oggetti.
• Algoritmi di chiamata.
• Chiamata di funzioni specifiche dell'editor di codice.
• Definizione di nuove funzioni.

La scheda Documentazione di Code Editor elenca i metodi di ogni classe API. Ad esempio, la classe Image ha un metodo add():

var image3 = image1.add(image2);

Questo metodo aggiunge le bande di image2 alle bande di image1. La categoria ee.Algorithms contiene un elenco degli algoritmi attualmente supportati per l'elaborazione specializzata o specifica per dominio. Ad esempio, per creare livelli topografici da un modello digitale dell'elevazione (DEM) di input:

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

Le funzioni specifiche di Code Editor includono i metodi Map e Export, che controllano rispettivamente il modo in cui i livelli vengono aggiunti al riquadro della mappa o esportati su Google Drive. Le funzioni possono essere create anche in JavaScript utilizzando

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

Come illustrato nella sezione Mappatura, le funzioni definite dall'utente sono utili per creare funzionalità personalizzate o modificare gli elementi di una raccolta utilizzando:

var collection2 = collection1.map(aFunction);

Le sezioni seguenti illustrano questi concetti per vari casi d'uso semplici.

"Hello world!" JavaScript

Stampare informazioni nella console è un'attività di base per ottenere informazioni su un oggetto, visualizzare il risultato numerico di un calcolo, visualizzare i metadati dell'oggetto o contribuire al debug. L'iconico esempio "Hello World!" nell'editor di codice è:

print('Hello world!');

Copia questa riga nell'editor di codice e fai clic su Esegui. Tieni conto che l'output viene visualizzato nella scheda Console, a destra dell'Editor di codice. Per un esempio più pertinente al rilevamento remoto, di seguito vengono stampati i metadati di un'immagine Landsat 8:

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

Esamina attentamente l'output nella console per visualizzare i metadati disponibili per le immagini Landsat.

Aggiunta di dati alla mappa

Oltre a stampare le informazioni nella console, l'aggiunta di dati a Map è il modo per visualizzare i dati geografici. Usa Map.addLayer() per farlo. Nel seguente esempio, viene creato un oggetto Image (la procedura per trovare queste immagini è discussa più avanti) utilizzando ee.Image(), aggiunto alla mappa con Map.addLayer() e la mappa è centrata sull'immagine:

// 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);

Il secondo parametro di Map.centerObject() è un livello di zoom, dove i numeri più alti indicano una scala più grande (zoom più elevato). I parametri per le funzioni Map sono descritti in dettaglio nel riferimento dell'API accessibile dalla scheda Documenti. Se l'aspetto dell'immagine non è soddisfacente, configura i parametri di visualizzazione con un argomento aggiuntivo per Map.addLayer(). Ad esempio:

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

Tieni presente che i parametri di visualizzazione sono definiti da un letterale oggetto, che include un elenco di bande da visualizzare, un valore di riflettanza minimo e massimo e un valore gamma. Scopri di più sulle bande Landsat qui. Scopri di più sulla visualizzazione delle immagini qui.

Utilizza Map.addLayer() per aggiungere elementi e raccolte di elementi alla mappa. Ad esempio:

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

Trovare immagini, raccolte di immagini e raccolte di elementi

Le immagini, le raccolte di immagini e le raccolte di elementi sono rilevabili cercando nel catalogo dati di Earth Engine. Ad esempio, se inserisci "Landsat 8" nel campo di ricerca, viene visualizzato un elenco di set di dati raster. L'elenco completo dei set di dati di Earth Engine è disponibile nel catalogo dati di Earth Engine. Fai clic sul nome del set di dati per visualizzare una breve descrizione, informazioni sulla disponibilità temporale, il fornitore di dati e l'ID raccolta. Fai clic sul pulsante Importa per creare automaticamente una sezione Importazioni nella parte superiore dello script con una variabile per questa raccolta.

In alternativa, copia l'ID collezione e incollalo nel codice. Ad esempio, scegli il risultato TOA di Livello 1 della ricerca "Landsat 8" e copia l'ID come segue:

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

Poiché si tratta di una raccolta di molte immagini che coprono la superficie terrestre, per trovare una singola immagine nella raccolta è necessario applicare filtri per restringere la ricerca. In alternativa, la raccolta di immagini può essere ridotta a una singola immagine utilizzando tecniche di composizione e di creazione di mosaici. Scopri di più su filtri e composizione (consulta Riduzione) nelle sezioni successive.

Le raccolte di elementi sono disponibili anche tramite Data Catalog. La loro rappresentazione è più piccola rispetto alle raccolte di immagini, ma puoi trovare confini internazionali, censuari, spartiacque e aree protette, per citarne alcuni. Scopri di più sull'importazione dei tuoi set di dati vettoriali qui.

Filtri e ordinamento

Spesso è necessario filtrare una raccolta per spazio e/o tempo per limitare il numero di risultati. Ad esempio, prendi in considerazione l'attività di ordinamento della raccolta di scene di Landsat 8 per trovare una scena senza nuvole per San Francisco. Innanzitutto, è necessario definire la regione di interesse. A questo scopo è spesso utile un punto. Attiva la scheda Inspector (Ispezione) sul lato destro dell'editor di codice e fai clic vicino al centro dell'area di interesse, copia le coordinate dalla scheda Inspector (Ispezione) e poi crea un Point utilizzando:

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

Crea le date di inizio e di fine:

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

Filtra la raccolta Landsat 8 utilizzando il punto e le date, poi ordina utilizzando una proprietà dei metadati (rilevata durante l'ispezione dei metadati della scena Landsat 8):

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

Questa raccolta può essere stampata e ispezionata in tutta sicurezza. Se la raccolta contiene troppe immagini, la stampa sarà molto lenta, scadrà il tempo di attesa o verrà restituito un errore. Tieni presente che le immagini nella raccolta sono un List memorizzato nella proprietà "features" del ImageCollection. L'ID di qualsiasi immagine della raccolta può essere copiato nel costruttore Image come sopra. In alternativa, acquisisci la prima immagine (copertura nuvolosa più bassa):

var first = filteredCollection.first();

Accedi alla funzionalità completa di filtri di Earth Engine utilizzando filter() con un ee.Filter come argomento. I metodi filterBounds() e filterDate() utilizzati sopra sono scorciatoie. Ad esempio, il seguente crea un Filter, lo utilizza per filtrare un FeatureCollection e mostra il risultato:

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

Calcoli relativi alle bande

Esegui operazioni matematiche sulle immagini utilizzando i metodi Image. Potrebbero essere incluse ricollegamenti di bande (indici spettrali), differenze di immagini o operazioni matematiche come la moltiplicazione per una costante. Ad esempio, calcola la differenza tra le immagini dell'indice di vegetazione a differenza normalizzata (NDVI) a distanza di 20 anni:

// 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);

Nota l'utilizzo di un function definito dall'utente in questo esempio. Scopri di più sulle funzioni nella sezione successiva.

Mappatura (cosa fare al posto di un ciclo for)

Utilizza map() per eseguire l'iterazione sugli elementi di una raccolta. I cicli For NON sono il modo corretto per farlo in Earth Engine e devono essere evitati. La funzione map() può essere applicata a un ImageCollection, un FeatureCollection o un List e accetta un function come argomento. L'argomento della funzione è un elemento della raccolta su cui è mappata. Questa operazione è utile per modificare ogni elemento della raccolta nello stesso modo, ad esempio per l'aggiunta. Ad esempio, il seguente codice aggiunge una banda NDVI a ogni immagine in 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);

Un'altra attività comune è l'aggiunta di una nuova proprietà (o "attributo" o "campo") agli elementi di un FeatureCollection. Nell'esempio seguente, la nuova proprietà è un calcolo che coinvolge due attributi esistenti:

// 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);

Tieni presente che il passaggio a ee.Number è necessario affinché il valore della proprietà sia riconosciuto come numero per poter utilizzare il metodo add(). Il tipo di raccolta può essere modificato da map(). Ad esempio:

// 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);

Prendi nota della proprietà aggiunta (foo) per ogni elemento creato dal centroide dell'immagine. Nell'ultima riga, il cast rende riconoscibile la collezione risultante come FeatureCollection.

In riduzione

La riduzione è il modo per aggregare i dati nel tempo, nello spazio, nelle bande, negli array e in altre strutture di dati in Earth Engine. Esistono vari metodi per questo scopo nell'API. Ad esempio, per creare un'immagine composita di un ImageCollection, utilizza reduce() per ridurre le immagini della raccolta a un'unica immagine. Un esempio semplice è la creazione della composizione mediana delle cinque scene meno nuvolose della raccolta Landsat 8 definita in precedenza:

// 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 riduzione è anche il modo per ottenere le statistiche di un'immagine nelle regioni definite da un Feature o FeatureCollection. Supponiamo che l'attività consista nel calcolare i valori medi dei pixel all'interno di un'area di interesse. Utilizza reduceRegion() per questo scopo. Ad esempio:

// 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
});

Scopri di più sui riduttori nel documento relativo ai riduttori.

Mascheramento

Ogni pixel in un ee.Image ha un valore e una maschera che vanno da 0 (nessun dato) a 1. I pixel mascherati (in cui mask==0) vengono considerati senza dati. I pixel con 0 < mask ≤ 1 hanno un valore, ma questo viene ponderato dalla maschera per i calcoli numerici.

Puoi rendere i pixel trasparenti o escluderli dall'analisi utilizzando le maschere. I pixel vengono mascherati quando il valore della maschera è zero. Continuando con l'esempio della differenza di immagini, utilizza una maschera per visualizzare le aree con NDVI aumentato e diminuito nell'intervallo di differenza:

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

In questo esempio, tieni presente che la maschera della differenza NDVI viene aggiornata dalla maschera del terreno con updateMask(). In questo modo, la maschera dei pixel della differenza NDVI viene impostata sulla maschera del suolo ovunque la maschera della differenza NDVI sia diversa da zero.

Il mascheramento è utile anche per escludere i dati dall'analisi. Prendi in considerazione l'esempio reduceRegion() riportato nella sezione Riduzione. Supponiamo che l'attività consista nel calcolare un NDVI medio stagionale per la contea di Santa Clara, in California, escludendo i pixel nuvolosi. L'esempio seguente mostra diversi concetti: filtri, mappatura, riduzione e utilizzo di una maschera di nuvole:

// 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);
});