開始使用 Earth Engine

本入門指南旨在協助您快速開始使用 Earth Engine JavaScript API 進行程式設計。如需 JavaScript 簡介和 Earth Engine API 的進階練習,請參閱教學課程。如需建議的 JavaScript 編碼樣式,請參閱 Google JavaScript 樣式指南。

Google Earth Engine 可讓使用者在 Google 基礎架構上儲存的地理參照圖像和向量上執行演算法。Google Earth Engine API 提供函式庫,可套用至資料,用於顯示及分析。Earth Engine 的公開資料目錄包含大量公開可用的圖像和向量資料集。您也可以在個人資料夾中建立私人資產。

如何使用這些文件

Earth Engine 說明文件的適用對象為熟悉地理空間資料分析的人員。文件主要依資料類型分類。舉例來說,左側導覽面板包含重要資料類型相關章節或頁面的連結,例如 Image、ImageCollection、Feature、FeatureCollection、Geometry、Reducer、Chart、Join 和 Array。本指南僅提供這些類型的基本說明,此外,還有機器學習、專門或感應器專用演算法 (例如 Landsat 演算法)、公開應用程式、資料 (資產) 管理,以及 Earth Engine 內部運作的重要詳細資料。在深入瞭解上述內容之前,請先從這裡開始!

程式碼編輯器

程式碼編輯器是開發 Earth Engine 應用程式的互動式環境 (圖 1)。中央面板提供 JavaScript 程式碼編輯器。編輯器上方有儲存目前指令碼、執行指令碼和清除地圖的按鈕。「Get Link」(取得連結) 按鈕會為網址列中的指令碼產生專屬網址。底部面板中的地圖包含指令碼新增的圖層。頂端是資料集和地點的搜尋框。左側面板包含程式碼範例、已儲存的指令碼、可搜尋的 API 參考資料,以及私人資料的資產管理工具。右側面板則有查詢地圖的檢查器、輸出控制台,以及長時間執行工作的管理工具。右上方的說明按鈕 包含本指南和其他資源的連結,可協助您取得協助。詳情請參閱程式碼編輯器指南和支援小幫手。

程式碼編輯器
圖 1. Earth Engine 程式碼編輯器 (code.earthengine.google.com)

在程式碼編輯器中開啟並執行程式碼

以下步驟說明如何開啟 Earth Engine,並執行顯示圖片的自訂指令碼。為獲得最佳效果,建議您安裝最新版本 Chrome,這是 Google 的網路瀏覽器,可前往這裡下載。

  1. 開啟 Earth Engine 程式碼編輯器: code.earthengine.google.com。
  2. 前往程式碼編輯器最左側的「Scripts」分頁。您可以在這裡找到一系列範例指令碼,用於存取、顯示及分析 Earth Engine 資料。
  3. 在「Image Collection」下方,選取「Filtered Composite」範例。中央控制台會顯示指令碼。按下「Run」按鈕執行指令碼。「Filtered Composite」範例會選取與科羅拉多州和猶他州交集或位於其邊界內的 Landsat 7 圖片。然後顯示所選圖片的真彩合成圖。範例會介紹常用的方法,例如 filter()、clip() 和 Map.addLayer()。

Earth Engine 資料結構

Earth Engine 中最基本的兩種地理資料結構為 Image 和 Feature,分別對應光柵和向量資料類型。圖片是由波段和屬性字典組成。 地圖項目是由 Geometry 和屬性字典組成。一組圖片 (例如圖片時間序列) 是由 ImageCollection 處理。一組特徵由 FeatureCollection 處理。Earth Engine 的其他基本資料結構包括 Dictionary、List、Array、Date、Number 和 String (如要進一步瞭解基本資料類型,請參閱本教學課程)。請務必注意,這些都是「伺服器端」物件,操作方式與用戶端 JavaScript 物件不同 (瞭解詳情)。

Earth Engine 演算法

在 API 中執行作業的方式有幾種:

  • 呼叫附加至物件的方法。
  • 呼叫演算法。
  • 呼叫程式碼編輯器專屬函式。
  • 定義新函式。

程式碼編輯器的「Docs」(文件) 分頁會列出每個 API 類別的方法。舉例來說,Image 類別具有 add() 方法:

程式碼編輯器 (JavaScript)

var image3 = image1.add(image2);

這個方法會將 image2 的波段新增至 image1 的波段。 ee.Algorithms 類別包含目前支援的演算法清單,可用於專業或特定領域的處理作業。例如,如要從輸入的數位高程模型 (DEM) 建立地形圖層,請按照下列步驟操作:

程式碼編輯器 (JavaScript)

var terrainImage = ee.Algorithms.Terrain(dem);

