适用于 Python 和 JavaScript 的 Earth Engine 客户端库可将复杂的地理空间分析转换为 Earth Engine 请求。您为客户端库编写的代码可能包含对客户端对象的引用和表示服务器端对象的变量。
请务必区分 Earth Engine 对象与代码中可能存在的其他 Python 或 JavaScript 对象或基元。您可以通过在脚本中操作客户端“代理”对象来操作服务器上的对象。您可以将任何以 ee 开头的内容识别为代理对象。这些 Earth Engine 代理对象不包含任何实际数据,只是服务器上对象的句柄。首先,考虑一个客户端字符串对象(不是代理对象):
代码编辑器 (JavaScript)
var clientString = 'I am a String'; print(typeof clientString); // string
import ee import geemap.core as geemap
Colab (Python)
client_string = 'I am a String' print(type(client_string)) # str
从输出中观察到,客户端(网络浏览器或笔记本)已解释并运行此代码,确定变量类型为 string。现在,假设您希望 Earth Engine 能够对此字符串执行某些操作。为此,您需要将字符串封装在一个合适的容器中,然后将其发送给 Google。该容器就是代理对象。示例如下:
代码编辑器 (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
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,这意味着它是服务器上某个对象的代理对象。您可以将 ee.Thing 视为将内容放入容器中以发送给 Google 的方式。您的客户端不知道容器中有什么,但您可以通过输出容器内容来了解其中有什么:
代码编辑器 (JavaScript)
print(serverString); // I am not a String
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!")
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?
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);
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);
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);
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
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!
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!
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())来封装该对象。