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 mostrar 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, você precisa fazer 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 contém 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 está pré-instalada e pronta para uso no Google Colab.
Autenticação
Faça a autenticaçã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).
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 ver 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.
!earthengine --project my-project <command>
Como alternativa, defina um projeto padrão a ser usado por todas as chamadas earthengine
com 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
!earthengine set_project my-project
Referência de comandos
autenticar
Autentica a ferramenta de linha de comando e a biblioteca de cliente do 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.
Será necessário instalar a gcloud se
você usar o modo de autenticação padrão da 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 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 username@gmail.com: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. É 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 username@gmail.com:R. Para conceder permissão de gravação, especifique -u username@gmail.com:W. Para remover as permissões de um usuário, especifique -d
username@gmail.com. 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 de AllUsers
não revoga as permissões adicionais que você também pode ter
concedido a usuários individuais.
recurso
Mostra 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
earthengine asset setbands projects/my-project/assets/asset_id band1 band2
O subcomando info mostra informações detalhadas sobre o recurso, incluindo
os metadados, em 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 propriedade usando a sinalização --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 criar propriedades especiais para visualizações de bandas de classificação, é possível
armazenar 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 é considerado UTC. É possível definir as propriedades especiais de horário 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 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 privadas 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). É possível especificar --max_items number (ou -m, para
abreviar) para limitar o número de itens de cada pasta ou coleção que você lista:
earthengine ls -m 10 projects/my-project/assets/my_large_collection
A execução do comando ls sem argumentos lista as pastas de nível superior que
você possui.
modelo
Ferramenta para manipular modelos salvos do TensorFlow.
model prepare
Prepare um modelo salvo para disponibilização no Earth Engine. Especificamente, isso transforma
seu SavedModel em um formato adequado para processar solicitações do Earth
Engine. (Saiba mais sobre o
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 da plataforma de IA 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
Define os valores de configuração do projeto. Antes de usar esse comando, defina um
projeto usando set_project.
get
Para ver 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 em todos os usuários do projeto em questão. Por padrão, ele é 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 para permitir que apenas 10 tarefas sejam executadas em paralelo:
earthengine alpha project_config set --max_concurrent_exports=10
A saída exibe 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
Use a sinalização -r para excluir o conteúdo de uma pasta ou coleção
recursivamente. Para garantir a 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 na nuvem do Google Cloud pelo qual as solicitações de recursos computacionais são roteadas.
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 que você
enviou 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 base em 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 para fazer upload de imagens para o Earth Engine em Como fazer upload de recursos de imagem: opções avançadas.
É possível especificar a política de redução de pirâmide usando a sinalização --pyramiding_policy, que pode ser definida como mean (padrão), sample, mode, min ou max. Isso vai controlar como o Earth Engine gera a pirâmide de
versões de menor resolução da 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
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 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
Também é possível 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 uma das seguintes 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
Há muitas opções relacionadas à maneira como os arquivos CSV e TFRecord são interpretados. Para ver uma lista completa de opções de upload de tabelas, acesse o guia Manifesto de tabela ou use:
earthengine upload table -h
external_image
Para registrar um GeoTIFF otimizado para nuvem (COG, na sigla em inglês) no Cloud Storage como um recurso compatível com COG (chamado de imagem externa na API), execute o comando upload external_image com um manifesto:
earthengine upload external_image --manifest /tmp/foo.json
Adicione --force para substituir um recurso, por exemplo, para apontá-lo para uma nova
versão do arquivo (consulte
Como atualizar recursos com suporte do COG).
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 de registro do COG e o guia de manifesto de imagem para mais detalhes sobre como criar o manifesto.