Instalação do Python: instalação do Conda

A API Python do Earth Engine pode ser instalada em uma máquina local usando o conda, um gerenciador de pacotes e ambientes do Python. O Conda é incluído nas distribuições Python Anaconda e Miniconda. O Anaconda é uma plataforma de programação de ciência de dados que inclui mais de 1.500 pacotes, enquanto o Miniconda inclui apenas o conda e suas dependências. Qualquer uma dessas distribuições do Python é adequada para instalar e trabalhar com a API Earth Engine. Se você não conhece essas distribuições, acesse os links para saber mais.

Este guia vai mostrar como:

• Verificar se já há uma instalação do conda
• Como instalar o conda em uma máquina local
• Como instalar a API Python do Earth Engine
• Como configurar credenciais de autenticação
• Teste a API

Observação: as etapas a seguir serão concluídas em um prompt de comando do Windows ou em um terminal Unix (Linux/Mac). Use as guias na parte de cima de cada seção de código para alternar para comandos relevantes ao seu sistema operacional.

Verificar a instalação do conda

Se o conda já estiver instalado no seu sistema, pule para a seção Instalar API. Se você não tiver certeza se o conda está instalado, verifique digitando o seguinte comando na interface de linha de comando.

conda --help

Se o conda estiver instalado e o caminho do sistema registrado na variável de ambiente PATH, o conteúdo de ajuda do conda vai aparecer no terminal. Se o conteúdo de ajuda aparecer, pule para a seção Instalar API. Se o conda não for reconhecido, o resultado será algo como: conda not found or not recognized as a command. É possível que o programa exista no seu sistema, mas não esteja registrado na variável de ambiente PATH. Mesmo assim, para manter a consistência, continue com a seção Instalar o conda, já que é difícil abordar todas as configurações possíveis do sistema. Desde que a pasta "miniconda3" não exista na pasta "Home", as instruções de instalação do conda a seguir serão bem-sucedidas. Para mais informações sobre o local de instalação e o registro do conda, consulte as páginas Instalação do Miniconda e Instalação do Anaconda.

Instalar o conda

Observação: pule para a seção Instalar API se o conda já estiver instalado no seu sistema.

Nesta seção, você vai fazer o download e instalar o Miniconda, que vai servir como a plataforma Python para acessar a API Earth Engine. Conforme descrito acima, você pode usar o Miniconda ou o Anaconda, mas para minimizar o impacto no seu sistema, este guia descreve uma instalação do Miniconda sem alterar as variáveis de ambiente do sistema. Se você preferir o Anaconda, consulte as instruções de instalação aqui e pule para a seção Instalar API.

Instalar o Miniconda

O download e a instalação do Miniconda são feitos em três etapas:

1. Faça o download do instalador de 64 bits do Python 3 Miniconda no seu diretório inicial.
2. Executar o instalador
3. Excluir o instalador

Copie e cole as linhas a seguir na interface de linha de comando apropriada para seu sistema. A instalação resulta em uma pasta chamada "miniconda3" adicionada ao seu diretório inicial.

1. Faça o download do instalador do Miniconda no seu diretório principal.

Linux

wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh

Mac

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o ~/miniconda.sh

Windows

powershell -command "Invoke-WebRequest -Uri https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -OutFile ~\miniconda.exe"

2. Instale o Miniconda silenciosamente, aceitando os padrões, no seu diretório "Home".

Linux

bash ~/miniconda.sh -b

Mac

bash ~/miniconda.sh -b

Windows

start /B /WAIT %UserProfile%\miniconda.exe /InstallationType=JustMe /AddToPath=0 /RegisterPython=0 /S /D=%UserProfile%\miniconda3

3. Remova o instalador do Miniconda do seu diretório "Home".

Linux

rm ~/miniconda.sh

Mac

rm ~/miniconda.sh

Windows

del %UserProfile%\miniconda.exe

Testar a instalação do Miniconda

Imprima o menu de ajuda do comando conda para testar a instalação do Miniconda. Como o Miniconda não foi adicionado à variável de ambiente PATH do sistema, primeiro você precisa ativar o conda para esta sessão chamando o comando activate pelo caminho completo do sistema. Um teste bem-sucedido vai resultar no conteúdo de ajuda do conda aparecendo no terminal. Execute as linhas a seguir na interface de linha de comando do seu sistema.

Linux

source $HOME/miniconda3/bin/activate
conda --help

Mac

source $HOME/miniconda3/bin/activate
conda --help

Windows

%UserProfile%\miniconda3\condabin\activate
conda --help

Observação: um ambiente conda ativado pode ser desativado executando: conda deactivate.

Observação: se o caminho para o Miniconda não estiver definido como uma variável de ambiente, como neste caso de instalação, será necessário ativar o Miniconda para cada nova sessão de linha de comando no futuro, incluindo o uso da API. Use o primeiro comando do snippet de código acima para ativar o Miniconda conforme necessário.

Adicionar o Miniconda à variável PATH

Cuidado: alterar a variável PATH do sistema pode ter consequências indesejadas.

