Загрузка манифеста изображений

Если вам нужно больше возможностей для загрузки изображений в Google Earth Engine (EE), чем предоставляют интерфейс редактора кода или команда upload инструмента командной строки earthengine, вы можете описать загрузку изображения с помощью JSON-файла, известного как манифест, и использовать команду upload image --manifest инструмента командной строки.

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

Единоразовая настройка

  1. Загрузка манифеста работает только с файлами, размещенными в Google Cloud Storage. Чтобы начать работу с Google Cloud Storage, создайте проект Google Cloud, если у вас его ещё нет. Обратите внимание, что при настройке необходимо указать кредитную карту для оплаты. Сам сервис EE пока не взимает плату, но за перенос файлов в Google Cloud Storage перед их загрузкой в EE придется немного заплатить. Для типичных объемов загружаемых данных (десятки или сотни гигабайт) стоимость будет довольно низкой.
  2. В проекте включите Cloud Storage API и создайте сегмент.
  3. Установите клиент Earth Engine Python. В него входит инструмент командной строки earthengine, который мы будем использовать для загрузки данных.
  4. Для автоматической загрузки можно использовать сервисный аккаунт Google Cloud, связанный с вашим проектом. Для тестирования сервисный аккаунт не нужен, но мы рекомендуем вам ознакомиться с тем, как его использовать.

Очень большие исходные файлы (100 ГБ и более) могут загружаться быстрее, если они разбиты на несколько фрагментов.

Идентификаторы и названия объектов.

Для объектов, принадлежащих облачному проекту, используйте следующее соглашение о наименовании: projects/some-project-id/assets/some-asset-id.

Названия объектов в устаревших проектах и объектов, принадлежащих пользователям

Для старых проектов название объекта в манифесте должно немного отличаться от идентификатора объекта, который виден в других местах Earth Engine. Чтобы загрузить объекты, идентификаторы которых начинаются с users/some_user или projects/some_project, в манифесте перед идентификатором нужно добавить строку projects/earthengine-legacy/assets/. Например, объект EE с идентификатором users/username/my_geotiff должен быть загружен с названием projects/earthengine-legacy/assets/users/username/my_geotiff.

Да, это означает, что идентификаторы, такие как projects/some_projects/some_asset, преобразуются в названия, в которых projects упоминается дважды: projects/earthengine-legacy/assets/projects/some_projects/some_asset. Это может запутать, но необходимо для соответствия стандартам Google Cloud API.

Используйте манифесты

Ниже приведен пример простого манифеста. Он загружает файл с названием small.tif из сегмента Google Cloud Storage с названием gs://earthengine-test.

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://earthengine-test/small.tif"
          ]
        }
      ]
    }
  ]
}

Чтобы использовать его, сохраните его в файле с именем manifest.json и запустите:

earthengine upload image --manifest /path/to/manifest.json

(Файл gs://earthengine-test/small.tif существует и доступен для чтения. Вы можете использовать его для тестирования.)

Наборы фрагментов

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

  • Мозаика. Иногда несколько файлов представляют несколько фрагментов (например, каждый фрагмент представляет собой квадрат размером 1x1 градус). Такие файлы необходимо объединить в один диапазон в объекте Earth Engine.
  • Отдельные ремешки. Иногда несколько файлов представляют несколько каналов. Такие файлы должны быть объединены в виде каналов в объекте EE.

(В редких случаях может потребоваться использовать оба способа одновременно.)

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

Для мозаичной загрузки манифест будет выглядеть следующим образом:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/N30W22.tif"
          ]
        },
        {
          "uris": [
            "gs://bucket/N31W22.tif"
          ]
        }
      ]
    }
  ]
}

Для отдельных диапазонов манифест будет выглядеть следующим образом (вам также потребуется добавить раздел bands, как описано ниже):

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "bands": ...,
  "tilesets": [
    {
      "id": "tileset_for_band1",
      "sources": [
        {
          "uris": [
            "gs://bucket/band1.tif"
          ]
        }
      ]
    },
    {
      "id": "tileset_for_band2",
      "sources": [
        {
          "uris": [
            "gs://bucket/band2.tif"
          ]
        }
      ]
    }
  ]
}

