Statistiche di una regione di immagine

reduceRegion

Per ottenere statistiche sui valori dei pixel in una regione di un ee.Image, utilizza image.reduceRegion(). In questo modo, tutti i pixel nella regione o nelle regioni vengono ridotti a una statistica o a un'altra rappresentazione compatta dei dati pixel nella regione (ad es. istogramma). La regione è rappresentata come un Geometry, che potrebbe essere un poligono contenente molti pixel oppure un singolo punto, nel qual caso nella regione ci sarà un solo pixel. In entrambi i casi, come illustrato nella Figura 1, l'output è una statistica derivata dai pixel nella regione.

Diagramma reduceRegion
Figura 1. Un'illustrazione di un ee.Reducer applicato a un'immagine e a una regione.

Per un esempio di recupero delle statistiche dei pixel in una regione di un'immagine utilizzando reduceRegion(), considera di trovare i valori spettrali medi di un composito Landsat di 5 anni all'interno dei confini della foresta di conifere della Sierra Nevada (illustrata nella Figura 2):

// Load input imagery: Landsat 7 5-year composite.
var image = ee.Image('LANDSAT/LE7_TOA_5YEAR/2008_2012');

// Load an input region: Sierra Nevada.
var region = ee.Feature(ee.FeatureCollection('EPA/Ecoregions/2013/L3')
  .filter(ee.Filter.eq('us_l3name', 'Sierra Nevada'))
  .first());

// Reduce the region. The region parameter is the Feature geometry.
var meanDictionary = image.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: region.geometry(),
  scale: 30,
  maxPixels: 1e9
});

// The result is a Dictionary.  Print it.
print(meanDictionary);

Per forzare il calcolo, è sufficiente stampare il risultato, che l'editor di codice visualizzerà come Dictionary nella console. L'output dovrebbe essere simile al seguente: 

B1: 25.406029716816853
B2: 23.971497014238988
B3: 22.91059593763103
B4: 54.83164133293403
B5: 38.07655472573677
B6_VCID_2: 198.93216428012906
B7: 24.063261634961563
Diagramma reduceRegion
Figura 2. Composizione a falsi colori dei dati delle immagini Landsat per California e Nevada. La regione su cui ridurre è mostrata in bianco.

Tieni presente che in questo esempio la riduzione viene specificata fornendo reducer (ee.Reducer.mean()), geometry (region.geometry()), scale (30 metri) e maxPixels per il numero massimo di pixel da inserire nel riduttore. Una scala deve essere sempre specificata nelle chiamate reduceRegion(). Questo perché nei flussi di elaborazione complessi, che possono coinvolgere dati provenienti da origini diverse con scale diverse, la scala dell'output non sarà determinata in modo univoco dagli input. In questo caso, la scala è impostata su 1 grado, il che generalmente produce risultati insoddisfacenti. Per ulteriori informazioni su come Earth Engine gestisce la scala, consulta questa pagina.

Esistono due modi per impostare la scala: specificando il parametro scale o specificando un sistema di riferimento spaziale e una trasformazione del sistema di riferimento spaziale. (Per ulteriori informazioni su sistemi di riferimento delle coordinate e trasformazioni dei sistemi di riferimento delle coordinate, consulta il glossario). Ad esempio, la riduzione meanDictionary (sopra) equivale a quanto segue:

// As an alternative to specifying scale, specify a CRS and a CRS transform.
// Make this array by constructing a 4326 projection at 30 meters,
// then copying the bounds of the composite, from composite.projection().
var affine = [0.00026949458523585647, 0, -180, 0, -0.00026949458523585647, 86.0000269494563];

// Perform the reduction, print the result.
print(image.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: region.geometry(),
  crs: 'EPSG:4326',
  crsTransform: affine,
  maxPixels: 1e9
}));

In generale, specificare la scala è sufficiente e produce un codice più leggibile. Earth Engine determina quali pixel inserire nel riduttore rasterizzando prima la regione. Se viene specificata una scala senza un sistema di riferimento spaziale, la regione viene rasterizzata nella proiezione nativa dell'immagine scalata alla risoluzione specificata. Se vengono specificati sia un CRS che una scala, la regione viene rasterizzata in base a questi valori.

Pixel nella regione

I pixel vengono considerati nella regione (e ponderati) in base alle seguenti regole, applicate nella scala e nella proiezione specificate:

  • Riduttori non ponderati (ad es. ee.Reducer.count() o ee.Reducer.mean().unweighted()): i pixel vengono inclusi se il loro centroide si trova nella regione e la maschera dell'immagine è diversa da zero.
  • Riduttori ponderati (ad es. ee.Reducer.mean()): i pixel vengono inclusi se almeno (circa) 1/256 (~0,4%) del pixel si trova nella regione e la maschera dell'immagine è diversa da zero; il loro peso è il minimo tra la maschera dell'immagine e la frazione (approssimativa) del pixel coperta dalla regione. I pesi dell'intersezione dei pixel sono rappresentati internamente come numeri interi a 8 bit (da 0 a 255), quantizzando la copertura frazionaria in 256 livelli discreti.

Il parametro maxPixels è necessario per il corretto calcolo. Se questo parametro viene omesso dall'esempio, viene restituito un errore simile al seguente:

Esistono diverse opzioni per superare questi errori: aumenta maxPixels, come nell'esempio, aumenta scale o imposta bestEffort su true, che calcola automaticamente una nuova scala (più grande) in modo che maxPixels non venga superato. Se non specifichi maxPixels, viene utilizzato il valore predefinito.