Você pode adicionar o caminho de instalação do Miniconda à variável PATH do sistema, o que permite interagir com o conda com uma simples chamada para conda sem precisar executar o comando activate pelo caminho completo. As instruções a seguir mostram como adicionar a instalação do Miniconda à variável PATH do sistema.

Linux

Adicione o seguinte caminho à variável de ambiente "PATH" seguindo as instruções da GUI ou da linha de comando abaixo.

$HOME/miniconda3/bin

Fatura uniforme governamental (GUI, na sigla em inglês)

1. Abra o arquivo .bashrc encontrado no diretório $HOME em um editor de texto.

xdg-open ~/.bashrc

2. Copie e cole as linhas a seguir na parte de baixo do arquivo.

# add path to conda
export PATH="$HOME/miniconda3/bin:$PATH"

3. Salve o arquivo e feche o editor de texto.

Observação: o caminho do conda adicionado pode ser removido excluindo as linhas que acabaram de ser adicionadas.

Linha de comando

Insira o comando a seguir em um terminal para anexar o caminho do conda ao arquivo ~/.bashrc.

printf '\n# add path to conda\nexport PATH="$HOME/miniconda3/bin:$PATH"\n' >> ~/.bashrc

Mac

Adicione o seguinte caminho à variável de ambiente "PATH" seguindo as instruções da GUI ou da linha de comando abaixo.

$HOME/miniconda3/bin

Fatura uniforme governamental (GUI, na sigla em inglês)

1. Abra o arquivo .bashrc encontrado no diretório $HOME em um editor de texto.

touch ~/.bashrc; open -t ~/.bashrc

2. Copie e cole as linhas a seguir na parte de baixo do arquivo.

# add path to conda
export PATH="$HOME/miniconda3/bin:$PATH"

3. Salve o arquivo e feche o editor de texto.

Observação: o caminho do conda adicionado pode ser removido excluindo as linhas que acabaram de ser adicionadas.

Linha de comando

Insira o comando a seguir em um terminal para anexar o caminho do conda ao arquivo ~/.bashrc.

printf '\n# add path to conda\nexport PATH="$HOME/miniconda3/bin:$PATH"\n' >> ~/.bashrc

Windows

Adicione o seguinte caminho à variável de ambiente "Path" seguindo as instruções da GUI ou da linha de comando abaixo.

%UserProfile%\miniconda3\condabin

Fatura uniforme governamental (GUI, na sigla em inglês)

1. Insira a seguinte linha em um prompt de comando para abrir a caixa de diálogo "Variável de ambiente".

rundll32 sysdm.cpl,EditEnvironmentVariables

2. Clique duas vezes na variável "Caminho" na seção "Usuário" para selecionar e editar.

3. Clique no botão "Editar texto" na nova janela de diálogo "Editar" para abrir o editor.

4. Adicione a seguinte string ao final do valor da variável "Path" atual. Use ponto e vírgula (;) para envolver a entrada e diferenciá-la das entradas vizinhas.

%UserProfile%\miniconda3\condabin;

5. Clique nos botões "OK" até que todas as janelas de diálogo sejam fechadas.

Observação: o caminho do conda adicionado pode ser removido seguindo o mesmo método de edição.

Linha de comando

Use o comando setx para anexar o caminho. Em um prompt de comando, insira:

setx Path "%Path%%UserProfile%\miniconda3\condabin;"

Observação: reinicie as interfaces de linha de comando abertas para que as mudanças na variável de ambiente entrem em vigor.

Inicializar o conda

Inicializa o conda para interação com o shell. Execute o comando a seguir para informações sobre a inicialização de vários shells. Siga as instruções impressas no console ao inserir o comando.

conda init --help

Depois de reiniciar a interface de linha de comando, você poderá ativar o ambiente base do conda com o seguinte comando.

conda activate

Instalar API

A API Python do Earth Engine é distribuída como um pacote conda-forge em: https://anaconda.org/conda-forge/earthengine-api. Ele é instalado com o comando conda install. Antes da instalação, crie um ambiente conda especificamente para o Earth Engine. A instalação da API Earth Engine no próprio ambiente garante que ela e os pacotes dependentes não causem problemas de controle de versões com o ambiente de base ou qualquer outro ambiente configurado anteriormente, e vice-versa. Para mais informações sobre como gerenciar ambientes conda, acesse este site.

Observação: a primeira etapa a seguir pressupõe que você acabou de concluir a seção Instalar o conda sem alterar as variáveis de ambiente ou inicializar o conda para uso no shell. O comando é estruturado de acordo. Se você já tiver instalado o conda por outro meio ou registrado o conda para uso no shell, faça o necessário para ativar o conda e comece a seguir as instruções na etapa 2.

1. Ative o ambiente base do conda, se ainda não estiver ativo.

Linux

source $HOME/miniconda3/bin/activate

Mac

source $HOME/miniconda3/bin/activate

Windows

%UserProfile%\miniconda3\condabin\activate

2. Crie um ambiente virtual do conda para a API Earth Engine.

conda create --name ee

Confirme a criação do ambiente.

3. Ative o ambiente do conda ee.

conda activate ee

