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

Hello world!

下面是一个简短的脚本，用于测试您是否已做好使用 Earth Engine 的准备。

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

语法

Python API 和 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())

界面对象

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

开发者指南中的 Python

Earth Engine 开发者指南中包含 Python 代码。如有代码示例，您可以点击代码块顶部的“Colab (Python)”标签页查看。 指南页面顶部可能还会包含用于将页面作为 Colab 笔记本运行或在 GitHub 上查看的按钮。Python 代码示例应使用 Google Colab 运行。互动式地图和对象探索由 geemap 库处理。Colab 中预安装了 Earth Engine Python 客户端库和 geemap。

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)