Как зарегистрировать объекты Cloud Optimized GeoTIFF (COG)

Earth Engine поддерживает объекты, основанные на файлах Cloud Optimized GeoTIFF (COG), которые хранятся в Google Cloud Storage (GCS).

При регистрации объекта, поддерживаемого COG, Earth Engine индексирует пространственные поля и поля метаданных изображения во время создания. Это позволяет эффективно использовать изображение в коллекциях, обеспечивая производительность, сравнимую со стандартными загруженными объектами (см. обзор Cloud Optimized GeoTIFF (COG)).

В этом руководстве рассказывается, как подготовить файлы, написать манифест, отправить запрос на регистрацию, настроить разрешения, а также обновить или удалить зарегистрированные объекты.

Подготовка

Прежде чем регистрировать COG, необходимо правильно настроить ресурсы Cloud Storage.

Местоположение сегмента

Чтобы у Earth Engine был доступ к вашему сегменту Cloud Storage, он должен находиться в одном из следующих регионов или макрорегионов центров обработки данных:

  • Макрорегион us
  • Любой двойной регион в США, включающий us-central1.
  • Регион us-central1

Если сегмент находится в любом другом региональном центре обработки данных (например, us-east4 или europe-west1), Earth Engine отклонит запросы на регистрацию и чтение. Ознакомьтесь с поддерживаемыми местоположениями сегментов Cloud Storage.

Класс хранилища и оплата

  • Рекомендуем использовать класс хранилища Standard. В стандартном хранилище нет правил, определяющих минимальный срок хранения, поэтому вы не будете платить штрафы за раннее удаление, если обновите или замените временные файлы.
  • Хотя циклы вычислений Earth Engine не влекут за собой дополнительных сборов за извлечение данных Cloud Storage, доступ к уровням хранения, отличным от стандартного хранилища, из внешних инструментов (таких как настольное программное обеспечение ГИС) влечет за собой дорогостоящие сборы за извлечение.
  • Чтобы использовать Cloud Storage, в вашем облачном проекте Google Cloud должны быть включены платежные функции. Чтобы начать работу, ознакомьтесь с кратким руководством по Cloud Storage.

Подготовьте данные о себестоимости реализованной продукции

Earth Engine считывает COG-файлы непосредственно из Cloud Storage, извлекая только заголовок и фрагменты, необходимые для вычислений, поэтому макет файла имеет значение. Файл TIFF должен:

  • Тайловый, с квадратными тайлами, размеры которых являются степенями двойки (от 16 x 16 до 2048 x 2048). Рекомендуемый размер – 512 x 512.
  • Все каталоги графических файлов (IFD) должны находиться в начале.
  • Включите обзоры со степенями двойки, если они есть. Обзорные изображения не обязательны, но рекомендуются для изображений, размер которых превышает размер одного фрагмента.
  • Используйте чередование BAND или PIXEL (см. сравнение одноканальных и многоканальных файлов).

Чтобы преобразовать изображение, используйте драйвер COG GDAL, который за один шаг создает требуемый макет (разбиение на фрагменты, обзорные изображения и размещение заголовков). Добавьте OVERVIEW_RESAMPLING=NEAREST для категориальных данных. По умолчанию используется CUBIC. Рекомендации по сжатию, обзору и макету можно найти в статье Рекомендации по подготовке внешних COG-файлов.

GDAL 3.11+ CLI

gdal raster convert in.tif out.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co OVERVIEWS=IGNORE_EXISTING \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

Классический интерфейс командной строки

Пропустите INTERLEAVE=BAND в версиях GDAL до 3.11.

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

Создание манифеста

Независимо от того, регистрируете ли вы COG с помощью клиентской библиотеки Earth Engine Python, инструмента командной строки earthengine или Earth Engine REST API, вам необходимо определить манифест загрузки изображения, указав место назначения объекта, URI Cloud Storage и дополнительные метаданные полосы. В API и инструменте командной строки объекты, поддерживаемые COG, называются внешними изображениями (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal).

