Начните работу с Earth Engine

Это руководство по началу работы предназначено для быстрого начала программирования с помощью API JavaScript Earth Engine. Вводный обзор JavaScript и более подробные упражнения с API Earth Engine см. в учебных пособиях . Рекомендуемый стиль кодирования JavaScript см. в Руководстве по стилю JavaScript Google .

Google Earth Engine позволяет пользователям запускать алгоритмы на основе изображений с географической привязкой и векторов, хранящихся в инфраструктуре Google. API Google Earth Engine предоставляет библиотеку функций, которые можно применять к данным для отображения и анализа. Каталог общедоступных данных Earth Engine содержит большое количество общедоступных наборов изображений и векторных данных. Частные активы также можно создавать в личных папках пользователей.

Как использовать эти документы

Документация Earth Engine предназначена для людей, знакомых с анализом геопространственных данных. Документы в основном структурированы по типам данных. Например, левая панель навигации содержит ссылки на разделы или страницы, посвященные важным типам данных, таким как Image , ImageCollection , Feature , FeatureCollection , Geometry , Reducer , Chart , Join и Array . В этом руководстве описано только достаточно информации об этих типах, чтобы вы могли начать работу. Есть также разделы, посвященные машинному обучению , специализированным алгоритмам или алгоритмам, специфичным для датчиков ( например, алгоритмы Landsat ), общедоступным приложениям , управлению данными (активами) и важной информации о внутренней работе Earth Engine . Прежде чем погрузиться в это, начните здесь!

Редактор кода

Редактор кода — это интерактивная среда для разработки приложений Earth Engine (рис. 1). На центральной панели имеется редактор кода JavaScript. Над редактором расположены кнопки сохранения текущего скрипта, его запуска и очистки карты. Кнопка «Получить ссылку» генерирует уникальный URL-адрес сценария в адресной строке. Карта на нижней панели содержит слои, добавленные скриптом. Вверху находится поле поиска наборов данных и мест. Левая панель содержит примеры кода, ваши сохраненные сценарии, ссылку на API с возможностью поиска и менеджер активов для личных данных. На правой панели есть инспектор для запроса карты, консоль вывода и менеджер длительно выполняющихся задач. Кнопка help в правом верхнем углу содержит ссылки на это руководство и другие ресурсы для получения помощи. Дополнительные сведения см. в руководстве по редактору кода и в руководстве «Помощь» .

Открытие и запуск кода в редакторе кода

Приведенные ниже шаги демонстрируют, как открыть Earth Engine и выполнить собственный скрипт, отображающий изображение. Для достижения наилучших результатов вы можете установить последнюю версию Chrome, веб-браузера Google, доступную здесь .

1. Откройте редактор кода Earth Engine здесь: code.earthengine.google.com .
2. Перейдите на вкладку «Сценарии» , расположенную в крайнем левом углу редактора кода. Там вы найдете коллекцию примеров скриптов, которые получают доступ, отображают и анализируют данные Earth Engine.
3. В разделе «Коллекция изображений» выберите пример «Фильтрованная композиция». Вы увидите скрипт на центральной консоли. Нажмите кнопку «Выполнить» , чтобы выполнить скрипт. В примере «Фильтрованное соединение» выбираются изображения 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() :

var image3 = image1.add(image2);

Этот метод добавляет полосы image2 к полосам image1 . Категория ee.Algorithms содержит список поддерживаемых в настоящее время алгоритмов для специализированной или предметной обработки. Например, чтобы создать топографические слои из входной цифровой модели рельефа (DEM):

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

Специальные функции редактора кода включают методы Map и Export , которые управляют тем, как слои добавляются на панель карты или экспортируются на Google Диск соответственно. Функции также можно создавать в JavaScript, используя

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

Как показано в разделе «Сопоставление» , определяемые пользователем функции полезны для создания пользовательских функций или изменения элементов коллекции с помощью:

var collection2 = collection1.map(aFunction);

Следующие разделы иллюстрируют эти концепции для различных простых случаев использования.

'Привет, мир!' JavaScript

Вывод информации на консоль — это основная задача для получения информации об объекте, отображения числового результата вычисления, отображения метаданных объекта или помощи при отладке. Знаменитая надпись «Hello World!» пример в редакторе кода:

print('Hello world!');

Скопируйте эту строку в редактор кода Code Editor и нажмите «Выполнить» . Обратите внимание, что выходные данные отображаются на вкладке «Консоль » справа от редактора кода. В качестве примера, более подходящего для дистанционного зондирования, ниже распечатываются метаданные изображения Landsat 8:

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

Внимательно проверьте вывод в консоли, чтобы увидеть метаданные, доступные для изображений Landsat.

Добавление данных на карту

Помимо вывода информации на консоль, добавление данных на Map — это способ визуализации географических данных. Для этого используйте Map.addLayer() . В следующем примере создается экземпляр Image (о том, как найти эти изображения, будет рассказано позже) с помощью ee.Image() , добавляется на карту с помощью Map.addLayer() и карта центрируется над изображением:

