Earth Engine 使用入门

本入门指南旨在帮助您快速开始使用 Earth Engine JavaScript API 进行编程。如需初步了解 JavaScript 并通过 Earth Engine API 进行更深入的练习,请参阅教程。如需了解推荐的 JavaScript 编码样式,请参阅 Google JavaScript 样式指南。

借助 Google Earth Engine,用户可以对存储在 Google 基础架构中的地理配准图像和矢量运行算法。Google Earth Engine API 提供了一个函数库,可应用于数据以进行显示和分析。Earth Engine 的公共数据目录包含大量公开可用的图像和矢量数据集。您还可以在用户的个人文件夹中创建不公开的资产。

如何使用这些文档

Earth Engine 文档面向熟悉地理空间数据分析的用户。这些文档主要按数据类型进行组织。例如,左侧导航栏包含指向重要数据类型(例如 Image、ImageCollection、Feature、FeatureCollection、Geometry、Reducer、Chart、Join 和 Array)相关部分或页面的链接。本指南仅对这些类型进行了简要介绍,以便您快速上手。此外,还有机器学习、专用或传感器专用算法(例如 Landsat 算法)、面向公众的应用、数据(资产)管理以及 Earth Engine 内部运作的重要细节等部分。 在深入了解这些内容之前,请先从这里开始!

代码编辑器

代码编辑器是一个用于开发 Earth Engine 应用的交互式环境(图 1)。中间面板提供了一个 JavaScript 代码编辑器。编辑器上方有用于保存当前脚本、运行脚本和清除地图的按钮。获取链接按钮会在地址栏中为脚本生成一个唯一网址。底部面板中的地图包含脚本添加的图层。顶部是数据集和地点的搜索框。左侧面板包含代码示例、您保存的脚本、可搜索的 API 参考文档以及用于管理私密数据的资产管理器。右侧面板包含一个用于查询地图的检查器、一个显示结果控制台和一个用于长时间运行的任务的管理器。右上角的帮助按钮 包含指向本指南和其他资源的链接,可帮助您获取帮助。 如需了解详情,请参阅代码编辑器指南和智能助手指南。

代码编辑器
图 1. Earth Engine 代码编辑器 (code.earthengine.google.com)

在代码编辑器中打开并运行代码

以下步骤演示了如何打开 Earth Engine 并执行显示图片的自定义脚本。为了获得最佳效果,您可能需要安装最新版本的 Chrome(Google 的网络浏览器),该浏览器可从此处获取。

  1. 在此处打开 Earth Engine 代码编辑器: code.earthengine.google.com。
  2. 前往代码编辑器最左侧的脚本标签页。您可以在其中找到一系列示例脚本,这些脚本可用于访问、显示和分析 Earth Engine 数据。
  3. 在“Image Collection”(图片集)下,选择“Filtered Composite”(过滤后的合成图片)示例。您会看到中央控制台中出现一个脚本。按运行按钮以执行脚本。“Filtered Composite”示例会选择与科罗拉多州和犹他州边界相交或位于其边界内的 Landsat 7 图像。然后,它会显示所选图片的真彩色合成。这些示例介绍了常用的方法,例如 filter()、clip() 和 Map.addLayer()。

Earth Engine 数据结构

Earth Engine 中最基本的两种地理数据结构是 Image 和 Feature,分别对应于光栅和矢量数据类型。图片由波段和属性字典组成。 特征由 Geometry 和属性字典组成。一堆图片(例如图片时序)由 ImageCollection 处理。地图项集合由 FeatureCollection 处理。Earth Engine 中的其他基本数据结构包括 Dictionary、List、Array、Date、Number 和 String(如需详细了解基本数据类型,请参阅此教程)。请务必注意,这些都是服务器端对象,其操作方式与客户端 JavaScript 对象不同(了解详情)。

Earth Engine 算法

您可以通过多种方式在 API 中运行操作:

  • 调用附加到对象的方法。
  • 调用算法。
  • 调用代码编辑器特定函数。
  • 定义新函数。

代码编辑器的文档标签页列出了每个 API 类的方法。例如,Image 类具有 add() 方法:

代码编辑器 (JavaScript)

var image3 = image1.add(image2);

此方法会将 image2 的波段添加到 image1 的波段。 ee.Algorithms 类别包含当前支持的用于专用或特定领域处理的算法列表。例如,如需根据输入的数字高程模型 (DEM) 创建地形图层,请执行以下操作:

代码编辑器 (JavaScript)

var terrainImage = ee.Algorithms.Terrain(dem);