Обратите внимание, что в случае отдельных диапазонов мы должны присвоить каждому набору фрагментов отдельный идентификатор набора фрагментов во избежание неясности. Идентификатор набора фрагментов может быть произвольной строкой. Эти строки не сохраняются в загруженном объекте. Идентификаторы наборов фрагментов используются только при загрузке, чтобы отличать наборы фрагментов друг от друга.

Диапазоны частот

Второй важный концепт – сопоставление исходных файлов с полосами объектов EE. Для этого используется раздел bands манифеста.

Раздел bands можно опустить. В этом случае полосы сначала создаются из файлов в первом наборе фрагментов, затем из следующего набора и т. д. По умолчанию диапазоны называются b1, b2 и т. д. Чтобы переопределить названия диапазонов по умолчанию, добавьте в конце раздел bands, например:

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/rgb.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "R",
      "tilesetBandIndex": 0
    },
    {
      "id": "G",
      "tilesetBandIndex": 1
    },
    {
      "id": "B",
      "tilesetBandIndex": 2
    }
  ]
}

Количество каналов EE должно совпадать с общим количеством каналов во всех наборах фрагментов.

Если вы не хотите загружать все каналы из файла, используйте поле tilesetBandIndex, чтобы указать, какие каналы GDAL нужно загрузить. Первый диапазон имеет tilesetBandIndex, равный 0.

Пример:

Предположим, что в исходном файле четыре полосы: "tmin", "tmin_error", "tmax", "tmax_error". Нам нужны только tmin и tmax. Вот как должны выглядеть соответствующие разделы манифеста:

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "id": "temperature",
      "sources": [
        {
          "uris": [
            "gs://bucket/temperature.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "tmin",
      "tilesetBandIndex": 0,
      "tilesetId": "temperature"
    },
    {
      "id": "tmax",
      "tilesetBandIndex": 2,
      "tilesetId": "temperature"
    }
  ]
}

Маскировать диапазоны

Маскирование полосы контролируется компонентом maskBands манифеста. Поддерживаются три возможных конфигурации маски (но полоса маски всегда считается последней полосой в определенном файле).

  1. Маска для всех диапазонов данных в одном файле.
  2. Маска для всех диапазонов данных, поступающих из всех других файлов.
  3. Маска для некоторых полос данных.

1. Самый распространенный случай – один файл GeoTIFF, последняя полоса которого используется в качестве маски для других полос. Это работает только для GeoTIFF типа Byte. Используйте следующий манифест:

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "id": "data_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/data_file.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "data_band",
      "tilesetId": "data_tileset"
    },
    {
      "id": "qa_band",
      "tilesetId": "data_tileset"
    }
  ],
  "maskBands": [
    {
      "tilesetId": "data_tileset"
    }
  ]
}

2. Чтобы использовать маску GeoTIFF для всех каналов в другом файле GeoTIFF, используйте следующий манифест:

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "id": "data_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/data_file.tif"
          ]
        }
      ]
    },
    {
      "id": "mask_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/mask_file.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "data_band",
      "tilesetId": "data_tileset"
    },
    {
      "id": "qa_band",
      "tilesetId": "data_tileset"
    }
  ],
  "maskBands": [
    {
      "tilesetId": "mask_tileset"
    }
  ]
}

3. Чтобы использовать GeoTIFF в качестве маски для определенного диапазона в другом файле, используйте следующий манифест (разница с предыдущим случаем заключается в том, что поле bandIds в maskBands задано):

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "id": "data_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/data_file.tif"
          ]
        }
      ]
    },
    {
      "id": "mask_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/mask_file.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "data_band",
      "tilesetId": "data_tileset"
    },
    {
      "id": "qa_band",
      "tilesetId": "data_tileset"
    }
  ],
  "maskBands": [
    {
      "tilesetId": "mask_tileset",
      "bandIds": ["data_band"]
    }
  ]
}

В последнем примере мы работаем с двумя диапазонами из набора фрагментов data_tileset, но применяем маску только к одному из них (data_band), как указано в поле bandIds единственного предоставленного объекта списка maskBands.

Обратите внимание, что в качестве маски используется только последний диапазон набора фрагментов, указанный в maskBands.

