Ferramenta de linha de comando

A ferramenta earthengine é um programa utilitário que permite gerenciar recursos e tarefas do Earth Engine na linha de comando. Ele é instalado 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 sobre um comando específico, use:

    earthengine command -h

Ao instalar a API Python pela primeira vez, faça login usando o comando authenticate descrito abaixo. As seções a seguir descrevem os comandos disponíveis em 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 vem pré-instalada e pronta para uso no Google Colab.

Autenticação

Autentique-se para cada nova sessão do Colab ou se a máquina virtual expirar por inatividade (as credenciais não são salvas entre as sessões).

Importe a biblioteca de cliente do Python e chame ee.Authenticate() para acionar o fluxo de autenticação. Siga as instruções para concluir a autenticação. O auth_mode padrão 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 do Cloud

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

!earthengine --project my-project <command>

Como alternativa, defina um projeto padrão para ser usado por todas as chamadas earthengine usando o comando set_project. O projeto será adicionado a um arquivo de credenciais (~/.config/earthengine/credentials) e usado para comandos subsequentes, a menos que seja substituído pela opção --project. Defina um projeto padrão para cada nova sessão do Colab ou se a máquina virtual expirar por 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ê pelo processo de autenticação usando seu navegador da Web.

É necessário instalar o gcloud se estiver usando o modo de autenticação padrão do gcloud. Consulte outros modos de autenticação disponíveis pelo 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 ACL controla quem pode ler ou gravar 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 mostra uma descrição JSON da ACL. O subcomando set define uma ACL fornecida em um arquivo com o mesmo formato JSON. Você pode 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 especiais de ACL:

• 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 permissão de leitura de todos os usuários. Revogar as permissões de AllUsers não revoga outras permissões que você possa ter concedido a usuários individuais.

recurso

Imprime ou atualiza 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
    earthengine asset setbands projects/my-project/assets/asset_id band1 band2

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

Os valores das propriedades de metadados que você define 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 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. Eles podem ou não ser necessários, dependendo do shell e da plataforma.

Para criar propriedades especiais para visualizações de intervalos de classificação, armazene as listas de valores e cores como strings separadas por vírgulas. Por exemplo, para definir os valores de paleta e classe de uma banda chamada 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

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 é 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. Você pode especificar a opção -p para criar recursivamente pastas principais conforme necessário. Por padrão, as pastas e imagens recém-criadas têm ACLs privadas.

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). Você pode 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

Executar o comando ls sem argumentos lista as pastas de nível superior que são de sua propriedade.

modelo

Ferramenta para manipular modelos salvos do TensorFlow.

model prepare

Prepare um modelo salvo para veiculaçã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 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 conferir a configuração de um projeto, use o subcomando get:

    earthengine alpha project_config get

Se você tiver permissão para ver 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 em todos os usuários do projeto especificado. 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 ver 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. É possível configurar as seguintes opções:

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

Por exemplo, para configurar um projeto de forma que apenas 10 tarefas possam ser executadas em paralelo:

    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 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

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

set_project

Define o projeto 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 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 um dos seguintes valores: mean (padrão), sample, mode, min ou max. Isso controla como o Earth Engine gera a pirâmide de versões de resolução mais baixa da sua imagem:

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

Use --last_band_alpha para indicar que a máscara da imagem deve 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 "sem dados" 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

Você também pode especificar propriedades de metadados para definir no recurso usando as mesmas flags aceitas pelo comando asset set descrito acima. As opções também são descritas no guia 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, use qualquer uma destas opções:

    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, você só precisa especificar o caminho para o arquivo .shp. Os arquivos relacionados .dbf, .shx e .prj precisam estar no mesmo local. Como alternativa, é possível especificar um arquivo .zip que contenha os arquivos necessários.

Há muitas opções relacionadas à forma como os arquivos CSV e TFRecord são interpretados. Para conferir uma lista completa de opções de upload de tabela, acesse o guia de manifesto de tabela ou use:

    earthengine upload table -h

external_image

Para criar um recurso apoiado por uma imagem externa, execute o comando upload_image com um manifesto:

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

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 do manifesto de imagem para mais detalhes sobre como construir o manifesto.