代码编辑器特有的函数包括 Map 和 Export 方法,它们分别控制如何将图层添加到地图面板或导出到 Google 云端硬盘。您还可以使用 JavaScript 创建函数

代码编辑器 (JavaScript)

var myFunction = function(args) {
  // do something
  return something;
};

如地图部分所示,用户定义的函数可用于创建自定义功能或使用以下内容修改集合的元素:

代码编辑器 (JavaScript)

var collection2 = collection1.map(aFunction);

以下部分针对各种简单用例说明了这些概念。

'Hello world!' JavaScript

将信息输出到控制台是一项基本任务,用于获取对象的相关信息、显示计算的数值结果、显示对象元数据或帮助进行调试。代码编辑器中的标志性“Hello World!”示例为:

代码编辑器 (JavaScript)

print('Hello world!');

将此行复制到代码编辑器的代码编辑器中,然后点击运行。请注意,输出会显示在代码编辑器右侧的控制台标签页中。对于更相关的遥感示例,以下代码会输出 Landsat 8 图像的元数据:

代码编辑器 (JavaScript)

print(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318'));

仔细检查控制台中的输出,查看 Landsat 影像的可用元数据。

向地图添加数据

除了将信息输出到控制台之外,向 Map 添加数据也是直观呈现地理数据的一种方式。请使用 Map.addLayer() 执行此操作。在以下示例中,使用 ee.Image() 实例化 Image(稍后将介绍如何查找这些图片),使用 Map.addLayer() 将其添加到地图中,并将地图居中显示在图片上:

代码编辑器 (JavaScript)

// Load an image.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');

// Center the map on the image.
Map.centerObject(image, 9);

// Display the image.
Map.addLayer(image);

Map.centerObject() 的第二个参数是缩放级别,数字越大,表示比例越大(放得更大)。Map 函数的参数在 API 参考文档中有深入说明,您可以通过文档标签页访问该文档。如果图片的外观不令人满意,请使用 Map.addLayer() 的其他参数配置显示参数。例如:

代码编辑器 (JavaScript)

// Load the image from the archive.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');

// Define visualization parameters in an object literal.
var vizParams = {bands: ['B5', 'B4', 'B3'], min: 0.02, max: 0.4, gamma: 1.3};

// Center the map on the image and display.
Map.centerObject(image, 9);
Map.addLayer(image, vizParams, 'Landsat 8 false color');

请注意,可视化参数由对象字面量定义,其中包括要显示的波段列表、最小和最大反射率值以及伽马值。 (如需详细了解 Landsat 波段,请点击此处。如需详细了解图片可视化,请点击此处)。

使用 Map.addLayer() 向地图添加地图项和地图项集合。例如,

代码编辑器 (JavaScript)

var counties = ee.FeatureCollection('TIGER/2018/Counties');
Map.addLayer(counties, {}, 'counties');

查找图片、图片集和特征集

您可以通过搜索 Earth Engine 数据目录来发现图片、图片集合和特征集合。例如,在搜索字段中输入“Landsat 8”会生成一个栅格数据集列表。(Earth Engine 数据集的完整列表位于 Earth Engine Data Catalog中)。点击数据集名称,即可查看简要说明、时间可用性信息、数据提供方和集合 ID。点击导入按钮,系统会在脚本顶部自动创建一个导入部分,其中包含此集合的变量。

或者,复制集合 ID 并将其粘贴到代码中。例如,选择“Landsat 8”搜索结果中的 Tier 1 TOA 结果,并复制其 ID,如下所示:

代码编辑器 (JavaScript)

var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA');

由于这是一个包含覆盖地球陆地表面的许多图片的集合,因此需要在集合中查找单个图片,以便缩小搜索范围。 或者,您也可以使用合成和拼接技术将图片集合缩减为单张图片。如需详细了解过滤和合成(请参阅缩减),请参阅后续部分。

您还可以通过 Data Catalog 获取地图项集合。其表示形式小于图片集合,但您会发现国际、人口普查、流域和保护区边界等。如需详细了解如何导入自己的矢量数据集,请点击此处。

过滤和排序

通常需要按空间和/或时间过滤集合,以限制结果数量。例如,假设您要对 Landsat 8 场景集合进行排序,以便找到旧金山的无云场景。首先,需要定义感兴趣的区域。点通常适用于此目的。激活代码编辑器右侧的检查器标签页,点击感兴趣区域的中心附近,从检查器标签页中复制坐标,然后使用以下代码构建 Point:

代码编辑器 (JavaScript)

var point = ee.Geometry.Point(-122.262, 37.8719);

构建开始日期和结束日期:

代码编辑器 (JavaScript)

var start = ee.Date('2014-06-01');
var finish = ee.Date('2014-10-01');

使用点和日期过滤 Landsat 8 集合,然后使用元数据属性(在检查 Landsat 8 场景元数据时发现)进行排序:

代码编辑器 (JavaScript)

var filteredCollection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(point)
  .filterDate(start, finish)
  .sort('CLOUD_COVER', true);

此集合可以安全地打印和检查。(如果集合包含过多图片,打印速度会非常慢、超时或返回错误)。请注意,集合中的图片是存储在 ImageCollection 的“features”属性中的 List。集合中任何图片的 ID 都可以复制到 Image 构造函数中,如上所示。或者,获取第一张图片(云量最低):

代码编辑器 (JavaScript)

var first = filteredCollection.first();

使用 filter() 并将 ee.Filter 作为参数,即可访问完整的 Earth Engine 过滤功能。(上面使用的 filterBounds() 和 filterDate() 方法是快捷方式)。例如,以下代码会创建一个 Filter,使用它来过滤 FeatureCollection,并显示结果:

代码编辑器 (JavaScript)

// Load a feature collection.
var featureCollection = ee.FeatureCollection('TIGER/2016/States');

// Filter the collection.
var filteredFC = featureCollection.filter(ee.Filter.eq('NAME', 'California'));

// Display the collection.
Map.setCenter(-119.604, 37.798, 6);
Map.addLayer(filteredFC, {}, 'California');

波段数学

使用 Image 方法对图片执行数学运算。这可能包括波段重组(光谱指数)、图像差分或数学运算(例如乘以常数)。例如,计算相隔 20 年的归一化植被指数 (NDVI) 图像之间的差异:

代码编辑器 (JavaScript)

// This function gets NDVI from Landsat 5 imagery.
var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.
var image1 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_20100611');

// Compute NDVI from the scenes.
var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);