Правила в отношении пирамид

Когда Earth Engine создает пирамиды изображений во время загрузки, он должен многократно уменьшать сетки размером 2 x 2 пикселя до одного пикселя, определенным образом преобразуя значение пикселя. По умолчанию значения пикселей усредняются, что в большинстве случаев является правильным, когда растровый диапазон представляет более или менее непрерывные данные. Однако в двух случаях использование значения по умолчанию приведет к неверным результатам. В этих случаях необходимо задать поле pyramidingPolicy в определении полосы (если оно не задано, по умолчанию предполагается значение MEAN).

Для классификации растровых изображений (например, для классификации земного покрова) наиболее логичным способом пирамидирования пикселей является использование большинства из четырех значений для получения следующего. Это делается с помощью правила пирамидального агрегирования MODE:

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/landcover.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "landcover",
      "pyramidingPolicy": "MODE"
    }
  ]
}

Для растровых каналов, в которых ни MEAN, ни MODE не имеют смысла (например, пиксели с битовой упаковкой), следует использовать политику пирамидирования SAMPLE. SAMPLE всегда принимает значение верхнего левого пикселя из каждой сетки 2 x 2. В следующем примере показано, как назначить правило MEAN для полосы, представляющей непрерывную переменную (NDVI), и правило SAMPLE для полосы QA.

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/ndvi.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "NDVI",
      "tilesetBandIndex": 0,
      "pyramidingPolicy": "MEAN"
    },
    {
      "id": "QA",
      "tilesetBandIndex": 1,
      "pyramidingPolicy": "SAMPLE"
    }
  ]
}

Время начала и окончания

Для всех объектов необходимо указывать время начала и окончания, чтобы данные были более понятными, особенно если объекты включены в коллекции. Эти поля не являются обязательными, но мы настоятельно рекомендуем использовать их по возможности.

Время начала и окончания обычно означает время наблюдения, а не время создания исходного файла.

Для простоты время окончания считается исключающей границей. Например, для объектов, которые должны показываться ровно один день, укажите в качестве времени начала и окончания полночь двух последовательных дней (например, 1980-01-31T00:00:00 и 1980-02-01T00:00:00). Если у объекта нет продолжительности, укажите то же время окончания, что и время начала. Время в манифестах должно быть представлено в виде строк ISO 8601. Чтобы упростить значения дат, рекомендуем считать, что время окончания не включается в период (например, полночь следующего дня для ежедневных объектов).

Пример:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/img_20190612.tif"
          ]
        }
      ]
    }
  ],
  "startTime": "1980-01-31T00:00:00Z",
  "endTime": "1980-02-01T00:00:00Z"
}

Структура манифеста

Ниже приведена структура JSON со всеми возможными полями манифеста для загрузки изображений. Определения полей приведены в разделе Определения полей манифеста.

{
  "name": <string>,
  "tilesets": [
    {
      "dataType": <string>,
      "id": <string>,
      "crs": <string>,
      "sources": [
        {
          "uris": [
            <stringn>>
          ],
          "affineTransform": {
            "scaleX": <double>,
            "shearX": <double>,
            "translateX": <double>,
            "shearY": <double>,
            "scaleY": <double>,
            "translateY": <double>
          }
        }
      ]
    }
  ],
  "bands": [
    {
      "id": <string>,
      "tilesetId": <string>,
      "tilesetBandIndex": <int32>,
      "missingData": {
        "values": [<doublen>>]
      },
      "pyramindingPolicy": <string>
    }
  ],
  "maskBands": [
    {
      "tilesetId": <string>,
      "bandIds": [
        <stringn>>
      ]
    }
  ],
  "footprint": {
    "points": [
      {
        "x": <double>,
        "y": <doublen>>
      }
    ],
    "bandId": <string>
  },
  "missingData": {
     "values": [<double>]
  },
  "pyramidingPolicy": <string>,
  "uriPrefix": <string>,
  "startTime": {
    "seconds": <integer>
  },
  "endTime": {
    "seconds": <integer>
  },
  "properties": {
    <unspecified>
  }
}

Определения полей манифеста

name

string