// 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() . Например:

// 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() чтобы добавить на карту объекты и коллекции объектов. Например,

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

Поиск изображений, коллекций изображений и коллекций объектов

Изображения, коллекции изображений и коллекции объектов можно обнаружить с помощью поиска в каталоге данных Earth Engine. Например, если ввести «Landsat 8» в поле поиска, появится список наборов растровых данных. (Полный список наборов данных Earth Engine можно найти в Каталоге данных Earth Engine ). Нажмите на имя набора данных, чтобы получить краткое описание, информацию о временной доступности, поставщике данных и идентификаторе коллекции. Нажмите кнопку «Импорт» , чтобы автоматически создать раздел «Импорт» в верхней части скрипта с переменной для этой коллекции.

Либо скопируйте идентификатор коллекции и вставьте его в свой код. Например, выберите результат TOA уровня 1 в поиске «Landsat 8» и скопируйте идентификатор следующим образом:

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

Поскольку это коллекция множества изображений, охватывающих поверхность Земли, для поиска отдельного изображения в коллекции требуется фильтрация, чтобы сузить поиск. Альтернативно, коллекцию изображений можно свести к одному изображению, используя методы композиции и мозаики. Подробнее о фильтрации и композиции (см. Сокращение ) в следующих разделах.

Коллекции объектов также доступны через Каталог данных. Их представленность меньше, чем в коллекциях изображений, но вы найдете международные границы, границы переписи населения, водоразделы и охраняемые территории, и это лишь некоторые из них. Узнайте больше об импорте собственных наборов векторных данных здесь .

Фильтрация и сортировка

Часто бывает необходимо отфильтровать коллекцию по пространству и/или времени, чтобы ограничить количество результатов. Например, рассмотрим задачу сортировки коллекции сцен Landsat 8, чтобы найти безоблачную сцену для Сан-Франциско. Во-первых, необходимо определить интересующую область. Для этого часто бывает полезна точка. Активируйте вкладку «Инспектор» в правой части редактора кода и щелкните рядом с центром интересующей вас области, скопируйте координаты с вкладки «Инспектор» , затем создайте Point используя:

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

Постройте даты начала и окончания:

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

Отфильтруйте коллекцию Landsat 8, используя точку и даты, затем отсортируйте ее по свойству метаданных (обнаруженному во время проверки метаданных сцены Landsat 8):

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

Эту коллекцию можно смело распечатать и просмотреть. (Если в коллекции слишком много изображений, ее печать будет либо очень медленной, либо по истечении времени ожидания, либо вернет ошибку). Обратите внимание, что изображения в коллекции представляют собой List , хранящийся в свойстве 'features' ImageCollection . Идентификатор любого изображения в коллекции можно скопировать в конструктор Image как указано выше. Альтернативно, получите первое изображение (самая низкая облачность):

var first = filteredCollection.first();

Получите доступ ко всем функциям фильтрации Earth Engine, используя filter() с аргументом ee.Filter . (Использованные выше методы filterBounds() и filterDate() являются сокращенными). Например, следующий пример создает Filter , использует его для фильтрации FeatureCollection и отображает результат:

// 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 . Это может включать рекомбинацию полос (спектральные индексы), дифференцирование изображений или математические операции, такие как умножение на константу. Например, вычислите разницу между изображениями нормализованного индекса растительности (NDVI) с разницей в 20 лет:

// 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 в этом примере. Подробнее о функциях в следующем разделе.

Сопоставление (что делать вместо цикла for)

Используйте map() для перебора элементов коллекции. (Циклы for НЕ являются правильным способом сделать это в Earth Engine, и их следует избегать). Функция map() может быть применена к ImageCollection , FeatureCollection или List и принимает function в качестве аргумента. Аргументом функции является элемент коллекции, с которой она сопоставляется. Это полезно для одинакового изменения каждого элемента коллекции, например добавления. Например, следующий код добавляет полосу NDVI к каждому изображению в ImageCollection :

// 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 . В следующем примере новое свойство представляет собой вычисление, включающее два существующих атрибута:

// 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);

Обратите внимание на приведение к ee.Number необходимое для того, чтобы значение свойства распознавалось как число для использования метода add() ). Тип коллекции можно изменить с помощью map() . Например:

// 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, определенной ранее:

// 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() . Например:

// 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
});

Узнайте больше о редукторах из документа «Редукторы».

Маскировка

Каждый пиксель в ee.Image имеет как значение, так и маску, которая находится в диапазоне от 0 (нет данных) до 1. Замаскированные пиксели (в которых маска == 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 не равна нулю.

Маскирование также полезно для исключения данных из анализа. Рассмотрим пример reduceRegion() из раздела Сокращение . Предположим, что задача состоит в том, чтобы вычислить среднее сезонное значение NDVI для округа Санта-Клара, штат Калифорния, исключая облачные пиксели. В следующем примере демонстрируется несколько концепций: фильтрация, сопоставление, уменьшение и использование облачной маски:

// 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);
});