请注意,此示例中使用了用户定义的 function。下一部分将详细介绍函数。

Map(不使用 for 循环时的替代方案)

使用 map() 遍历集合中的项。(在 Earth Engine 中,for 循环不是实现此目的的正确方法,应避免使用)。map() 函数可应用于 ImageCollection、FeatureCollection 或 List,并接受 function 作为其参数。函数的参数是其映射到的集合中的元素。这对于以相同方式修改集合中的每个元素(例如添加)非常有用。例如,以下代码会向 ImageCollection 中的每张图片添加 NDVI 波段:

代码编辑器 (JavaScript)

// This function gets NDVI from Landsat 8 imagery.
var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// Load the Landsat 8 TOA data, filter by location and date.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the collection.
var ndviCollection = collection.map(addNDVI);

另一项常见任务是向 FeatureCollection 中的特征添加新属性(或“特性”或“字段”)。在以下示例中,新属性是涉及两个现有属性的计算:

代码编辑器 (JavaScript)

// This function creates a new property that is the sum of two existing properties.
var addField = function(feature) {
  var sum = ee.Number(feature.get('property1')).add(feature.get('property2'));
  return feature.set({'sum': sum});
};

// Create a FeatureCollection from a list of Features.
var features = ee.FeatureCollection([
  ee.Feature(ee.Geometry.Point(-122.4536, 37.7403),
    {property1: 100, property2: 100}),
    ee.Feature(ee.Geometry.Point(-118.2294, 34.039),
    {property1: 200, property2: 300}),
]);

// Map the function over the collection.
var featureCollection = features.map(addField);

// Print a selected property of one Feature.
print(featureCollection.first().get('sum'));

// Print the entire FeatureCollection.
print(featureCollection);

请注意,为了使用 add() 方法,需要将属性值转换为 ee.Number,以便将其识别为数字。集合的类型可以通过 map() 进行更改。例如:

代码编辑器 (JavaScript)

// This function returns the image centroid as a new Feature.
var getGeom = function(image) {
  return ee.Feature(image.geometry().centroid(), {foo: 1});
};

// Load a Landsat 8 TOA collection.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the ImageCollection.
var featureCollection = ee.FeatureCollection(collection.map(getGeom));

// Print the collection.
print(featureCollection);

请注意,通过图片质心创建的每个地图项都添加了属性 (foo)。在最后一行中,类型转换使生成的集合可识别为 FeatureCollection。

减少

