Statistiche di una regione di immagine

reduceRegion

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

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

Per un esempio di acquisizione delle statistiche dei pixel in una regione di un'immagine utilizzando reduceRegion(), valuta la possibilità 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 dalla 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 mostrerà 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 di reduceRegion
Figura 2. Composito a falsi colori dei dati delle immagini Landsat per California e Nevada. La regione su cui applicare la riduzione è indicata 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. Deve sempre essere specificata una scala 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 verrà determinata in modo inequivocabile dagli input. In questo caso, la scala è impostata su 1 grado, il che in genere produce risultati insoddisfacenti. Per ulteriori informazioni su come Earth Engine gestisce la scalabilità, consulta questa pagina.

Esistono due modi per impostare la scala: specificando il parametro scale o specificando un sistema di riferimento e una trasformazione del sistema di riferimento. (consulta il glossario per maggiori informazioni su sistemi di riferimento cartografico e trasformazioni CRS). Ad esempio, la riduzione di meanDictionary (sopra) è equivalente 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 genere, è sufficiente specificare la scala per ottenere un codice più leggibile. Earth Engine determina quali pixel inviare al riduttore rasterizzando prima la regione. Se viene specificata una scala senza un sistema di riferimento, la regione viene rasterizzata nella proiezione nativa dell'immagine con la scala della risoluzione specificata. Se vengono specificati sia un sistema di riferimento cartografico sia una scala, la regione viene rasterizzata in base a questi valori.

Pixel nella regione

I pixel vengono considerati all'interno della regione (e ponderati) in base alle seguenti regole, applicate alla scala e alla proiezione specificate:

  • Riduttore non ponderato (ad es. ee.Reducer.count() o ee.Reducer.mean().unweighted()): i pixel vengono inclusi se il loro centroide è nella regione e la maschera dell'immagine è diversa da zero.
  • Riduttoreni ponderati (ad es. ee.Reducer.mean()): i pixel vengono inclusi se almeno (approssimativamente) lo 0,5% del pixel si trova nella regione e la maschera dell'immagine non è pari a zero; il loro peso è il minimo della maschera dell'immagine e della (approssimativa) frazione del pixel coperta dalla regione.

Il parametro maxPixels è necessario per il completamento del calcolo. Se questo parametro non è incluso nell'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.