Пример. Один COG-файл, содержащий все каналы Если COG-файл содержит все каналы (например, RGB), в манифесте требуется только один набор фрагментов:

{
  "name": "projects/my-project/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

Пример. Несколько COG-файлов (по одному на диапазон) Если у вас есть отдельные файлы для разных диапазонов (например, красного, зеленого и синего):

{
  "name": "projects/my-project/assets/my_multi_band_cog",
  "tilesets": [
    {
      "id": "red_tileset",
      "sources": [ { "uris": [ "gs://google-sample-bucket/band_red.tif" ] } ]
    },
    {
      "id": "green_tileset",
      "sources": [ { "uris": [ "gs://google-sample-bucket/band_green.tif" ] } ]
    }
  ],
  "bands": [
    { "id": "R", "tilesetId": "red_tileset", "tilesetBandIndex": 0 },
    { "id": "G", "tilesetId": "green_tileset", "tilesetBandIndex": 0 }
  ]
}

Ограничения манифеста

Для манифестов объектов, поддерживаемых COG, действуют ограничения, которые не применяются к стандартным манифестам загрузки:

  • Один сегмент. Все URI в манифесте должны находиться в одном сегменте Cloud Storage.
  • Один URI на источник. Каждый элемент ImageSource должен содержать ровно один URI. Вы не можете объединить несколько файлов в один источник набора фрагментов. Чтобы создать мозаику из нескольких сцен COG, зарегистрируйте каждый COG как объект и объедините их в ee.ImageCollection с помощью .mosaic().
  • Нет mask_bands. Поле верхнего уровня mask_bands не поддерживается. Используйте missingData в манифесте или убедитесь, что в TIFF-файле есть внутреннее значение nodata.
  • Не указывайте data_type в наборе фрагментов. Не указывайте data_type в разделе tilesets. Это значение определяется автоматически.
  • Не указывайте dimensions в исходном коде. Не указывайте dimensions в ImageSource.
  • Нет subdataset_prefix/subdataset_suffix.
  • Нетmin_tile_area_ratio или skip_metadata_read.

Отправьте запрос на регистрацию

Вы можете отправить манифест в Earth Engine с помощью клиентской библиотеки Earth Engine Python, инструмента командной строки earthengine или Earth Engine REST API. Выберите способ, который лучше всего подходит для вашего рабочего процесса.

Клиентская библиотека Python

В скрипте Python или блокноте Jupyter используйте клиентскую библиотеку Earth Engine для Python (ee.data) после инициализации проекта:

import ee

# 1. Authenticate and initialize
ee.Authenticate()
ee.Initialize(project='your-project-id')

# 2. Define the manifest as a Python dictionary
manifest = {
  "name": "projects/your-project-id/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

# 3. Register the asset
result = ee.data.startExternalImageIngestion(manifest)
print(f"Asset registered: {result['name']}")

Инструмент командной строки

В терминале сохраните манифест в файле с именем manifest.json и выполните команду загрузки earthengine:

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Register the asset
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

REST API

Для автоматизированных рабочих процессов без клиентской библиотеки отправьте авторизованный запрос POST напрямую в конечную точку REST API Earth Engine projects.image.importExternal (в примере ниже используется Python):

import json
from pprint import pprint
import ee
from google.auth.transport.requests import AuthorizedSession

# 1. Authenticate and start an authorized HTTP session
ee.Authenticate()
ee_project = 'your-project-id'
session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

# 2. Define the REST request body wrapping the manifest
request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/my_cog_asset',
    'tilesets': [
      {
        'id': 'default_tileset',
        'sources': [
          {
            'uris': [
              'gs://google-sample-bucket/my_optimized_image.tif'
            ]
          }
        ]
      }
    ]
  }
}

# 3. Send the POST request
url = (
    'https://earthengine.googleapis.com/v1alpha/'
    f'projects/{ee_project}/image:importExternal'
)
response = session.post(url=url, data=json.dumps(request))
pprint(json.loads(response.content))

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

