Загрузка манифеста таблицы

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

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

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

Идентификаторы и имена активов

Для ресурсов в облачных проектах используйте projects/my_cloud_project/assets/my_asset .

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

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

Использование манифестов

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

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

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

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

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

Для загрузки шейп-файла укажите только файл .shp; остальные файлы будут обнаружены автоматически.

Несколько источников

Можно указать несколько источников CSV или шейп-файлов, по одному файлу на источник. В этом случае каждый файл CSV должен иметь одинаковую структуру. Например, у нас есть два файла CSV: region1.csv и region2.csv :

идентификатор форма
1 {"type":"Точка","координаты":[-119,36]}
2 {"type":"Точка","координаты":[-118,37]}
3 {"type":"Точка","координаты":[-117,38]}
идентификатор форма
4 {"type":"Точка","координаты":[-112,40]}
5 {"type":"Точка","координаты":[-111,41]}
6 {"type":"Точка","координаты":[-110,42]}

Они имеют одинаковую структуру, но разное содержание. Они были загружены в корзину облачного хранилища: gs://earthengine-test/region1.csv и gs://earthengine-test/region2.csv . Чтобы принять их как ресурс Earth Engine, создайте манифест с двумя записями в списке sources , например:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://earthengine-test/region1.csv"
      ]
    },
    {
      "uris": [
        "gs://earthengine-test/region2.csv"
      ]
    }
  ]
}

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

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

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

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

Пример:

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

Справочник по структуре манифеста

Следующая структура JSON включает все возможные поля манифеста загрузки таблицы. Определения полей можно найти в следующем разделе «Определения полей манифеста».

{
  "name": <string>,
  "sources": [
    {
      "uris": [
        <string>
      ],
      "charset": <string>,
      "maxErrorMeters": <double>,
      "maxVertices": <int32>,
      "crs": <string>,
      "geodesic": <boolean>,
      "primaryGeometryColumn": <string>,
      "xColumn": <string>,
      "yColumn": <string>,
      "dateFormat": <string>,
      "csvDelimiter": <string>,
      "csvQualifier": <string>,
    }
  ],
  "uriPrefix": <string>,
  "startTime": {
    "seconds": <integer>
  },
  "endTime": {
    "seconds": <integer>
  },
  "properties": {
    <unspecified>
  }
}

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

имя

string