缩减是在 Earth Engine 中按时间、空间、波段、数组和其他数据结构汇总数据的方法。API 中有多种方法可实现此目的。例如,如需制作 ImageCollection 的合成图像,请使用 reduce() 将集合中的图像缩减为一张图像。一个简单的示例是,为之前定义的 Landsat 8 集合中云量最少的五个场景创建中位数合成:

代码编辑器 (JavaScript)

// Load a Landsat 8 TOA collection.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  // Filter by date and location.
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-01-01', '2014-12-31')
  // Sort by increasing cloudiness.
  .sort('CLOUD_COVER');

// Compute the median of each pixel for each band of the 5 least cloudy scenes.
var median = collection.limit(5).reduce(ee.Reducer.median());

缩减也是获取由 Feature 或 FeatureCollection 定义的区域中图片统计信息的方法。假设任务是计算感兴趣区域内的平均像素值。为此,请使用 reduceRegion()。例如:

代码编辑器 (JavaScript)

// Load and display a Landsat TOA image.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');
Map.addLayer(image, {bands: ['B4', 'B3', 'B2'], max: 0.3});

// Create an arbitrary rectangle as a region and display it.
var region = ee.Geometry.Rectangle(-122.2806, 37.1209, -122.0554, 37.2413);
Map.addLayer(region);

// Get a dictionary of means in the region.  Keys are bandnames.
var mean = image.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: region,
  scale: 30
});

如需详细了解 Reducer,请参阅 Reducer 文档。

面具

ee.Image 中的每个像素都有一个值和一个掩码,范围从 0(无数据)到 1。被遮盖的像素(即 mask==0 的像素)会被视为无数据。0 < 掩膜 ≤ 1 的像素具有值,但该值会按掩膜进行加权,以进行数值计算。

您可以使用遮罩使像素透明或将其从分析中排除。当遮罩值为零时,像素会被遮盖。继续使用图像差分示例,使用遮罩显示差分间隔内 NDVI 增加和减少的区域:

// This function gets NDVI from Landsat 5 imagery.
var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.
var image1 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_20100611');

// Compute NDVI from the scenes.
var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);
// Load the land mask from the SRTM DEM.
var landMask = ee.Image('CGIAR/SRTM90_V4').mask();

// Update the NDVI difference mask with the land mask.
var maskedDifference = ndviDifference.updateMask(landMask);

// Display the masked result.
var vizParams = {min: -0.5, max: 0.5, palette: ['FF0000', 'FFFFFF', '0000FF']};
Map.setCenter(-122.2531, 37.6295, 9);
Map.addLayer(maskedDifference, vizParams, 'NDVI difference');

在此示例中,请注意,NDVI 差异的掩膜会通过 updateMask() 由陆地掩膜更新。这会将 NDVI 差异像素的掩膜设置为陆地掩膜,只要 NDVI 差异掩膜不为零。

遮盖功能还可用于从分析中排除数据。以“Reduce”部分中的 reduceRegion() 示例为例。假设任务是计算加利福尼亚州圣克拉拉县的季节性平均 NDVI,不包括多云像素。以下示例演示了多个概念:过滤、映射、缩减和使用云遮罩:

代码编辑器 (JavaScript)

// This function gets NDVI from a Landsat 8 image.
var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// This function masks cloudy pixels.
var cloudMask = function(image) {
  var clouds = ee.Algorithms.Landsat.simpleCloudScore(image).select(['cloud']);
  return image.updateMask(clouds.lt(10));
};

// Load a Landsat collection, map the NDVI and cloud masking functions over it.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .filterBounds(ee.Geometry.Point([-122.262, 37.8719]))
  .filterDate('2014-03-01', '2014-05-31')
  .map(addNDVI)
  .map(cloudMask);

// Reduce the collection to the mean of each pixel and display.
var meanImage = collection.reduce(ee.Reducer.mean());
var vizParams = {bands: ['B5_mean', 'B4_mean', 'B3_mean'], min: 0.02, max: 0.4};
Map.addLayer(meanImage, vizParams, 'mean');

// Load a region in which to compute the mean and display it.
var counties = ee.FeatureCollection('TIGER/2018/Counties');
var santaClara = ee.Feature(counties.filter(ee.Filter.eq('NAME', 'Santa Clara')).first());
Map.addLayer(santaClara);

// Get the mean of NDVI in the region.
var mean = meanImage.select(['nd_mean']).reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: santaClara.geometry(),
  scale: 30
});

// Print mean NDVI for the region.
mean.get('nd_mean').evaluate(function(val){
  print('Santa Clara spring mean NDVI:', val);
});