Настроить права доступа

В отличие от стандартных объектов Earth Engine, данные пикселей COG остаются в Cloud Storage. Если вы хотите поделиться объектом, созданным на основе COG, вам нужно предоставить пользователям доступ на чтение как к объекту Earth Engine, так и к файлам Cloud Storage.

Как предоставить разрешения для сегмента Cloud Storage

У соавторов должны быть разрешения на чтение файлов из Cloud Storage.

Требуемые разрешения:

  • storage.buckets.get (для получения метаданных и местоположения сегмента)
  • storage.objects.get (для чтения данных пикселя)

Вы можете предоставить эти разрешения, используя следующие стандартные роли Cloud Storage:

  • Storage Bucket Viewer (предоставляет разрешение storage.buckets.get на чтение метаданных и местоположения сегмента)
  • Наблюдатель объектов в хранилище (предоставляет разрешение storage.objects.get на чтение данных пикселя)

Как настроить проект в консоли Google Cloud

  1. Откройте браузер Cloud Storage.
  2. Нажмите на название сегмента.
  3. Перейдите на вкладку Права доступа.
  4. Нажмите Предоставить доступ.
  5. Добавьте адреса электронной почты соавторов (или группы Google, или allUsers для общего доступа).
  6. Назначьте роли Storage Bucket Viewer и Storage Object Viewer.
  7. Нажмите Сохранить.

Как предоставить доступ к объекту Earth Engine

Поделитесь самим объектом с помощью Менеджера объектов Earth Engine или CLI. Подробную информацию вы найдете в руководстве по управлению объектами.

Как обновлять, заменять и удалять объекты, поддерживаемые COG

Объект на основе COG – это указатель на определенную версию файла в Cloud Storage, а также метаданные (след, проекция, полосы и обзорный макет), которые Earth Engine проиндексировал при регистрации. Earth Engine закрепляет версию файла, чтобы эти метаданные не рассинхронизировались с пикселями. Именно поэтому обновление объектов на основе COG отличается от обновления стандартных объектов.

Генерирование объектов

При регистрации COG Earth Engine записывает поколение объекта Cloud Storage (номер его версии) вместе с URI. Закрепленное поколение можно увидеть в метаданных объекта. Оно выглядит как суффикс #<generation> в URI:

Python

asset = ee.data.getAsset('projects/your-project-id/assets/my_cog_asset')
print(asset['tilesets'][0]['sources'][0]['uris'])
# ['gs://google-sample-bucket/my_optimized_image.tif#1750427474244728']

Вы также можете закрепить определенную версию самостоятельно, добавив суффикс #<generation> в URI манифеста при регистрации (или повторной регистрации) объекта. В противном случае Earth Engine считывает текущий объект и закрепляет любое найденное поколение. Явное закрепление полезно для отката к более ранней версии, которая была сохранена в сегменте с управлением версиями объектов.

Если вы перезапишете файл в Cloud Storage, он получит новое поколение, а если удалите – закрепленное поколение исчезнет. В любом случае прочитать пиксели объекта не удастся, если только в сегменте не включено управление версиями объектов, которое сохраняет старое поколение. В этом случае Earth Engine продолжит читать старые пиксели. Операции с метаданными, в которых используется индексированная запись (например, ee.data.getAsset(), bandNames() и фильтрация коллекций), продолжат работать в любом случае.

Как обновить объект после изменения его файла

Чтобы связать существующий объект с новой версией файла, зарегистрируйте его повторно с тем же названием и включенной функцией перезаписи. Earth Engine повторно считывает заголовок GeoTIFF, повторно индексирует метаданные и закрепляет новое поколение в одном синхронном вызове. Существующие разрешения объекта сохраняются, но его свойства, диапазон дат и названия каналов берутся из нового манифеста, поэтому включите все, что вы ранее задали с помощью ee.data.updateAsset().

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Командная строка: earthengine upload external_image --force --manifest manifest.json
  • REST API. Включите "overwrite": true в качестве поля верхнего уровня вместе с "imageManifest" в тело запроса projects.image.importExternal.