Название создаваемого объекта. name имеет формат "projects/*/assets/**" (например, "projects/earthengine-legacy/assets/users/USER/ASSET").

наборы фрагментов

list

Список словарей, определяющих свойства наборов тайлов. Дополнительную информацию можно найти в описании полей элемента словаря tilesets ниже.

tilesets[i].dataType

string

Указывает числовой тип данных. По умолчанию используется тип, который сообщает GDAL. В этом случае указывать тип не нужно.

Тип данных Значение
Не указано "DATA_TYPE_UNSPECIFIED"
8-битное целое число со знаком "INT8"
8-битное целое число без знака "UINT8"
16-битное целое число со знаком "INT16"
16-битное целое число без знака "UINT16"
32-битное целое число со знаком "INT32"
32-битное целое число без знака "UINT32"
32-битный с плавающей запятой "FLOAT32"
64-битное число с плавающей запятой "FLOAT64"

tilesets[i].id

string

Идентификатор набора фрагментов. Должен быть уникальным среди наборов фрагментов, указанных в манифесте объекта. Этот идентификатор удаляется на этапе обработки и используется только для связывания набора фрагментов с диапазоном. Пустая строка является допустимым идентификатором.

tilesets[i].crs

string

Система координат сетки пикселей, указанная в виде стандартного кода, если это возможно (например, кода EPSG), или в формате WKT.

tilesets[i].sources

list

Список словарей, определяющих свойства графического файла и его сопутствующих файлов. Дополнительную информацию можно найти в описании полей элемента словаря sources ниже.

tilesets[i].sources[j].uris

list

Список URI данных, которые нужно добавить. Поддерживаются только URI Google Cloud Storage. Каждый URI должен быть указан в следующем формате: gs://bucket-id/object-id. Основной объект должен быть первым элементом списка, а дополнительные – следующими. Каждый URI начинается с префикса ImageManifest.uriPrefix, если он задан.

tilesets[i].sources[j].affineTransform

dictionary

Необязательное аффинное преобразование. Указывается, только если данных из uris (включая сопутствующие файлы) недостаточно для размещения пикселей. Предоставляется в виде словаря со следующими ключами: scaleX, shearX, translateX, shearY, scaleY, translateY. Дополнительную информацию можно найти в этом справочном материале.

Примеры ключей и значений:

{
  "scaleX": 0.1,
  "shearX": 0.0,
  "translateX": -180.0,
  "shearY": 0.0,
  "scaleY": -0.1,
  "translateY": 90.0
}

диапазоны

list

Список словарей, определяющих свойства одной полосы, полученной из набора фрагментов. Обратите внимание, что порядок каналов объекта совпадает с порядком bands. Дополнительную информацию можно найти в следующих полях элемента словаря bands.

bands[i].id

string

Идентификатор (название) диапазона.

bands[i].tilesetId

string

Идентификатор набора фрагментов, соответствующего диапазону.

bands[i].tilesetBandIndex

int32

Индекс диапазона, начинающийся с нуля, из набора фрагментов, соответствующего диапазону.

bands[i].missingData.values

list

Список значений (тип double), которые представляют отсутствие данных в полосе.

bands[i].pyramidingPolicy

string

Правила в отношении пирамид. Подробнее… Варианты:

  • "MEAN" (по умолчанию)
  • "MODE"
  • "ОБРАЗЕЦ"

maskBands

list

Список словарей, определяющих свойства одной полосы маски, полученной из набора тайлов. Можно указать не более одной полосы маски. Дополнительную информацию можно найти в следующих полях элемента словаря maskBands.

maskBands[i].tilesetId

string

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

maskBands[i].bandIds

list of strings

Список идентификаторов полос, к которым применяется полоса маски. Если оставить поле пустым, маска будет применена ко всем каналам объекта. Каждой полосе может соответствовать только одна полоса маски.

след ноги

dictionary

Словарь, определяющий свойства следа всех допустимых пикселей на изображении. Если значение не указано, по умолчанию используется все изображение. Дополнительную информацию можно найти в описании полей элемента словаря footprint ниже.

footprint.points

list

