圖片區域的統計資料

reduceRegion

如要取得 ee.Image 區域中像素值的統計資料，請使用 image.reduceRegion()。這會將區域中的所有像素縮減為統計資料，或是區域中像素資料的其他精簡表示法 (例如直方圖)。該區域會以 Geometry 表示，可能包含多個像素的多邊形，也可能只是單一點，在這種情況下，區域中只會有一個像素。如圖 1 所示，無論是哪種情況，輸出內容都是從區域中的像素衍生而來的統計資料。

reduceRegion 圖表
圖 1：插圖：ee.Reducer套用至圖片和區域。

如要瞭解如何使用 reduceRegion() 取得圖片區域的像素統計資料，請考慮找出內華達山脈針葉林邊界內 5 年 Landsat 複合影像的平均光譜值 (如圖 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);

如要強制運算，只要列印結果即可，程式碼編輯器會在控制台中顯示為 Dictionary。輸出內容應如下所示： 

B1: 25.406029716816853
B2: 23.971497014238988
B3: 22.91059593763103
B4: 54.83164133293403
B5: 38.07655472573677
B6_VCID_2: 198.93216428012906
B7: 24.063261634961563
reduceRegion 圖表
圖 2. 加州和內華達州的 Landsat 影像資料假色合成圖。要縮減的區域會以白色顯示。

請注意，在本範例中，縮減量是透過提供 reducer (ee.Reducer.mean())、geometry (region.geometry())、 scale (30 公尺) 和 maxPixels 指定，以輸入縮減量的最大像素數。請務必在 reduceRegion() 呼叫中指定比例。這是因為在複雜的處理流程中，可能涉及來自不同來源且規模不同的資料，因此輸出內容的規模無法明確地從輸入內容判斷。在這種情況下，縮放比例預設為 1 度，通常會產生不令人滿意的結果。如要進一步瞭解 Earth Engine 如何處理規模，請參閱這個頁面。

您可以透過兩種方式設定比例：指定 scale 參數，或指定 CRS 和 CRS 轉換。(如要進一步瞭解 CRS 和 CRS 轉換，請參閱詞彙表)。舉例來說，上述 meanDictionary 縮減等同於下列項目：

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

一般來說，指定比例就已足夠，且可讓程式碼更易於閱讀。 Earth Engine 會先將區域點陣化，然後決定要將哪些像素輸入至縮減函式。如果指定比例但未指定 CRS，系統會以圖片的原生投影方式，將區域點陣化為指定解析度。如果同時指定 CRS 和比例，系統會根據這些值將區域點陣化。

區域中的像素

系統會根據下列規則判斷像素是否位於區域內 (並加權)，並以指定的比例和投影方式套用這些規則：

  • 未加權縮減器 (例如 ee.Reducer.count() 或 ee.Reducer.mean().unweighted())：如果像素的質心位於區域內，且圖片的遮罩不為零，就會納入像素。
  • 加權縮減器 (例如 ee.Reducer.mean())： 如果像素至少 (約) 1/256 (~0.4%) 位於區域內，且圖片的遮罩不為零，則會納入像素；權重為圖片遮罩和區域涵蓋像素 (約) 分數的最小值。像素交集權重在內部會以 8 位元整數 (0 到 255) 表示，將分數涵蓋範圍量化為 256 個離散層級。

您必須提供 maxPixels 參數，才能成功計算。如果範例中缺少這個參數，系統會傳回類似下列的錯誤：

有多種方法可解決這些錯誤：增加 maxPixels (如範例所示)、增加 scale，或將 bestEffort 設為 true，這樣系統就會自動計算新的 (較大) 比例，確保不會超過 maxPixels。如未指定 maxPixels，系統會使用預設值。