用戶端與伺服器

Earth Engine 的 Python 和 JavaScript 用戶端程式庫可將複雜的地理空間分析轉譯為 Earth Engine 要求。您為用戶端程式庫編寫的程式碼,可能同時包含用戶端物件的參照,以及代表伺服器端物件的變數。

請務必區分 Earth Engine 物件與程式碼中可能存在的其他 Python 或 JavaScript 物件或原始物件。只要在指令碼中操控用戶端「Proxy」物件,即可操控伺服器上的物件。凡是以 ee 開頭的物件,都是 Proxy 物件。這些 Earth Engine Proxy 物件不含任何實際資料,只是伺服器上物件的控制代碼。首先,請考慮用戶端字串物件 (「不是」Proxy 物件):

程式碼編輯器 (JavaScript)

var clientString = 'I am a String';
print(typeof clientString);  // string

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

client_string = 'I am a String'
print(type(client_string))  # str

從輸出內容中,您可以看到用戶端 (網路瀏覽器或筆記本) 已解讀並執行這段程式碼,判斷變數為 string 類型。現在假設您希望 Earth Engine 能夠對這個字串執行某些操作。為此,您需要將字串包裝在合適的容器中,然後傳送給 Google。這個容器就是 Proxy 物件。範例如下:

程式碼編輯器 (JavaScript)

var serverString = ee.String('I am not a String!');
print(typeof serverString);  // object
print('Is this an EE object?',
    serverString instanceof ee.ComputedObject);  // true

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

server_string = ee.String('I am not a String!')
print(type(server_string))  # ee.ee_string.String
print(
    'Is this an EE object?', isinstance(server_string, ee.ee_string.String)
)  # True

從輸出內容中,您會發現 ee.String 是 object,而非 string。具體來說,它是 ee.computedObject,這表示它是伺服器上某個項目的 Proxy 物件。您可以將 ee.Thing 視為將內容放入容器並傳送給 Google 的方式。用戶端不知道容器中的內容,但您可以透過列印容器來瞭解內容:

程式碼編輯器 (JavaScript)

print(serverString);  // I am not a String

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

print(server_string.getInfo())  # I am not a String

如要查看容器本身的樣貌,請輸出物件的字串表示法:

程式碼編輯器 (JavaScript)

print(serverString.toString());  // ee.String("I am not a String!")

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

print(server_string)  # ee.String({"constantValue": "I am not a String!"})

如果基於某些原因,您需要使用在用戶端執行的 Python 或 JavaScript 來操控容器中的任何內容,請使用 getInfo() 取得容器內容,並將其指派給變數:

程式碼編輯器 (JavaScript)

var someString = serverString.getInfo();
var strings = someString + '  Am I?';
print(strings);  // I am not a String!  Am I?

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

some_string = server_string.getInfo()
strings = some_string + '  Am I?'
print(strings)  # I am not a String!  Am I?

循環播放

由於用戶端不知道伺服器端 ee.Thing 物件中的內容,因此條件式和 for 迴圈等用戶端作業無法與這些物件搭配使用。因此,為避免同步呼叫 getInfo(),請盡可能使用伺服器函式。舉例來說,請考慮以下兩種建立清單的方式:

不建議:用戶端 for 迴圈

程式碼編輯器 (JavaScript)

var clientList = [];
for(var i = 0; i < 8; i++) {
  clientList.push(i + 1);
}
print(clientList);

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

client_list = []
for i in range(8):
  client_list.append(i + 1)
print(client_list)

建議:伺服器端對應

程式碼編輯器 (JavaScript)

var serverList = ee.List.sequence(0, 7);
serverList = serverList.map(function(n) {
  return ee.Number(n).add(1);
});
print(serverList);

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

server_list = ee.List.sequence(0, 7)
server_list = server_list.map(lambda n: ee.Number(n).add(1))
print(server_list.getInfo())

伺服器端對應範例有點不切實際,因為您只要使用 ee.List.sequence(1, 8) 就能建立相同的清單,但這說明瞭一些重要概念。第一個概念是 map(),這項功能只會將相同的函式套用至清單中的所有項目。由於這個函式是在伺服器上執行,因此 getInfo() 和 print() 等用戶端函式無法在對應函式中運作。因此,i + 1 程式碼必須替換為對等的伺服器端程式碼:ee.Number(n).add(1)。重要事項:n 是僅存在於伺服器上的物件 。由於函式不知道引數的類型,因此必須轉換為 ee.Number。

(如要瞭解哪些函式會在用戶端執行,請參閱用戶端和伺服器函式一節)。

另外值得注意的是,有時用戶端功能很方便。舉例來說,您可以使用先前的 for 迴圈建立清單,並使用伺服器端物件包裝:

程式碼編輯器 (JavaScript)

var toServerList = ee.List(clientList);

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

to_server_list = ee.List(client_list)

請注意,用戶端處理作業是在筆記本或瀏覽器 (主機機器的 CPU) 中完成,因此效率可能低於使用 Earth Engine 在伺服器上執行工作。此外,為避免可能出現令人意外的結果,建議您避免在指令碼中混合用戶端和伺服器功能。「條件」一節提供可能造成非預期後果的範例。

條件式

伺服器端物件不一定能與用戶端函式搭配使用,反之亦然。舉例來說,假設伺服器端布林值變數如下:

程式碼編輯器 (JavaScript)

var myList = ee.List([1, 2, 3]);
var serverBoolean = myList.contains(5);
print(serverBoolean);  // false

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

my_list = ee.List([1, 2, 3])
server_boolean = my_list.contains(5)
print(server_boolean.getInfo())  # False

如下例所示,變數不會在用戶端條件中運作,因為它是伺服器端物件。如要正確檢查伺服器端布林值,請使用伺服器端函式:

不建議:用戶端條件式

程式碼編輯器 (JavaScript)

var clientConditional;
if (serverBoolean) {
  clientConditional = true;
} else {
  clientConditional = false;
}
print('Should be false:', clientConditional);  // True!

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

if server_boolean:
  client_conditional = True
else:
  client_conditional = False
print('Should be False:', client_conditional)  # True!

建議:伺服器端條件式

程式碼編輯器 (JavaScript)

var serverConditional = ee.Algorithms.If(serverBoolean, 'True!', 'False!');
print('Should be false:', serverConditional);  // False!

Python 設定

如要瞭解 Python API 和使用 geemap 進行互動式開發,請參閱「Python 環境」頁面。

import ee
import geemap.core as geemap

Colab (Python)

server_conditional = ee.Algorithms.If(server_boolean, 'True!', 'False!')
print('Should be False:', server_conditional.getInfo())  # False!

用戶端和伺服器函式

前幾節說明瞭混合用戶端和伺服器物件和函式,為何效率不彰或不合邏輯。哪些物件和函式屬於用戶端,哪些屬於伺服器端?一般來說,任何初始化為 ee.Thing 的項目都是伺服器物件,而該物件上的任何方法 ee.Thing.method() 都是伺服器函式。出現在 Python 或 JavaScript 參考資料中的物件和函式位於用戶端。如前所述,您可以使用用戶端功能建立物件,然後將用戶端物件提供給 Earth Engine 建構函式 (例如 ee.String()),藉此包裝物件。