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

Инструмент earthengine – это утилита, которая позволяет управлять объектами и задачами Earth Engine из командной строки. Она устанавливается автоматически вместе с Python API. Чтобы проверить, установлен ли инструмент и правильно ли он работает, введите в командной строке следующее:

    earthengine

Если инструмент установлен правильно, он выведет краткую сводку доступных команд. Чтобы получить справку по определенной команде, используйте:

    earthengine command -h

При первой установке Python API вам нужно войти в систему с помощью команды authenticate, описанной ниже. Ниже приведены подробные сведения о доступных командах.

Учетные данные сервисного аккаунта

Чтобы использовать CLI с учетными данными сервисного аккаунта, укажите флаг service_account_file, указывающий на JSON-файл с ключом сервисного аккаунта.

    earthengine --service_account_file=service_account_creds.json

Использование в Colab

Инструмент командной строки Earth Engine предустановлен и готов к использованию в Google Colab.

Аутентификация

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

Импортируйте клиентскую библиотеку Python и вызовите ee.Authenticate(), чтобы запустить процесс аутентификации. Следуйте инструкциям на экране. По умолчанию в Colab используется auth_mode colab. Другие варианты описаны в руководстве по аутентификации.

import ee
ee.Authenticate()

Выполнение команд

Чтобы запустить утилиты командной строки, например Earth Engine CLI, перед вызовом команды нужно поставить восклицательный знак.

!earthengine -h

Как настроить облачный проект

Используйте параметр --project, чтобы задать облачный проект для каждой отдельной команды earthengine.

!earthengine --project my-project <command>

Также можно задать проект по умолчанию, который будет использоваться для всех вызовов earthengine, с помощью команды set_project. Проект будет добавлен в файл учетных данных (~/.config/earthengine/credentials) и использован для последующих команд, если не будет переопределен параметром --project. Задайте проект по умолчанию для каждого нового сеанса Colab или на случай, если виртуальная машина перестанет работать из-за бездействия (учетные данные не сохраняются между сеансами).

!earthengine set_project my-project

Справочник по командам

выполнить аутентификацию

Выполняет аутентификацию инструмента командной строки и клиентской библиотеки Python в Earth Engine. Пример:

    earthengine authenticate

Для аутентификации клиентов Earth Engine использует протокол OAuth 2.0. Команда earthengine authenticate проведет вас через процесс аутентификации с помощью веб-браузера.

Если вы используете режим аутентификации gcloud по умолчанию, вам потребуется установить gcloud. Другие режимы аутентификации, доступные через параметр auth_mode, описаны в руководстве по аутентификации.

acl

Выводит или обновляет список контроля доступа (ACL) объекта Earth Engine. Список контроля доступа определяет, кто может читать или записывать данные в объект. Примеры:

    earthengine acl get projects/my-project/assets/asset_id
    earthengine acl set public projects/my-project/assets/asset_id
    earthengine acl ch -u [e-mail]:R projects/my-project/assets/asset_id

Субкоманда get выводит описание ACL в формате JSON. Субкоманда set задает ACL, указанный в файле с тем же форматом JSON. Вы можете скопировать ACL из одного объекта в другие, сохранив выходные данные из get и передав их в set.

Субкоманда set также принимает два специальных названия ACL:

• private – удаляет разрешения для всех, кроме владельца.
• public: предоставляет разрешение на чтение всем пользователям.

Субкоманда ch позволяет вносить отдельные изменения в ACL. Чтобы предоставить разрешение на чтение, укажите -u [e-mail]:R, на запись – -u [e-mail]:W, а чтобы удалить разрешения пользователя – -d [e-mail]. Специальный идентификатор пользователя AllUsers можно использовать, чтобы предоставить или отозвать разрешение на чтение для всех пользователей. Обратите внимание, что отзыв разрешений AllUsers не отменяет дополнительные разрешения, которые вы могли предоставить отдельным пользователям.

объект

Выводит или обновляет метаданные, связанные с объектом Earth Engine. Примеры:

    earthengine asset info projects/my-project/assets/asset_id
    earthengine asset set -p name=value projects/my-project/assets/asset_id
    earthengine asset setbands projects/my-project/assets/asset_id band1 band2

Субкоманда info выводит подробную информацию об объекте, включая его метаданные, в формате JSON. Субкоманда set задает отдельные свойства метаданных для объекта. Субкоманда setbands обновляет названия каналов объекта.

