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
- Откройте браузер Cloud Storage.
- Нажмите на название сегмента.
- Перейдите на вкладку Права доступа.
- Нажмите Предоставить доступ.
- Добавьте адреса электронной почты соавторов (или группы Google, или
allUsersдля общего доступа). - Назначьте роли Storage Bucket Viewer и Storage Object Viewer.
- Нажмите Сохранить.
Как предоставить доступ к объекту 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.