Удалять объект перед этим не нужно, так как это приведет к нежелательным последствиям: отдельный объект потеряет разрешения, а изображение из подборки на некоторое время исчезнет из нее. Обратите внимание, что ee.data.updateAsset() (projects.assets.patch) может изменять только свойства, диапазон дат и названия каналов, но не файл, на который указывает объект.

Независимые жизненные циклы

Объекты Earth Engine и Cloud Storage управляются отдельно:

  • При удалении объекта Earth Engine (earthengine rm или ee.data.deleteAsset()) удаляется только запись об объекте. Файлы в Cloud Storage не будут затронуты.
  • Удаление файла в Cloud Storage не приводит к удалению объекта. Он по-прежнему будет показываться в списках и в своей коллекции (см. Поколения объектов).

Работа с большими коллекциями

В Earth Engine API нет пакетного или рекурсивного удаления: каждый объект необходимо удалять по отдельности, а коллекция должна быть пустой, прежде чем ее можно будет удалить. earthengine rm -r делает это за вас, но удаляет изображения по одному, поэтому удаление коллекции с десятками тысяч изображений может занять несколько часов.

  • Чтобы заменить изображения в коллекции, перезапишите их, а не удаляйте. Повторно зарегистрируйте каждый образ по имени, включив перезапись (см. выше). В этом случае для каждого изображения требуется один запрос вместо двух, коллекция остается заполненной, и не нужно удалять и заново создавать саму коллекцию, в которой хранятся разрешения. Удалите только те изображения, которых нет в новом наборе.
  • Чтобы удалить много объектов, распараллельте процесс с помощью скрипта. Получите список объектов с помощью ee.data.listAssets() (используя представление BASIC, которое возвращает только названия и типы, а не полные метаданные для каждого изображения) и удалите их из небольшого пула потоков. Запросы объектов используют ограничения частоты запросов на уровне проекта, поэтому поддерживайте умеренную параллельность (около 10 рабочих процессов) и позвольте встроенным повторным попыткам клиентской библиотеки обрабатывать любые ответы 429 Too Many Requests:

    Python

    import concurrent.futures
    import ee
    
    ee.Initialize(project='your-project-id')
    collection = 'projects/your-project-id/assets/my_collection'
    
    listing = ee.data.listAssets({'parent': collection, 'view': 'BASIC'})
    asset_ids = [a['name'] for a in listing['assets']]
    
    def delete(asset_id):
      try:
        ee.data.deleteAsset(asset_id)
      except ee.EEException as e:
        return f'{asset_id}: {e}'
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
      failures = [f for f in executor.map(delete, asset_ids) if f]
    
    if failures:
      print('\n'.join(failures))
    else:
      ee.data.deleteAsset(collection)
    

    Коллекция удаляется, только если удалены все изображения. Если удаление не удалось, коллекция остается на месте для повторного запуска.

    Тот же шаблон применяется для регистрации нескольких изображений: замените ee.data.deleteAsset(asset_id) в помощнике на ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) и сопоставьте его со списком манифестов. Передача allow_overwrite=True даже при первом запуске позволяет безопасно перезапустить пакет после частичного сбоя, поскольку любой уже созданный объект заменяется, а не вызывает ошибку.

Использовать зарегистрированные объекты

После регистрации доступ к объекту на основе COG в скриптах Earth Engine осуществляется так же, как и к любому стандартному объекту изображения:

JavaScript

var image = ee.Image('projects/your-project-id/assets/my_cog_asset');

Python

image = ee.Image('projects/your-project-id/assets/my_cog_asset')

Ответы на часто задаваемые вопросы о разрешениях, обновлении файлов и управлении большими коллекциями можно найти в разделе часто задаваемых вопросов о COG.