程式碼編輯器專屬函式包括 Map 和 Export 方法,分別控制如何將圖層新增至地圖面板,或匯出至 Google 雲端硬碟。您也可以使用 JavaScript 建立函式

程式碼編輯器 (JavaScript)

var myFunction = function(args) {
  // do something
  return something;
};

如地圖一節所示,使用者定義函式可用於建立自訂功能,或使用下列項目修改集合元素:

程式碼編輯器 (JavaScript)

var collection2 = collection1.map(aFunction);

以下各節將說明這些概念在各種簡單用途中的應用。

'Hello world!' JavaScript

將資訊輸出至控制台是一項基本工作,可讓您取得物件相關資訊、顯示運算的數值結果、顯示物件中繼資料,或協助偵錯。程式碼編輯器中的經典「Hello World!」範例如下:

程式碼編輯器 (JavaScript)

print('Hello world!');

將這行程式碼複製到程式碼編輯器的程式碼編輯器中,然後按一下「Run」(執行)。請注意,輸出內容會顯示在程式碼編輯器右側的「Console」分頁中。以下範例與遙測更相關,會列印 Landsat 8 圖片的中繼資料:

程式碼編輯器 (JavaScript)

print(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318'));

仔細檢查控制台中的輸出內容,查看 Landsat 圖片可用的中繼資料。

在地圖中新增資料

除了將資訊輸出至控制台,將資料新增至 Map 也是視覺化地理資料的方式。請使用 Map.addLayer() 執行這項操作。在以下範例中,系統會使用 ee.Image() 例項化 Image (稍後會說明如何找到這些圖片),並使用 Map.addLayer() 將其新增至地圖,然後將地圖置中於圖片上方:

程式碼編輯器 (JavaScript)

// Load an image.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');

// Center the map on the image.
Map.centerObject(image, 9);

// Display the image.
Map.addLayer(image);

Map.centerObject() 的第二個參數是縮放等級,數字越大表示比例越大 (放大程度越高)。如要深入瞭解 Map 函式的參數,請參閱「文件」分頁中的 API 參考資料。如果圖片外觀不盡理想,請使用 Map.addLayer() 的額外引數設定顯示參數。例如:

程式碼編輯器 (JavaScript)

// Load the image from the archive.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');

// Define visualization parameters in an object literal.
var vizParams = {bands: ['B5', 'B4', 'B3'], min: 0.02, max: 0.4, gamma: 1.3};

// Center the map on the image and display.
Map.centerObject(image, 9);
Map.addLayer(image, vizParams, 'Landsat 8 false color');

請注意,視覺化參數是由物件常值定義,其中包含要顯示的波段清單、反射率最小值和最大值,以及 gamma 值。(如要進一步瞭解 Landsat 波段,請按這裡。如要進一步瞭解圖片視覺呈現,請按這裡。

使用 Map.addLayer() 將地圖項目和地圖項目集合新增至地圖。舉例來說,

程式碼編輯器 (JavaScript)

var counties = ee.FeatureCollection('TIGER/2018/Counties');
Map.addLayer(counties, {}, 'counties');

尋找圖片、圖片集和特徵集

搜尋 Earth Engine 資料目錄,即可找到圖片、圖片集合和特徵集合。舉例來說,在搜尋欄位中輸入「Landsat 8」,就會產生光柵資料集清單。(如需 Earth Engine 資料集的完整清單,請前往 Earth Engine Data Catalog)。按一下資料集名稱,即可查看簡短說明、時間可用性、資料提供者和集合 ID。按一下「Import」按鈕,系統就會自動在指令碼頂端建立「Imports」部分,並為這個集合建立變數。

或者,您也可以複製集合 ID 並貼到程式碼中。舉例來說,選擇「Landsat 8」搜尋結果中的第 1 級 TOA,並複製 ID,如下所示:

程式碼編輯器 (JavaScript)

var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA');

由於這個集合包含許多涵蓋地球陸地表面的圖片,因此您必須篩選集合中的個別圖片,才能縮小搜尋範圍。或者,您也可以使用合成和鑲嵌技術,將圖片集合縮減為單一圖片。如要進一步瞭解篩選和合成 (請參閱「縮減」),請參閱後續章節。

您也可以透過 Data Catalog 取得特徵集合。雖然這類資料的數量少於圖片集合,但您仍可找到國際、人口普查、流域和保護區邊界等資料。如要進一步瞭解如何匯入自己的向量資料集,請參閱這篇文章。

篩選及排序

通常需要依空間和/或時間篩選集合,才能限制結果數量。舉例來說,假設您要排序 Landsat 8 場景集合,找出舊金山沒有雲層的場景。首先,必須定義感興趣的區域。這時通常適合使用點。啟用程式碼編輯器右側的「Inspector」分頁,然後點選所需區域中心附近,從「Inspector」分頁複製座標,然後使用以下程式碼建構 Point:

程式碼編輯器 (JavaScript)

var point = ee.Geometry.Point(-122.262, 37.8719);

建立開始和結束日期:

程式碼編輯器 (JavaScript)

var start = ee.Date('2014-06-01');
var finish = ee.Date('2014-10-01');

使用點和日期篩選 Landsat 8 集合,然後使用中繼資料屬性排序 (在檢查 Landsat 8 場景中繼資料時發現):

程式碼編輯器 (JavaScript)

var filteredCollection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(point)
  .filterDate(start, finish)
  .sort('CLOUD_COVER', true);

您可以放心列印及檢查這個集合。(如果集合中的圖片過多,列印速度會非常慢、逾時或傳回錯誤)。請注意,集合中的圖片是儲存在 ImageCollection 的「features」屬性中的 List。集合中任何圖片的 ID 都可以複製到 Image 建構函式中,如上所示。或者,您也可以取得第一張圖片 (雲層覆蓋率最低):

程式碼編輯器 (JavaScript)

var first = filteredCollection.first();

使用 filter() 並以 ee.Filter 做為引數,即可存取完整的 Earth Engine 篩選功能。(上述 filterBounds() 和 filterDate() 方法是捷徑)。舉例來說,以下程式碼會建立 Filter,並用來篩選 FeatureCollection,然後顯示結果:

程式碼編輯器 (JavaScript)

// Load a feature collection.
var featureCollection = ee.FeatureCollection('TIGER/2016/States');

// Filter the collection.
var filteredFC = featureCollection.filter(ee.Filter.eq('NAME', 'California'));

// Display the collection.
Map.setCenter(-119.604, 37.798, 6);
Map.addLayer(filteredFC, {}, 'California');

波段數學

使用 Image 方法對圖片執行數學運算。這可能包括波段重組 (光譜指數)、圖像差異或數學運算,例如乘以常數。例如,計算相隔 20 年的歸一化差值植生指標 (NDVI) 圖片之間的差異:

程式碼編輯器 (JavaScript)

// This function gets NDVI from Landsat 5 imagery.
var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.
var image1 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_20100611');

// Compute NDVI from the scenes.
var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);

請注意,這個範例使用了使用者定義的 function。下一節會進一步說明函式。

Map (for 迴圈的替代做法)

使用 map() 疊代集合中的項目。(For 迴圈並非在 Earth Engine 中執行這項操作的正確方式,應避免使用)。map() 函式可套用至 ImageCollection、FeatureCollection 或 List,並接受 function 做為引數。函式的引數是集合中對應的元素。這項功能很實用,可讓您以相同方式修改集合中的每個元素,例如新增。舉例來說,下列程式碼會將 NDVI 波段新增至 ImageCollection 中的每張圖片:

程式碼編輯器 (JavaScript)

// This function gets NDVI from Landsat 8 imagery.
var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// Load the Landsat 8 TOA data, filter by location and date.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the collection.
var ndviCollection = collection.map(addNDVI);

另一項常見工作是為 FeatureCollection 中的地圖項目新增屬性 (或「欄位」)。在以下範例中,新屬性是涉及兩個現有屬性的運算:

程式碼編輯器 (JavaScript)

// This function creates a new property that is the sum of two existing properties.
var addField = function(feature) {
  var sum = ee.Number(feature.get('property1')).add(feature.get('property2'));
  return feature.set({'sum': sum});
};

// Create a FeatureCollection from a list of Features.
var features = ee.FeatureCollection([
  ee.Feature(ee.Geometry.Point(-122.4536, 37.7403),
    {property1: 100, property2: 100}),
    ee.Feature(ee.Geometry.Point(-118.2294, 34.039),
    {property1: 200, property2: 300}),
]);

// Map the function over the collection.
var featureCollection = features.map(addField);

// Print a selected property of one Feature.
print(featureCollection.first().get('sum'));

// Print the entire FeatureCollection.
print(featureCollection);

請注意,必須轉換為 ee.Number,屬性值才會被視為數字,以便使用 add() 方法。您可以使用 map() 變更集合類型。例如:

程式碼編輯器 (JavaScript)

// This function returns the image centroid as a new Feature.
var getGeom = function(image) {
  return ee.Feature(image.geometry().centroid(), {foo: 1});
};

// Load a Landsat 8 TOA collection.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the ImageCollection.
var featureCollection = ee.FeatureCollection(collection.map(getGeom));

// Print the collection.
print(featureCollection);

請注意,系統會為從圖片群集中心建立的每個地圖項目新增屬性 (foo)。在最後一行中,轉換會將產生的集合識別為 FeatureCollection。

遏止

縮減是指在 Earth Engine 中,隨著時間、空間、頻帶、陣列和其他資料結構匯總資料。API 提供多種方法,可達成這項目標。舉例來說,如要建立 ImageCollection 的合成影像,請使用 reduce() 將集合中的影像縮減為一個 Image。舉例來說,您可以建立中位數合成影像,其中包含先前定義的 Landsat 8 集合中,雲量最少的五個場景:

程式碼編輯器 (JavaScript)

// Load a Landsat 8 TOA collection.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  // Filter by date and location.
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-01-01', '2014-12-31')
  // Sort by increasing cloudiness.
  .sort('CLOUD_COVER');

// Compute the median of each pixel for each band of the 5 least cloudy scenes.
var median = collection.limit(5).reduce(ee.Reducer.median());

縮減也是取得 Feature 或 FeatureCollection 定義區域中圖片統計資料的方法。假設工作是計算感興趣區域內的平均像素值。請使用 reduceRegion() 執行這項操作。例如:

程式碼編輯器 (JavaScript)

// Load and display a Landsat TOA image.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');
Map.addLayer(image, {bands: ['B4', 'B3', 'B2'], max: 0.3});

// Create an arbitrary rectangle as a region and display it.
var region = ee.Geometry.Rectangle(-122.2806, 37.1209, -122.0554, 37.2413);
Map.addLayer(region);

// Get a dictionary of means in the region.  Keys are bandnames.
var mean = image.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: region,
  scale: 30
});

