Python 安裝

Python 支援

Earth Engine Python 用戶端程式庫與 Google Cloud 支援的 Python 版本相容。支援服務會依照 Python 版本發布時程 (PEP 602；Python 版本狀態) 每年更新一次。使用未支援的 Python 版本可能會導致驗證失敗、非預期行為或特定作業失敗。

安裝選項

如果您使用 Google Colab，系統已透過 pip 安裝最新版本的 Earth Engine Python 用戶端程式庫。請試用下列筆記本，開始使用 Earth Engine 和 Colab：

在 Google Colab 中執行

前往 GitHub 查看來源

如果您不使用 Colab，可以使用 conda (建議) 或 pip，在系統上手動安裝及更新 Earth Engine 用戶端程式庫：

pip install earthengine-api

pip install earthengine-api --upgrade

套件匯入

Python API 套件稱為 ee。您必須針對每個新的 Python 工作階段和指令碼匯入及初始化：

import ee

驗證和初始化

在使用 Earth Engine Python 用戶端程式庫之前，您必須進行驗證，並使用產生的憑證來初始化 Python 用戶端。執行：

ee.Authenticate()

系統會為您的環境選取最佳驗證模式，並提示您確認指令碼的存取權。如要進行初始化，您必須提供自己擁有的專案，或具備使用權限。這個專案會用於執行所有 Earth Engine 作業：

ee.Initialize(project='my-project')

如要瞭解如何排解問題，以及進一步瞭解驗證模式和 Cloud 專案，請參閱驗證指南。

向全世界問好！

以下是一段簡短的指令碼，可用於測試您是否已準備好使用 Earth Engine。

import ee
ee.Authenticate()
ee.Initialize(project='my-project')
print(ee.String('Hello from the Earth Engine servers!').getInfo())

語法

Python 和 JavaScript API 都會存取相同的伺服器端功能，但由於語法差異，用戶端運算式 (進一步瞭解用戶端與伺服器的差異) 可能會有所不同。下表列出使用 Python API 時，與 JavaScript API 相比會遇到的常見語法差異。

function myFun(arg) {
  return arg;
}

var myFun = function(arg) {
  return arg;
};

def my_fun(arg):
  return arg

var foo = col.map(function(arg) {
  return arg;
});

foo = col.map(lambda arg: arg)

var myVar = 'var';

my_var = 'var'

var match = such.and(that);
var match = such.or(that);
var match = such.not(that);

match = such.And(that)
match = such.Or(that)
match = such.Not(that)

var foo = my.really()
              .reallyLong()
              .methodChain();

foo = (my.really()
       .reallyLong()
       .methodChain())

var dic = {'key': value};
var dic = {key: value};

dic = {'key': value}

var value = dic.key;
var value = dic['key'];

value = dic['key']

// Positional arguments.
var foo = fun(argX, argY, argZ);
// Keyword arguments object.
var foo = fun({y: argY});

# Positional arguments.
foo = fun(arg_x, arg_y, arg_z)
# Keyword arguments dictionary.
foo = fun(**{'y': arg_y})
# Keyword arguments.
foo = fun(x=arg_x, z=arg_z)

var t = true;
var f = false;

t = True
f = False

var na = null;

na = None

//

#

日期物件

使用 datetime 模組定義及操作用戶端日期物件。在指令碼中加入模組：

import datetime

將 ee.Date 轉換為用戶端日期：

ee_date = ee.Date('2020-01-01')
py_date = datetime.datetime.utcfromtimestamp(ee_date.getInfo()['value']/1000.0)

將用戶端日期轉換為 ee.Date:

py_date = datetime.datetime.utcnow()
ee_date = ee.Date(py_date)

正在匯出資料

使用 Python API 匯出資料時，必須使用 ee.batch 模組，該模組會提供 Export 函式的介面。請按照使用 JavaScript API 的方式傳遞參數引數，並留意上方語法表中所述的差異。匯出工作必須透過在已定義的工作上呼叫 start() 方法來啟動。對工作呼叫 status() 方法，查詢工作狀態。以下範例說明如何匯出 ee.Image 物件。