Список точек, определяющих контур всех действительных пикселей на изображении. Точка определяется словарем с ключами x и y, имеющими значения с плавающей запятой. Список точек описывает кольцо, которое образует внешнюю границу простого многоугольника, содержащего центры всех действительных пикселей изображения. Это должно быть линейное кольцо: последняя точка должна совпадать с первой. Координаты указываются в проекции полосы, заданной параметром bandId.

Примечание. Используйте нецелые координаты, например центр каждого пикселя, поскольку footprint включает пиксель, если он (прямоугольник 1 x 1) пересекает контур. Чтобы случайно не выбрать соседние пиксели, не используйте целочисленные координаты, поскольку они являются границами между пикселями. Если нарисовать контур по центрам пикселей, это предотвратит включение нежелательных пикселей, которые могут вызвать ошибки, когда нужные пиксели примыкают к границе карты, например к антимеридиану или полюсу.

Например, для изображения 2 x 2 со всеми четырьмя допустимыми пикселями возможным кольцом является следующее:

[
  {
    "x": 0.5,
    "y": 0.5
  },
  {
    "x": 0.5,
    "y": 1.5
  },
  {
    "x": 1.5,
    "y": 1.5
  },
  {
    "x": 1.5,
    "y": 0.5
  },
  {
    "x": 0.5,
    "y": 0.5
  }
]

footprint.bandId

string

Идентификатор полосы, CRS которой определяет координаты следа. Если значение не указано, используется первая полоса.

missingData.values

list

Список значений (тип double), которые представляют отсутствие данных во всех диапазонах изображения. Применяется ко всем диапазонам, для которых не задано собственное значение missingData.

pyramidingPolicy

string

Правила в отношении пирамид. Если правило не указано, по умолчанию применяется MEAN. Применяется ко всем диапазонам, для которых не заданы собственные значения. Подробнее… Варианты:

  • "MEAN" (по умолчанию)
  • "MODE"
  • "ОБРАЗЕЦ"

uriPrefix

string

Необязательный префикс, который добавляется ко всем uris, определенным в манифесте.

startTime

integer

Временная метка, связанная с объектом (если есть). Обычно это время, когда был сделан спутниковый снимок. Для объектов, соответствующих интервалу времени, например средних значений за месяц или год, эта временная метка соответствует началу этого интервала. Указывается в секундах и (необязательно) наносекундах с начала эпохи (1 января 1970 г.). Подразумевается часовой пояс UTC.

endTime

integer

Для объектов, соответствующих интервалу времени, например средних значений за месяц или год, эта временная метка соответствует концу этого интервала (не включительно). Указывается в секундах и (необязательно) наносекундах с начала эпохи (1 января 1970 г.). Подразумевается часовой пояс UTC.

объекты

dictionary

Простой словарь пар "ключ-значение". Ключи должны быть строками, а значения – числами или строками. Значения списков пока не поддерживаются для объектов, загруженных пользователями.

Ограничения

Размер манифеста JSON

Размер файла манифеста JSON не должен превышать 10 МБ. Если вам нужно загрузить много файлов, подумайте, как можно сократить количество символов, необходимых для описания набора данных. Например, используйте поле uriPrefix, чтобы не указывать путь к сегменту Google Cloud для каждого URI в списке uris. Если размер архива все равно слишком велик, попробуйте сократить названия файлов.

Формат графического файла

Каждый графический файл должен быть в формате TIFF. Если система координат не указана в манифесте, то файл должен быть в формате GeoTIFF со встроенной системой координат.

Файлы TIFF можно сжимать с помощью DEFLATE, JPEG-XL/JXL, LERC, LERC_DEFLATE, LERC_ZSTD, LZMA, LZW, WEBP или ZSTD.

Рекомендации по загрузке больших файлов:

  • Лучший выбор. ZSTD обеспечивает хороший баланс скорости и сжатия.
  • Не рекомендуется: LZMA может работать очень медленно, несмотря на хорошее сжатие.
  • Несжатые файлы. Размер файлов будет больше, а загрузка займет больше времени.
  • Сжатие с потерями (например, JPEG). Может изменить значения пикселей. Используйте сжатие без потерь (например, DEFLATE, LZMA, LZW, ZSTD), если вы понимаете, как это может повлиять на ваши данные.