Значения свойств метаданных, которые вы задаете, могут быть числами или строками. При указании названий свойств с помощью флага --property или -p разделяйте название и значение свойства знаком равенства. Тип данных определяется автоматически, но вы можете указать его явно, добавив перед названием свойства префикс (string), (number) или (date). Например, в следующем примере задается строковое свойство со значением "42":

    earthengine asset set -p '(string)name=42' projects/my-project/assets/asset_id

Кавычки в этом примере не позволяют оболочке интерпретировать скобки. В зависимости от оболочки и платформы они могут быть необязательными.

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

    earthengine asset set -p 'landcover_class_palette=ff0000,00ff00,0000ff' projects/my-project/assets/asset_id
    earthengine asset set -p 'landcover_class_values=1,2,3' projects/my-project/assets/asset_id

Чтобы удалить свойство, задайте для него значение null без указания типа:

    earthengine asset set -p name=null projects/my-project/assets/asset_id

Свойства даты – это просто числа, которые представляют собой количество миллисекунд, прошедших с начала эпохи Unix (т. е. с полуночи 1 января 1970 года). Их можно указывать непосредственно в виде числа или в одном из следующих форматов:

    YYYY-MM-DD
    YYYY-MM-DDThh:mm:ss
    YYYY-MM-DDThh:mm:ss.f

Часовой пояс – UTC. Вы можете задать время начала и окончания с помощью флагов --time_start и --time_end:

    earthengine asset set --time_start 1978-10-15T12:34:56 projects/my-project/assets/asset_id

cp

Копирует объект. Пример:

    earthengine cp projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

create

Создание новых папок и коллекций изображений. Пример:

    earthengine create folder projects/my-project/assets/folder_id
    earthengine create collection projects/my-project/assets/collection_id

Используйте субкоманду folder, чтобы создать папки, и collection, чтобы создать коллекции изображений. Вы можете указать параметр -p, чтобы рекурсивно создавать родительские папки по мере необходимости. По умолчанию для новых папок и изображений задаются списки управления доступом с ограниченным доступом.

ls

Показывает содержимое одной или нескольких папок или коллекций. Пример:

    earthengine ls users/username

Параметр -l запрашивает длинный формат с дополнительной информацией о каждом объекте (в настоящее время только о его типе). Чтобы ограничить количество элементов в каждой папке или коллекции, можно указать параметр --max_items number (или -m):

    earthengine ls -m 10 projects/my-project/assets/my_large_collection

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

модель

Инструмент для работы с сохраненными моделями TensorFlow.

model prepare

Подготовьте сохраненную модель для использования в Earth Engine. В частности, это преобразует ваш SavedModel в форму, подходящую для обработки запросов от Earth Engine. Подробнее о SavedModel…

    earthengine model prepare my_source_dir my_dest_dir '{"Conv2D:0":"my_input_band"}' '{"Sigmoid:0":"my_output_band"}'

Подробнее о моделях ИИ-платформы… Полный пример приведен здесь.

mv

Перемещает или переименовывает объект. Пример:

    earthengine mv projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

project_config

Предварительная версия. Настройка конфигурации проекта – это предварительная версия функции, поэтому вызовы должны включать ключевое слово alpha.

Задает значения конфигурации проекта. Прежде чем использовать эту команду, задайте проект с помощью set_project.

get

Чтобы посмотреть конфигурацию проекта, используйте субкоманду get:

    earthengine alpha project_config get

Если у вас есть разрешение на просмотр настроек пакетных задач проекта, выходные данные будут содержать:

• maxConcurrentExports – число, указывающее максимальное количество пакетных задач, которые могут выполняться параллельно для всех пользователей в рамках данного проекта. По умолчанию это значение равно максимальному количеству, разрешенному тарифным планом связанного платежного аккаунта.

Кроме того, если у вас есть разрешение на просмотр конфигурации плана, выходные данные будут содержать:

• planMaxConcurrentExports – число, указывающее максимальное количество пакетных задач, которые могут выполняться параллельно для всех пользователей и проектов, использующих платежный аккаунт.

set

Чтобы обновить конфигурацию проекта, используйте субкоманду set. Можно задать следующие настройки:

• max_concurrent_exports, чтобы контролировать максимальный параллелизм пакетных задач проекта.
  • требуются соответствующие разрешения

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

    earthengine alpha project_config set --max_concurrent_exports=10