Имя создаваемого актива. name имеет формат «projects/*/assets/**» (например, projects/earthengine-legacy/assets/users/USER/ASSET ).

источники

list

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

источники[i].uris

list

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

источники[i].charset

string

Имя набора символов по умолчанию, используемого для декодирования строк. Если пусто, по умолчанию предполагается кодировка «UTF-8».

источники[i].maxErrorMeters

double

Максимально допустимая ошибка в метрах при преобразовании геометрии между системами координат. Если пусто, максимальная ошибка по умолчанию составляет 1 метр.

источники[i].maxVertices

int32

Максимальное количество вершин. Если не ноль, геометрия будет разделена на пространственно непересекающиеся части, каждая из которых находится в пределах этого предела.

источники[i].crs

string

Код CRS по умолчанию или строка WKT, определяющая систему координат любой геометрии, для которой она не указана. Если оставить пустым, по умолчанию будет EPSG:4326 . Только для источников CSV/TFRecord.

источники[i].геодезические

boolean

Стратегия по умолчанию для интерпретации ребер в геометрии, для которых не указано иное. Если false, края в проекции прямые. Если это правда, края изогнуты, чтобы следовать кратчайшему пути на поверхности Земли. Если это поле пусто, по умолчанию используется значение false, если CRS является системой координат проекции. Только для источников CSV/TFRecord.

источники[i].primaryGeometryColumn

string

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

Если оставить пустым и существует более одного столбца геометрии, используется первый встреченный столбец геометрии. Только для источников CSV/TFRecord.

источники[i].xColumn

string

Имя столбца числовых координат X для определения геометрии точки. Если также указан yColumn и оба столбца содержат числовые значения, то столбец геометрии точки будет построен со значениями x,y в системе координат, заданной в CRS. Если оставить пустым и CRS не указывает систему координат проекции, по умолчанию используется «долгота». Если оставить пустым и CRS указывает систему координат проекции, по умолчанию используется пустая строка и точечная геометрия не создается.

Сгенерированный столбец геометрии точки будет называться {xColumn}_{yColumn}_N , куда добавляется N, так что {xColumn}_{yColumn}_N является уникальным, если столбец с именем {xColumn}_{yColumn} уже существует. Только для источников CSV/TFRecord.

источники[i].yColumn

string

Имя столбца числовых координат Y для определения геометрии точки. Если также указан xColumn и оба столбца содержат числовые значения, то столбец геометрии точки будет построен со значениями x,y в системе координат, заданной в CRS. Если оставить пустым и CRS не указывает систему координат проекции, по умолчанию используется «широта». Если оставить пустым и CRS указывает систему координат проекции, по умолчанию используется пустая строка и точечная геометрия не создается.

Сгенерированный столбец геометрии точки будет называться {xColumn}_{yColumn}_N , куда добавляется N, так что {xColumn}_{yColumn}_N является уникальным, если столбец с именем {xColumn}_{yColumn} уже существует. Только для источников CSV/TFRecord.

источники[i].dateFormat

string

Формат для анализа полей, кодирующих даты. Шаблон формата должен соответствовать описанию в документации класса DateTimeFormat Joda-Time . Если оставить пустым, даты будут импортированы в виде строк. Только для источников CSV/TFRecord.

источники[i].csvDelimiter

string

При загрузке файлов CSV в качестве разделителя между значениями столбцов в строке используется один символ. Если оставить пустым, по умолчанию используется ',' . Только для источников CSV.

источники[i].csvQualifier

string

При загрузке файлов CSV — символ, окружающий значения столбца (также известный как «символ кавычки»). Если оставить пустым, по умолчанию будет " . Только для источников CSV.

Если значение столбца не окружено квалификаторами, начальные и конечные пробелы обрезаются. Например:

    ..., test,...            <== this value is not qualified
becomes the string value:
    "test"                   <== leading whitespace is stripped
 пока:
    ...," test",...          <== this value IS qualified with quotes
becomes the string value:
    " test"                  <== leading whitespace remains!

uriPrefix

string

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

время начала

integer

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

время окончания

integer

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

характеристики

dictionary

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

столбецDataTypeOverrides

dictionary

Если автоматическое определение типа работает неправильно, используйте это поле с именами столбцов в качестве ключей и одной из следующих констант в качестве значений: COLUMN_DATA_TYPE_STRING, COLUMN_DATA_TYPE_NUMERIC, COLUMN_DATA_TYPE_LONG.

Ограничения

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

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

,

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

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

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

Идентификаторы и имена активов

Для ресурсов в облачных проектах используйте projects/my_cloud_project/assets/my_asset .

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

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

Использование манифестов

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

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

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

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

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

Для загрузки шейп-файла укажите только файл .shp; остальные файлы будут обнаружены автоматически.

Несколько источников

Можно указать несколько источников CSV или шейп-файлов, по одному файлу на источник. В этом случае каждый файл CSV должен иметь одинаковую структуру. Например, у нас есть два файла CSV: region1.csv и region2.csv :

идентификатор форма
1 {"type":"Точка","координаты":[-119,36]}
2 {"type":"Точка","координаты":[-118,37]}
3 {"type":"Точка","координаты":[-117,38]}
идентификатор форма
4 {"type":"Точка","координаты":[-112,40]}
5 {"type":"Точка","координаты":[-111,41]}
6 {"type":"Точка","координаты":[-110,42]}

Они имеют одинаковую структуру, но разное содержание. Они были загружены в корзину облачного хранилища: gs://earthengine-test/region1.csv и gs://earthengine-test/region2.csv . Чтобы принять их как ресурс Earth Engine, создайте манифест с двумя записями в списке sources , например:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://earthengine-test/region1.csv"
      ]
    },
    {
      "uris": [
        "gs://earthengine-test/region2.csv"
      ]
    }
  ]
}

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

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

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

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

Пример:

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

Справочник по структуре манифеста

Следующая структура JSON включает все возможные поля манифеста загрузки таблицы. Определения полей можно найти в следующем разделе «Определения полей манифеста».

{
  "name": <string>,
  "sources": [
    {
      "uris": [
        <string>
      ],
      "charset": <string>,
      "maxErrorMeters": <double>,
      "maxVertices": <int32>,
      "crs": <string>,
      "geodesic": <boolean>,
      "primaryGeometryColumn": <string>,
      "xColumn": <string>,
      "yColumn": <string>,
      "dateFormat": <string>,
      "csvDelimiter": <string>,
      "csvQualifier": <string>,
    }
  ],
  "uriPrefix": <string>,
  "startTime": {
    "seconds": <integer>
  },
  "endTime": {
    "seconds": <integer>
  },
  "properties": {
    <unspecified>
  }
}

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

имя

string

Имя создаваемого актива. name имеет формат «projects/*/assets/**» (например, projects/earthengine-legacy/assets/users/USER/ASSET ).

источники

list

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

источники[i].uris

list

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

источники[i].charset

string

Имя набора символов по умолчанию, используемого для декодирования строк. Если пусто, по умолчанию предполагается кодировка «UTF-8».

источники[i].maxErrorMeters

double

Максимально допустимая ошибка в метрах при преобразовании геометрии между системами координат. Если пусто, максимальная ошибка по умолчанию составляет 1 метр.

источники[i].maxVertices

int32

Максимальное количество вершин. Если не ноль, геометрия будет разделена на пространственно непересекающиеся части, каждая из которых находится в пределах этого предела.

источники[i].crs

string

Код CRS по умолчанию или строка WKT, определяющая систему координат любой геометрии, для которой она не указана. Если оставить пустым, по умолчанию будет EPSG:4326 . Только для источников CSV/TFRecord.

источники[i].геодезические

boolean

Стратегия по умолчанию для интерпретации ребер в геометрии, для которых не указано иное. Если false, края в проекции прямые. Если это правда, края изогнуты, чтобы следовать кратчайшему пути на поверхности Земли. Если это поле пусто, по умолчанию используется значение false, если CRS является системой координат проекции. Только для источников CSV/TFRecord.

источники[i].primaryGeometryColumn

string

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

Если оставить пустым и существует более одного столбца геометрии, используется первый встреченный столбец геометрии. Только для источников CSV/TFRecord.

источники[i].xColumn

string

Имя столбца числовых координат X для определения геометрии точки. Если также указан yColumn и оба столбца содержат числовые значения, то столбец геометрии точки будет построен со значениями x,y в системе координат, заданной в CRS. Если оставить пустым и CRS не указывает систему координат проекции, по умолчанию используется «долгота». Если оставить пустым и CRS указывает систему координат проекции, по умолчанию используется пустая строка и точечная геометрия не создается.

Сгенерированный столбец геометрии точки будет называться {xColumn}_{yColumn}_N , куда добавляется N, так что {xColumn}_{yColumn}_N является уникальным, если столбец с именем {xColumn}_{yColumn} уже существует. Только для источников CSV/TFRecord.

источники[i].yColumn

string

Имя столбца числовых координат Y для определения геометрии точки. Если также указан xColumn и оба столбца содержат числовые значения, то столбец геометрии точки будет построен со значениями x,y в системе координат, заданной в CRS. Если оставить пустым и CRS не указывает систему координат проекции, по умолчанию используется «широта». Если оставить пустым и CRS указывает систему координат проекции, по умолчанию используется пустая строка и точечная геометрия не создается.

Сгенерированный столбец геометрии точки будет называться {xColumn}_{yColumn}_N , куда добавляется N, так что {xColumn}_{yColumn}_N является уникальным, если столбец с именем {xColumn}_{yColumn} уже существует. Только для источников CSV/TFRecord.

источники[i].dateFormat

string

Формат для анализа полей, кодирующих даты. Шаблон формата должен соответствовать описанию в документации класса DateTimeFormat Joda-Time . Если оставить пустым, даты будут импортированы в виде строк. Только для источников CSV/TFRecord.

источники[i].csvDelimiter

string

При загрузке файлов CSV в качестве разделителя между значениями столбцов в строке используется один символ. Если оставить пустым, по умолчанию используется ',' . Только для источников CSV.

источники[i].csvQualifier

string

При загрузке файлов CSV — символ, окружающий значения столбца (также известный как «символ кавычки»). Если оставить пустым, по умолчанию будет " . Только для источников CSV.

Если значение столбца не окружено квалификаторами, начальные и конечные пробелы обрезаются. Например:

    ..., test,...            <== this value is not qualified
becomes the string value:
    "test"                   <== leading whitespace is stripped
 пока:
    ...," test",...          <== this value IS qualified with quotes
becomes the string value:
    " test"                  <== leading whitespace remains!

uriPrefix

string

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

время начала

integer

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

время окончания

integer

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

характеристики

dictionary

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

столбецDataTypeOverrides

dictionary

Если автоматическое определение типа работает неправильно, используйте это поле с именами столбцов в качестве ключей и одной из следующих констант в качестве значений: COLUMN_DATA_TYPE_STRING, COLUMN_DATA_TYPE_NUMERIC, COLUMN_DATA_TYPE_LONG.

Ограничения

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

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