建立匯出工作：

task = ee.batch.Export.image.toDrive(image=my_image,  # an ee.Image object.
                                     region=my_geometry,  # an ee.Geometry object.
                                     description='mock_export',
                                     folder='gdrive_folder',
                                     fileNamePrefix='mock_export',
                                     scale=1000,
                                     crs='EPSG:4326')

開始匯出工作：

task.start()

查看匯出工作狀態：

task.status()

task.status() 的結果是字典，其中包含任務狀態和 ID 等資訊。

{
  'state': 'READY',
  'description': 'my_export_task',
  'creation_timestamp_ms': 1647567508236,
  'update_timestamp_ms': 1647567508236,
  'start_timestamp_ms': 0,
  'task_type': 'EXPORT_IMAGE',
  'id': '56TVJIZABUMTD5CJ5YHTMYK4',
  'name': 'projects/earthengine-legacy/operations/56TVJIZABUMTX5CJ5HHTMYK4'
}

您可以使用 state 欄位監控工作進度。如要查看 state 值的 清單，以及進一步瞭解工作生命週期，請參閱「處理環境」頁面。

列印物件

在 Python 中列印 Earth Engine 物件，會列印物件的序列化要求，而非物件本身。如要瞭解原因，請參閱「用戶端與伺服器」頁面。

對 Earth Engine 物件呼叫 getInfo()，從伺服器取得所需物件並傳送至用戶端：

# Load a Landsat image.
img = ee.Image('LANDSAT/LT05/C02/T1_L2/LT05_034033_20000913')

# Print image object WITHOUT call to getInfo(); prints serialized request instructions.
print(img)

# Print image object WITH call to getInfo(); prints image metadata.
print(img.getInfo())

UI 物件

Earth Engine ui 模組只能透過 JavaScript API 程式碼編輯器使用。在 Python 中使用 UI 元素的第三方程式庫。geemap、Folium 和 ipyleaflet 等程式庫可提供互動式地圖顯示功能，而 Matplotlib、Altair 或 seaborn 等程式庫則可用於繪製圖表。如要瞭解如何使用 geemap 和 Matplotlib，請參閱 Colab 中的 Earth Engine 設定筆記本中的範例。

開發人員指南中的 Python

Earth Engine 開發人員指南中包含 Python 程式碼。如有可用的程式碼範例，只要按一下程式碼區塊頂端的「Colab (Python)」分頁標籤即可查看。指南頁面頂端也可能會提供按鈕，讓您以 Colab 筆記本的形式執行頁面，或在 GitHub 上查看頁面。請使用 Google Colab 執行 Python 程式碼範例。互動式地圖和物件探索由 geemap 程式庫處理。Earth Engine Python 用戶端程式庫和 geemap 都已預先安裝在 Colab 中。

Earth Engine 設定

執行 Python 程式碼時，您必須匯入 Earth Engine 程式庫、驗證並初始化。範例中使用了下列指令 (如需替代方案，請參閱「驗證和初始化」頁面)。

import ee
ee.Authenticate()
ee.Initialize(project='my-project')

使用 geemap 進行互動式探索

geemap 程式庫可用於顯示地圖圖塊，以及列印 Earth Engine 物件的豐富表示法。針對這些功能，程式庫分別依附於 ipyleaflet 和 eerepr。geemap 程式庫及其依附元件已預先安裝在 Google Colab 中，請將其匯入至每個工作階段。

import geemap.core as geemap

您可以使用 geemap.Map 物件查看地理 Earth Engine 資料類別，例如 ee.Image 和 ee.FeatureCollection。首先，請定義地圖物件。接著，新增圖層或變更可視區域。

# Initialize a map object.
m = geemap.Map()

# Define an example image.
img = ee.Image.random()

# Add the image to the map.
m.add_layer(img, None, 'Random image')

# Display the map (you can call the object directly if it is the final line).
display(m)