Estatísticas de uma região de imagem

reduceRegion

Para receber estatísticas de valores de pixels 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 pixels na região (por exemplo, histograma). A região é representada como um Geometry, que pode ser um polígono, contendo muitos pixels, ou pode ser um único ponto, caso em que 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.

Figura 1. Uma ilustração de um ee.Reducer aplicado a uma imagem e uma região.

Para um exemplo de como receber 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 Serra Nevada (ilustrada pela 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 Code Editor vai mostrar como um Dictionary no console. A saída deve ser algo como:

B1: 25.406029716816853
B2: 23.971497014238988
B3: 22.91059593763103
B4: 54.83164133293403
B5: 38.07655472573677
B6_VCID_2: 198.93216428012906
B7: 24.063261634961563

Figura 2. Composto de cores falsas dos dados de imagem do Landsat para 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()), a geometry (region.geometry()), a scale (30 metros) e maxPixels para o número máximo de pixels a serem inseridos no redutor. Uma escala sempre precisa ser especificada nas reduceRegion() chamadas. 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 será determinada de forma inequívoca pelas entradas. Nesse caso, a escala padrão é de 1 grau, o que geralmente produz resultados insatisfatórios. Consulte esta página para mais informações sobre como o Earth Engine processa a escala.

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

// 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 como estando na região (e ponderados) de acordo com as seguintes regras, aplicadas na escala e projeção especificadas:

• Redutores não ponderados (por exemplo, ee.Reducer.count() ou ee.Reducer.mean().unweighted()): os pixels são incluídos se o centroide estiver na região e a máscara da imagem não for zero.
• Redutores ponderados (por exemplo, ee.Reducer.mean()): os pixels são incluídos se pelo menos (aproximadamente) 1/256 (~0,4%) do pixel estiver na região e a máscara da imagem não for zero. O peso é o mínimo da máscara da imagem e a fração (aproximada) do pixel coberto pela região. Os pesos de interseção de pixels são representados internamente como números inteiros de 8 bits (0 a 255), quantificando a cobertura fracionária em 256 níveis discretos.

Limite de quantização de peso de pixel: os pesos de interseção de pixels são representados internamente como números inteiros de 8 bits (de 0 a 255). Como resultado, qualquer fração de cobertura menor que aproximadamente 1/256 (~0,4%) será arredondada para um peso de 0 (inválido). Se a geometria de toda a região for menor que 1/256 da área nominal de um único pixel na scale especificada (por exemplo, menos de 0,4 km² em uma escala de 10.000 metros), todos os pixels vão receber um peso de 0, e a redução vai retornar null para estatísticas. Para evitar isso, use um parâmetro scale menor (que subdivide os pixels nativos, normalmente usando a interpolação do vizinho mais próximo) ou considere usar um conjunto de dados com um tamanho de pixel nativo menor.

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

Dictionary (Error)
  Image.reduceRegion: Too many pixels in the region. Found 527001545, but only 10000000 allowed.

Há várias opções para corrigir esses erros: aumentar maxPixels, como no exemplo, aumentar a scale ou definir bestEffort como verdadeiro, o 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.