Statistiques d'une région d'image

reduceRegion

Pour obtenir des statistiques sur les valeurs de pixel dans une région d'une ee.Image, utilisez image.reduceRegion(). Tous les pixels de la ou des régions sont ainsi réduits à une statistique ou à une autre représentation compacte des données de pixel de la région (par exemple, un histogramme). La région est représentée par un Geometry, qui peut être un polygone contenant de nombreux pixels ou un seul point, auquel cas il n'y aura qu'un seul pixel dans la région. Dans les deux cas, comme illustré dans la figure 1, la sortie est une statistique dérivée des pixels de la région.

Schéma de reduceRegion
Figure 1. Illustration d'un ee.Reducer appliqué à une image et à une région.

Pour obtenir un exemple d'obtention de statistiques sur les pixels dans une région d'une image à l'aide de reduceRegion(), envisagez de trouver les valeurs spectrales moyennes d'un composite Landsat sur cinq ans dans les limites de la forêt de conifères de la Sierra Nevada (illustrée par la figure 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);

Pour forcer le calcul, il suffit d'imprimer le résultat, que l'éditeur de code affichera sous forme de Dictionary dans la console. Le résultat devrait ressembler à ceci: 

B1: 25.406029716816853
B2: 23.971497014238988
B3: 22.91059593763103
B4: 54.83164133293403
B5: 38.07655472573677
B6_VCID_2: 198.93216428012906
B7: 24.063261634961563
Schéma de reduceRegion
Figure 2. Composition fausse couleur des données d'image Landsat pour la Californie et le Nevada. La région sur laquelle effectuer la réduction s'affiche en blanc.

Notez que dans cet exemple, la réduction est spécifiée en fournissant les valeurs reducer (ee.Reducer.mean()), geometry (region.geometry()), scale (30 mètres) et maxPixels pour le nombre maximal de pixels à saisir dans le réducteur. Une échelle doit toujours être spécifiée dans les appels reduceRegion(). En effet, dans les flux de traitement complexes, qui peuvent impliquer des données provenant de différentes sources avec différentes échelles, l'échelle de la sortie ne sera pas déterminée de manière univoque à partir des entrées. Dans ce cas, l'échelle est définie par défaut sur 1 degré, ce qui produit généralement des résultats insatisfaisants. Pour en savoir plus sur la façon dont Earth Engine gère l'échelle, consultez cette page.

Il existe deux façons de définir l'échelle: en spécifiant le paramètre scale ou en spécifiant un système de coordonnées et une transformation de système de coordonnées. (Pour en savoir plus sur les systèmes de coordonnées et les transformations de coordonnées, consultez le glossaire.) Par exemple, la réduction meanDictionary (ci-dessus) équivaut à ce qui suit:

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

En règle générale, spécifier l'échelle est suffisant et permet d'obtenir un code plus lisible. Earth Engine détermine les pixels à saisir dans le réducteur en rasterisant d'abord la région. Si une échelle est spécifiée sans système de coordonnées projetées, la région est rasterisée dans la projection native de l'image, mise à l'échelle à la résolution spécifiée. Si un système de coordonnées et une échelle sont spécifiés, la région est rasterisée en fonction de ces éléments.

Pixels dans la région

Les pixels sont déterminés comme étant dans la région (et pondérés) selon les règles suivantes, appliquées à l'échelle et à la projection spécifiées:

  • Réducteurs non pondérés (par exemple, ee.Reducer.count() ou ee.Reducer.mean().unweighted()): les pixels sont inclus si leur centroïde se trouve dans la région et que le masque de l'image est différent de zéro.
  • Réducteurs pondérés (par exemple, ee.Reducer.mean()) : les pixels sont inclus si au moins (approximativement) 0,5% du pixel se trouve dans la région et que le masque de l'image est différent de zéro. Leur poids correspond au minimum du masque de l'image et de la fraction (approximative) du pixel recouvert par la région.

Le paramètre maxPixels est nécessaire pour que le calcul aboutisse. Si ce paramètre est omis de l'exemple, une erreur est renvoyée, qui se présente comme suit:

Il existe plusieurs options pour contourner ces erreurs: augmenter maxPixels, comme dans l'exemple, augmenter scale ou définir bestEffort sur "true", ce qui calcule automatiquement une nouvelle échelle (plus grande) afin que maxPixels ne soit pas dépassé. Si vous ne spécifiez pas maxPixels, la valeur par défaut est utilisée.