Estatísticas de uma região de imagem

reduceRegion

Para conferir as estatísticas dos valores de pixel em uma região de um ee.Image, use image.reduceRegion(). Isso reduz todos os pixels nas regiões a uma estatística ou outra representação compacta dos dados de pixel na região (por exemplo, histograma). A região é representada como um Geometry, que pode ser um polígono contendo muitos pixels ou um único ponto. Nesse caso, haverá apenas um pixel na região. Em ambos os casos, conforme ilustrado na Figura 1, a saída é uma estatística derivada dos pixels na região.

diagrama de reduceRegion
Figura 1. Ilustração de um ee.Reducer aplicado a uma imagem e a uma região.

Para conferir um exemplo de como conferir estatísticas de pixels em uma região de uma imagem usando reduceRegion(), considere encontrar os valores espectrais médios de um composto Landsat de cinco anos dentro dos limites da floresta de coníferas da Sierra Nevada (ilustrado na 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);

Para forçar a computação, basta imprimir o resultado, que o editor de código vai mostrar como um Dictionary no console. A saída será semelhante a esta: 

B1: 25.406029716816853
B2: 23.971497014238988
B3: 22.91059593763103
B4: 54.83164133293403
B5: 38.07655472573677
B6_VCID_2: 198.93216428012906
B7: 24.063261634961563
diagrama de reduceRegion
Figura 2. Composição de falsa cor dos dados de imagem do Landsat para a Califórnia e Nevada. A região em que a redução será feita é mostrada em branco.

Neste exemplo, a redução é especificada fornecendo o reducer (ee.Reducer.mean()), o geometry (region.geometry()), o scale (30 metros) e o maxPixels para o número máximo de pixels a serem inseridos no redutor. Uma escala precisa ser sempre especificada em chamadas reduceRegion(). Isso ocorre porque, em fluxos de processamento complexos, que podem envolver dados de diferentes fontes com escalas diferentes, a escala da saída não é determinada de forma inequívoca pelas entradas. Nesse caso, a escala padrão é 1 grau, o que geralmente produz resultados insatisfatórios. Consulte esta página para mais informações sobre como o Earth Engine lida com a escala.

Há duas maneiras de definir a escala: especifique o parâmetro scale ou uma transformação CRS e CRS. Consulte o glossário para mais informações sobre CRS e transformações CRS. Por exemplo, a redução de meanDictionary (acima) é equivalente a:

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

Em geral, especificar a escala é suficiente e resulta em um código mais legível. O Earth Engine determina quais pixels serão inseridos no redutor primeiro rasterizando a região. Se uma escala for especificada sem um CRS, a região será rasterizada na projeção nativa da imagem, dimensionada para a resolução especificada. Se um CRS e uma escala forem especificados, a região será rasterizada com base neles.

Pixels na região

Os pixels são determinados para estar na região (e ponderados) de acordo com as seguintes regras, aplicadas na escala e projeção especificadas:

  • Redutor não ponderado (por exemplo, ee.Reducer.count() ou ee.Reducer.mean().unweighted()): os pixels são incluídos se o centroid deles estiver na região e a máscara da imagem não for zero.
  • Redutor ponderado (por exemplo, ee.Reducer.mean()): pixels são incluídos se pelo menos (aproximadamente) 0,5% do pixel estiver na região e a máscara da imagem não for zero. O peso deles é o mínimo da máscara da imagem e a (aproximação) fração do pixel coberto pela região.

O parâmetro maxPixels é necessário para que a computação seja bem-sucedida. Se esse parâmetro for deixado de fora do exemplo, um erro será retornado, semelhante a este:

Há várias opções para contornar esses erros: aumentar maxPixels, como no exemplo, aumentar o scale ou definir bestEffort como "true", que calcula automaticamente uma nova escala (maior) para que maxPixels não seja excedido. Se você não especificar maxPixels, o valor padrão será usado.