Python 安装

Python 支持

Earth Engine Python 客户端库与 Google Cloud 支持的 Python 版本兼容。支持每年根据 Python 升级版本发布时间表(PEP 602;Python 版本状态)进行更新。使用不受支持的 Python 版本可能会导致身份验证失败、意外行为或某些操作失败。

安装选项

如果您使用的是 Google Colab,则最新版本的 Earth Engine Python 客户端库已安装(通过 pip)。请尝试使用以下笔记本,开始使用 Earth Engine 和 Colab:

如果您不使用 Colab,可以使用 conda(推荐)或 pip 在系统上手动安装和更新 Earth Engine 客户端库:


使用 pip 将 API 安装到任意 Python 环境。在终端或命令提示符中:

pip install earthengine-api

安装后,您可以按照此处所述导入 Earth Engine API、进行身份验证和初始化。

更新 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 项目,请参阅身份验证指南。

Hello world!

下面是一个简短的脚本,用于测试您是否已准备好使用 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 相关的常见语法差异。

JavaScript 和 Python 之间的常见语法差异
属性 JavaScript Python
函数定义
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
Null 值
var na = null;
na = None
评论
//
#

Date 对象

使用 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())
请注意,getInfo() 是同步操作,这意味着在结果返回到客户端之前,getInfo() 调用之后的表达式执行会被阻止。 此外,请求大量数据或进行高开销计算可能会返回错误和/或挂起。一般来说,最佳实践是导出结果,并在完成后将其导入新脚本中以进行进一步分析。

界面对象

Earth Engine ui 模块只能通过 JavaScript API 代码编辑器使用。在 Python 中使用第三方库来创建界面元素。geemap、Folium 和 ipyleaflet 等库可提供交互式地图显示,而 Matplotlib、Altair 或 seaborn 等库可用于绘制图表。如需了解如何使用 geemap 和 Matplotlib,请参阅 Earth Engine in Colab 设置笔记本中的示例。

开发者指南中的 Python

整个 Earth Engine 开发者指南中都包含 Python 代码。在可用情况下,您可以通过点击代码块顶部的“Colab (Python)”标签页来查看代码示例。 指南页面顶部可能还包含一些按钮,用于将页面作为 Colab 笔记本运行或在 GitHub 上查看。Python 代码示例旨在通过 Google Colab 运行。交互式地图和对象探索由 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)