如要進一步瞭解縮減器,請參閱縮減器說明文件。

面具

ee.Image 中的每個像素都有一個值和一個遮罩,範圍從 0 (無資料) 到 1。遮罩像素 (遮罩==0) 會視為無資料。如果像素的遮罩值介於 0 和 1 之間 (不含 0),則像素會有值,但會依遮罩加權,用於數值運算。

您可以使用遮罩,將像素設為透明或排除在分析範圍之外。如果遮罩值為零,像素就會遮蓋。繼續使用圖片差異範例,使用遮罩顯示差異間隔內 NDVI 增加和減少的區域:

// This function gets NDVI from Landsat 5 imagery.
var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.
var image1 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_20100611');

// Compute NDVI from the scenes.
var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);
// Load the land mask from the SRTM DEM.
var landMask = ee.Image('CGIAR/SRTM90_V4').mask();

// Update the NDVI difference mask with the land mask.
var maskedDifference = ndviDifference.updateMask(landMask);

// Display the masked result.
var vizParams = {min: -0.5, max: 0.5, palette: ['FF0000', 'FFFFFF', '0000FF']};
Map.setCenter(-122.2531, 37.6295, 9);
Map.addLayer(maskedDifference, vizParams, 'NDVI difference');

在這個範例中,請注意 NDVI 差異的遮罩會由土地遮罩以 updateMask() 更新。只要 NDVI 差異遮罩不為零,這項操作就會將 NDVI 差異像素的遮罩設為陸地遮罩。