4. Instale a API no ambiente ee do conda. Verifique se (ee) aparece no início da linha de comando, indicando que você está trabalhando no ambiente ee.

conda install -c conda-forge earthengine-api

Você precisará confirmar a instalação da API e das dependências dela. Depois de confirmar, o conda vai fazer o download e instalar as dependências. Se tudo der certo, você terá um ambiente conda chamado "ee" com todos os requisitos para acessar a API, além da earthengine ferramenta de linha de comando.

Receber credenciais

Antes de usar a API Earth Engine ou a ferramenta de linha de comando earthengine, você precisa fazer uma autenticação única que autoriza o acesso ao Earth Engine em nome da sua Conta do Google. Para autenticar, use o comando authenticate da ferramenta de linha de comando earthengine.

No ambiente ee do conda, execute o comando a seguir e siga as instruções impressas resultantes. Um URL será fornecido para gerar um código de autorização após a concordância. Copie o código de autorização e insira-o como entrada de linha de comando.

earthengine authenticate

Ao inserir o código de autorização, um token de autorização é salvo em um arquivo de credenciais, que pode ser encontrado abaixo. O uso subsequente do comando ee.Initialize() da API e da ferramenta de linha de comando earthengine vai consultar esse arquivo para autenticar. Se quiser revogar a autorização, basta excluir o arquivo de credenciais.

Linux

ls $HOME/.config/earthengine/credentials

Mac

ls $HOME/.config/earthengine/credentials

Windows

dir %UserProfile%\.config\earthengine\credentials

Teste a API

Execute um script simples do Python que imprima metadados de um conjunto de dados DEM para testar a instalação da API. Ele precisa mostrar um objeto JSON no console.

1. Inicie um interpretador python no ambiente conda ee.

python

2. Execute as seguintes linhas de Python uma por uma para imprimir os metadados de um conjunto de dados de DEM

import ee

# Initialize the Earth Engine module.
ee.Initialize()

# Print metadata for a DEM dataset.
print(ee.Image('USGS/SRTMGL1_003').getInfo())

Uso subsequente da API

Sempre que quiser usar a API Earth Engine, primeiro ative o ambiente conda ee. O procedimento de ativação depende de o conda estar registrado para uso no shell ou não. Siga as instruções relevantes para sua instalação do conda abaixo.

Conda não registrado

O comando de ativação do ambiente ee do conda a seguir pressupõe que o conda foi instalado seguindo as instruções na seção Instalar o conda acima. Ou seja, o caminho de instalação é presumido com base nas etapas anteriores. Execute o seguinte comando em uma interface de linha de comando.

Linux

source $HOME/miniconda3/bin/activate ee

Mac

source $HOME/miniconda3/bin/activate ee

Windows

%UserProfile%\miniconda3\condabin\activate ee

Conda registrado

O comando de ativação do ambiente ee do conda a seguir pressupõe que o conda foi registrado para uso no shell ou no prompt de comando pelas instruções deste guia ou por outros meios. Execute o seguinte comando em uma interface de linha de comando.

conda activate ee

Depois de executar o comando, (ee) vai aparecer no início da linha de comando, indicando que você está trabalhando no ambiente ee.

Agora você pode iniciar um interpretador do Python e acessar a API Python do Earth Engine. Consulte a página Instalação do Python para orientações gerais sobre como trabalhar com a API Python.

Como atualizar a API

Use o comando conda update para atualizar seu ambiente ee para a versão mais recente da API. Primeiro, ative o ambiente ee do conda, se ele ainda não estiver ativo.

conda update -c conda-forge earthengine-api

Para conferir o número da versão instalada no momento em Python, imprima a propriedade __version__ da biblioteca ee. Inicie um interpretador Python inserindo python na linha de comando do ambiente conda ee e insira os comandos a seguir.

import ee
print(ee.__version__)

Compartilhar seu ambiente ee

É útil compartilhar seu ambiente Python do conda com outras pessoas para conseguir resultados reproduzíveis e replicáveis, principalmente quando você instalou pacotes Python adicionais. O Conda oferece uma maneira conveniente para outras pessoas replicarem seu ambiente.

No ambiente ee do conda, execute o comando a seguir para salvar um arquivo YAML chamado "ee-shared-env" no diretório inicial, que lista as especificações do ambiente.

Linux

conda env export > $HOME/ee-shared-env.yml

Mac

conda env export > $HOME/ee-shared-env.yml

Windows

conda env export > %UserProfile%\ee-shared-env.yml

Compartilhe o arquivo resultante, e o destinatário poderá replicar o ambiente executando o seguinte comando do conda.

conda env create -f path-to-ee-shared-env.yml

Observação: a primeira linha do arquivo ee-shared-env.yml define o nome do ambiente a ser criado. O Conda não vai substituir um ambiente existente. Portanto, talvez seja necessário alterar o nome do ambiente no arquivo ee-shared-env.yml. Como alternativa, use o comando remove do conda ou a flag --clone do comando create do conda para gerenciar nomes de ambiente.

Observação: a replicação de ambientes em sistemas operacionais pode falhar, já que há versões e builds de pacotes específicos do SO que podem não estar disponíveis ou criar conflitos de dependência.