В выходных данных будет показана обновленная конфигурация проекта, идентичная той, которую возвращает get.

Дополнительную информацию о параллельном выполнении пакетных задач можно найти на странице Квоты Earth Engine.

rm

Удаляет один или несколько объектов. Пример:

    earthengine rm projects/my-project/assets/asset_id
    earthengine rm -r projects/my-project/assets/folder_id

Чтобы удалить содержимое папки или коллекции, используйте флаг -r. Чтобы случайно не удалить нужные объекты, используйте флаг --dry_run. Он позволяет проверить, что именно будет удалено, не выполняя удаление.

set_project

Задает проект Google Cloud, через который маршрутизируются запросы на вычисления.

    earthengine set_project foo-project

Эту команду нужно выполнить перед запуском команд, требующих функций Cloud, например model.

задача

Выводит информацию о длительных задачах или управляет ими. Примеры:

    earthengine task list
    earthengine task list -l
    earthengine task info TASK_ID
    earthengine task cancel TASK_ID

Субкоманда list позволяет получить основные сведения о недавно отправленных задачах. Параметр -l запрашивает длинный формат с дополнительной информацией о каждой задаче. Субкоманда info выводит подробную информацию об отдельных задачах. Субкоманда cancel отменяет одну или несколько выполняющихся задач.

загрузка

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

Изображение

Чтобы загрузить объект изображения с настройками по умолчанию, выполните следующие действия:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id gs://bucket/image.tif

Если вы укажете несколько входных графических файлов, они будут интерпретироваться как фрагменты одного объекта изображения. Подробнее о том, как загружать изображения в Earth Engine, читайте в статье Загрузка объектов изображений: дополнительные настройки.

Вы можете указать правила уменьшения пирамиды с помощью флага --pyramiding_policy, который может принимать одно из следующих значений: mean (по умолчанию), sample, mode, min или max. Это определяет, как Earth Engine генерирует пирамиду версий вашего изображения с более низким разрешением:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --pyramiding_policy=sample gs://bucket/image.tif

Вы можете использовать --last_band_alpha, чтобы указать, что маска для изображения должна быть взята из альфа-канала в последней полосе:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --last_band_alpha gs://bucket/image.tif

Вы можете указать значение, которое будет использоваться при отсутствии данных, с помощью флага --nodata_value. Это замаскирует все пиксели на изображении с этим значением:

    earthengine upload image --asset_id=users/myuser/asset --nodata_value=255 gs://bucket/image.tif

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

стол

Чтобы загрузить файл Shapefile, CSV или TFRecord из Google Cloud Storage в объект таблицы Earth Engine, можно использовать любой из следующих способов:

    earthengine upload table --asset_id=projects/my-project/assets/myUploadedShapefile gs://bucket/foo.shp
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedCSV gs://bucket/foo.csv
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedTFRecord gs://bucket/foo.tfrecord

Примечание. При загрузке шейп-файлов нужно указать только путь к файлу .shp. Связанные файлы .dbf, .shx и .prj должны находиться в том же месте. Вы также можете указать файл .zip, содержащий нужные файлы.

Существует множество вариантов интерпретации файлов CSV и TFRecord. Полный список параметров загрузки таблиц можно найти в руководстве Манифест таблицы или с помощью следующей команды:

    earthengine upload table -h

external_image

Чтобы зарегистрировать Cloud Optimized GeoTIFF (COG) в Cloud Storage как объект на основе COG (в API он называется внешним изображением), выполните команду upload external_image с манифестом:

earthengine upload external_image --manifest /tmp/foo.json

Добавьте --force, чтобы перезаписать существующий объект, например указать на новую версию его файла (см. Обновление объектов, поддерживаемых COG).

Пример манифеста:

{
  "name": "projects/{project}/assets/cogdemo1",
  "tilesets": [
    { "id": "0", "sources": [{ "uris": ["gs://ee-docs-demos/COG_demo.tif"] }] }
  ],
  "properties": {
    "source": "https://code.earthengine.google.com/d541cf8b268b2f9d8f834c255698201d"
  },
  "startTime": "2016-01-01T00:00:00.000000000Z",
  "endTime": "2016-12-31T15:01:23.000000000Z"
}

Подробную информацию о создании манифеста можно найти в руководстве по регистрации COG и руководстве по манифесту изображений.