Ferramenta de linha de comando

A ferramenta earthengine é um programa de utilitário que permite gerenciar recursos e tarefas do Earth Engine na linha de comando. Ela é instalada automaticamente quando você instala a API Python. Para verificar se a ferramenta está instalada e funcionando corretamente, digite o seguinte em uma linha de comando:

    earthengine

Se a ferramenta estiver instalada corretamente, ela vai imprimir um breve resumo dos comandos disponíveis. Para receber ajuda com um comando específico, use:

    earthengine command -h

Ao instalar a API Python pela primeira vez, é necessário fazer login usando o comando authenticate descrito abaixo. As seções a seguir descrevem os comandos disponíveis com mais detalhes.

Credenciais da conta de serviço

Para usar a CLI com as credenciais de uma conta de serviço, use a flag service_account_file para apontar para um arquivo JSON que contenha a chave da conta de serviço.

    earthengine --service_account_file=service_account_creds.json

Uso no Colab

A ferramenta de linha de comando do Earth Engine já vem pré-instalada e pronta para uso em Google Colab.

Autenticação

Faça a autenticação para cada nova sessão do Colab ou se a máquina virtual expirar devido à inatividade (as credenciais não são salvas entre as sessões).

Importe a biblioteca de cliente Python e chame ee.Authenticate() para acionar o fluxo de autenticação. Siga as instruções para concluir a autenticação. O padrão auth_mode no Colab é colab. Consulte o guia de autenticação para outras opções.

import ee
ee.Authenticate()

Execução de comandos

Para executar utilitários de linha de comando, como a CLI do Earth Engine, é necessário adicionar um ponto de exclamação antes das chamadas de comando.

!earthengine -h

Definir um projeto na nuvem

Use a opção --project para definir um projeto na nuvem para cada comando earthengine individual.

!earthengine --project my-project <command>

Como alternativa, defina um projeto padrão a ser usado por todas as earthengine chamadas usando o set_project comando. O projeto será adicionado a um arquivo de credenciais (~/.config/earthengine/credentials) e usado para comandos subsequentes, a menos que seja substituído pela --project opção. Defina um projeto padrão para cada nova sessão do Colab ou se a máquina virtual expirar devido à inatividade (as credenciais não são salvas entre as sessões).

!earthengine set_project my-project

Referência de comandos

autenticar

Autentica a ferramenta de linha de comando e a biblioteca de cliente Python no Earth Engine. Exemplo:

    earthengine authenticate

O Earth Engine usa o protocolo OAuth 2.0 para autenticar clientes. O comando earthengine authenticate vai orientar você no processo de autenticação usando seu navegador da Web.

Será necessário instalar o gcloud se você estiver usando o modo de autenticação padrão do gcloud. Consulte outros modos de autenticação disponíveis no parâmetro auth_mode no guia de autenticação.

acl

Imprime ou atualiza a lista de controle de acesso (ACL) de um recurso do Earth Engine. A lista de controle de acesso (ACL, na sigla em inglês) controla quem pode ler ou gravar em um recurso. Exemplos:

    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

O subcomando get imprime uma descrição JSON da ACL. O subcomando set define uma ACL fornecida em um arquivo com o mesmo formato JSON. É possível copiar uma ACL de um recurso para outros salvando a saída de get e fornecendo-a para set.

O subcomando set também aceita dois nomes de ACL especiais:

• private: remove as permissões de todos, exceto do proprietário.
• public: concede permissão de leitura a todos os usuários.

O subcomando ch permite fazer mudanças individuais em uma ACL. Para conceder permissão de leitura , especifique -u [e-mail]:R. Para conceder permissão de gravação, especifique -u [e-mail]:W. Para remover as permissões de um usuário, especifique -d [e-mail]. O identificador de usuário especial AllUsers pode ser usado para conceder ou revogar a permissão de leitura de todos os usuários. A revogação das permissões AllUsers não revoga outras permissões que você também possa ter concedido a usuários individuais.

recurso

Imprime ou atualiza os metadados associados a um recurso do Earth Engine. Exemplos:

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

O subcomando info imprime informações detalhadas sobre o recurso, incluindo os metadados dele, no formato JSON. O subcomando set define propriedades de metadados individuais em um recurso.

Os valores das propriedades de metadados definidas podem ser números ou strings. Ao definir nomes de propriedades usando a flag --property ou -p, separe o nome e o valor da propriedade com um sinal de igual. O tipo de dados é detectado automaticamente, ou você pode especificá-lo explicitamente prefixando o nome da propriedade com (string), (number) ou (date). Por exemplo, isso define uma propriedade com valor de string com o valor "42":

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

As aspas neste exemplo impedem que o shell interprete os parênteses. Elas podem ou não ser necessárias, dependendo do shell e da plataforma.

Para excluir uma propriedade, defina-a como null sem um tipo:

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

As propriedades de data são apenas números que representam um número de milissegundos desde a época Unix (ou seja meia-noite de 1º de janeiro de 1970) e podem ser especificadas diretamente como um número ou em um dos seguintes formatos:

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

O fuso horário é considerado UTC. É possível definir as propriedades especiais de hora de início e término usando as flags --time_start e --time_end:

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

cp

Copia um recurso. Exemplo:

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

create

Cria novas pastas e coleções de imagens. Exemplo:

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

Use o subcomando folder para criar pastas e o collection para criar coleções de imagens. É possível especificar a opção -p para criar pastas pai de forma recursiva, conforme necessário. As pastas e imagens recém-criadas têm ACLs particulares por padrão.