遮蓋功能也可用於排除分析資料。請參考「縮減」一節中的 reduceRegion() 範例。假設任務是計算加州聖塔克拉拉郡的季節性平均 NDVI,不含多雲像素。以下範例示範多個概念:篩選、對應、縮減和使用雲遮罩:

程式碼編輯器 (JavaScript)

// This function gets NDVI from a Landsat 8 image.
var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// This function masks cloudy pixels.
var cloudMask = function(image) {
  var clouds = ee.Algorithms.Landsat.simpleCloudScore(image).select(['cloud']);
  return image.updateMask(clouds.lt(10));
};

// Load a Landsat collection, map the NDVI and cloud masking functions over it.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point([-122.262, 37.8719]))
  .filterDate('2014-03-01', '2014-05-31')
  .map(addNDVI)
  .map(cloudMask);

// Reduce the collection to the mean of each pixel and display.
var meanImage = collection.reduce(ee.Reducer.mean());
var vizParams = {bands: ['B5_mean', 'B4_mean', 'B3_mean'], min: 0.02, max: 0.4};
Map.addLayer(meanImage, vizParams, 'mean');

// Load a region in which to compute the mean and display it.
var counties = ee.FeatureCollection('TIGER/2018/Counties');
var santaClara = ee.Feature(counties.filter(ee.Filter.eq('NAME', 'Santa Clara')).first());
Map.addLayer(santaClara);

// Get the mean of NDVI in the region.
var mean = meanImage.select(['nd_mean']).reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: santaClara.geometry(),
  scale: 30
});

// Print mean NDVI for the region.
mean.get('nd_mean').evaluate(function(val){
  print('Santa Clara spring mean NDVI:', val);
});