Регистрация объектов GeoTIFF, оптимизированных для облака (COG)

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

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

Требования и настройка Cloud Storage

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

1. Местоположение сегмента (строгое требование)

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

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

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

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

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

Шаг 1. Подготовьте COG-файлы

Файлы TIFF должны быть оптимизированы для облака. Файл TIFF должен:

  • Разбито на фрагменты со следующими размерами: 256 x 256, 512 x 512, 1024 x 1024 или 2048 x 2048. Для оптимальной производительности рекомендуем использовать изображения размером 512 x 512 или больше.
  • Расположены так, что все каталоги графических файлов (IFD) находятся в начале.
  • Включите обзоры, созданные с помощью Power of 2.
  • Используйте чередование BAND.

Для преобразования изображений можно использовать GDAL.

С помощью драйвера GDAL COG (рекомендуется GDAL 3.1 или более поздней версии):

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Использование стандартного драйвера GTiff

Сначала создайте внутренние обзорные изображения со степенью двойки (с помощью gdal raster overview add или gdaladdo), а затем скопируйте изображение и обзорные изображения в макет COG с разбивкой на фрагменты:

gdaladdo -r nearest in.tif 2 4 8 16 32  # or -r cubic for continuous/float data

gdal_translate in.tif out.tif \
  -co BIGTIFF=YES \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=16 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Шаг 2. Создайте манифест

Независимо от того, регистрируете ли вы COG с помощью клиентской библиотеки Earth Engine Python, инструмента командной строки earthengine или Earth Engine REST API, вам необходимо определить манифест загрузки изображения, указав место назначения объекта, URI Google Cloud Storage и дополнительные метаданные полосы.

Пример. Один 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 }
  ]
}

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

Вы можете отправить манифест в 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. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
print(f"Asset registered: {result['name']}")

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

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

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Submit the external image upload task
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

REST API (Python)

Для автоматизированных рабочих процессов без клиентской библиотеки отправьте авторизованный запрос 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 данные пикселей не копируются, эта операция обычно занимает несколько секунд.

Ограничения для манифеста объектов COG

При создании манифеста для объектов на основе COG обратите внимание на следующие строгие ограничения (которые отличаются от стандартных манифестов загрузки):

  • Один сегмент. Все URI в манифесте должны находиться в одном сегменте GCS.
  • Один 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.

Шаг 4. Настройте разрешения (важно для предоставления доступа)

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

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

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

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

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

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

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

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

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

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

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

Управление генерацией объектов

При регистрации COG Earth Engine сохраняет определенное поколение (версию) объекта GCS. Если вы обновите файл в GCS, его поколение изменится.

  • По умолчанию Earth Engine не сможет загрузить объект и вернет ошибку: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
  • Это позволяет избежать рассинхронизации метаданных (например, проекции или контура) с пикселями.

  • Рекомендация. Если вам нужно обновить данные изображения, зарегистрируйте его как новый объект или повторно выполните команду загрузки с флагом --force, а не перезаписывайте файлы:

    earthengine --project your-project-id upload external_image --force --manifest manifest.json

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

После регистрации доступ к объекту, поддерживаемому 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')