ls

Lista o conteúdo de uma ou mais pastas ou coleções. Exemplo:

    earthengine ls users/username

A opção -l solicita um formato longo com mais informações sobre cada recurso (atualmente apenas o tipo dele). É possível especificar --max_items number (ou -m para abreviar) para limitar o número de itens de cada pasta ou coleção listada:

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

A execução do comando ls sem argumentos vai listar as pastas de nível superior que você possui.

modelo

Ferramenta para manipular modelos salvos do TensorFlow.

model prepare

Prepare um modelo salvo para exibição no Earth Engine. Especificamente, isso transforma seu SavedModel em um formato adequado para processar solicitações do Earth Engine. (Saiba mais sobre SavedModel.)

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

Saiba mais sobre os modelos do AI Platform aqui. Confira um exemplo completo aqui .

mv

Move ou renomeia um recurso. Exemplo:

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

project_config

Prévia :a definição da configuração do projeto é um recurso de prévia. Portanto, as invocações precisam incluir a palavra-chave alpha.

Define valores de configuração do projeto. Antes de usar esse comando, defina um projeto usando set_project.

get

Para visualizar uma configuração de projeto, use o subcomando get:

    earthengine alpha project_config get

Se você tiver permissão para visualizar as configurações de tarefas em lote do projeto, a saída vai conter:

• maxConcurrentExports: um número que indica o número máximo de tarefas em lote que podem ser executadas em paralelo para todos os usuários do projeto. Por padrão, esse valor é definido como o máximo permitido pelo plano de assinatura da conta de faturamento associada.

Além disso, se você tiver permissão para visualizar a configuração do plano, a saída vai conter:

• planMaxConcurrentExports, um número que indica o número máximo de tarefas em lote que podem ser executadas em paralelo em todos os usuários e projetos que usam a conta de faturamento.

set

Para atualizar a configuração do projeto, use o subcomando set. As seguintes configurações podem ser definidas:

• max_concurrent_exports, para controlar o paralelismo máximo de tarefas em lote
  do projeto
  • requer as permissões corretas

Por exemplo, para configurar um projeto de modo que ele permita apenas 10 tarefas em execução em paralelo para o projeto:

    earthengine alpha project_config set --max_concurrent_exports=10

A saída mostra a configuração atualizada do projeto, idêntica ao que get retorna.

Para mais informações sobre o paralelismo de tarefas em lote, consulte a página de cotas do Earth Engine.

rm

Exclui um ou mais recursos. Exemplo:

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

É possível usar a flag -r para excluir o conteúdo de uma pasta ou coleção de forma recursiva. Para segurança ao excluir vários recursos, use a flag --dry_run para verificar exatamente o que será excluído sem excluir nada.

set_project

Define o projeto na nuvem do Google Cloud pelo qual as solicitações de computação são encaminhadas.

    earthengine set_project foo-project

Esse comando é necessário antes de executar comandos que exigem a funcionalidade do Cloud, por exemplo, model.

tarefa

Imprime informações sobre tarefas de longa duração ou as gerencia. Exemplos:

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

O subcomando list lista informações básicas sobre as tarefas enviadas recentemente. A opção -l solicita um formato longo com mais informações sobre cada tarefa. O subcomando info imprime informações detalhadas sobre tarefas individuais. O subcomando cancel cancela uma ou mais tarefas em execução.

upload

Faz upload de imagens ou tabelas do Google Cloud Storage para o Earth Engine ou cria recursos com suporte de imagens externas.

imagem

Para fazer upload de um recurso de imagem usando as configurações padrão:

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

Se você especificar vários arquivos de imagem de entrada, eles serão interpretados como blocos de um único recurso de imagem. Saiba mais sobre as opções de upload de imagens para o Earth Engine em Fazer upload de recursos de imagem: opções avançadas.

É possível especificar a política de redução de pirâmide usando a flag --pyramiding_policy, que pode ser definida como mean (o padrão), sample, mode, min ou max. Isso vai controlar como o Earth Engine gera a pirâmide de versões de resolução mais baixa da imagem:

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

É possível usar --last_band_alpha para indicar que a máscara da imagem precisa ser extraída de um canal alfa na última banda:

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

É possível especificar um valor de dados ausentes usando a flag --nodata_value. Isso vai mascarar todos os pixels na imagem com esse valor:

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

Também é possível especificar propriedades de metadados a serem definidas no recurso usando as mesmas flags aceitas pelo asset set comando descrito acima. As opções também são descritas no guia de manifesto de imagem.

tabela

Para fazer upload de um Shapefile, CSV ou TFRecord do Google Cloud Storage para um recurso de tabela do Earth Engine, é possível usar qualquer um destes:

    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

Observação: ao fazer upload de Shapefiles, é necessário especificar apenas o caminho para o arquivo .shp. Os arquivos .dbf, .shx e .prj relacionados precisam estar no mesmo local. Como alternativa, é possível especificar um arquivo .zip que contenha os arquivos necessários.

Há muitas opções relacionadas à maneira como os arquivos CSV e TFRecord são interpretados. É possível conferir uma lista completa de opções de upload de tabelas acessando o guia de manifesto de tabelas ou com:

    earthengine upload table -h

external_image

Para criar um recurso com suporte de uma imagem externa, execute o comando upload_image com um manifesto:

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

Confira um exemplo de manifesto:

{
  "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"
}

Consulte o guia do Cloud GeoTIFF e o guia de manifesto de imagem para mais detalhes sobre como criar o manifesto.