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

A API Earth Engine Python pode ser instalada em uma máquina local usando o conda, um gerenciador de pacotes e ambientes do Python. O Conda é fornecido com as distribuições Anaconda e Miniconda do Python. 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 as dependências dele. 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 delas para saber mais.

Este guia vai orientar você sobre:

• Como verificar uma instalação do conda
• Como instalar o conda em uma máquina local
• Como instalar a API Earth Engine para Python
• 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 para seu sistema operacional.

Verificar a instalação do conda

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

conda --help

Se o conda estiver instalado e o caminho do sistema estiver 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 a 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 que esse seja o caso, para manter a consistência, continue com a seção Instalar o conda, porque é difícil abordar todas as possíveis configurações do sistema. Contanto que a pasta "miniconda3" não exista na pasta inicial, as instruções de instalação do conda a seguir vão funcionar. 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 a 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 sistema, este guia vai descrever uma instalação do Miniconda sem alterações nas variáveis ambientais do sistema. Se você preferir o Anaconda, consulte as instruções de instalação fornecidas aqui e pule para a seção Instalar a 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 do Miniconda para Python 3 de 64 bits no diretório inicial
2. Executar o instalador
3. Excluir o instalador

Conclua estas etapas copiando e colando as linhas a seguir na interface de linha de comando adequada para seu sistema. A instalação resulta em uma pasta chamada "miniconda3" adicionada ao diretório principal.

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 diretório inicial.

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

Linux

rm ~/miniconda.sh

Mac

rm ~/miniconda.sh

Windows

del %UserProfile%\miniconda.exe

Testar a instalação do Miniconda

Mostre 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 é necessário ativar o conda para esta sessão chamando o comando activate pelo caminho completo do sistema. Um teste bem-sucedido resultará na exibição do conteúdo de ajuda conda no terminal. Execute as linhas a seguir na interface de linha de comando do 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 inesperadas.

Você pode adicionar o caminho de instalação do Miniconda à variável PATH do sistema, o que permite interagir com o conda por 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 caminho a seguir à 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 conda adicionado pode ser removido excluindo as linhas adicionadas.

Linha de comando

Digite 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 caminho a seguir à 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 conda adicionado pode ser removido excluindo as linhas adicionadas.

Linha de comando

Digite 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 caminho a seguir à variável de ambiente "Path" concluindo as instruções da GUI ou da linha de comando abaixo.

%UserProfile%\miniconda3\condabin

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

1. Digite a linha a seguir 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 "Path" na seção "User" para selecioná-la para edição.

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". Verifique se a entrada está entre ponto e vírgula (;) para 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 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, digite:

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 de procedimento para informações sobre a inicialização de vários shells. Siga as instruções impressas no console após 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 comando abaixo.

conda activate

Instalar API

A API Earth Engine Python é distribuída como um pacote conda-forge em: https://anaconda.org/conda-forge/earthengine-api. Ele é instalado com o comando conda install. No entanto, antes de instalar, crie um ambiente conda especificamente para o Earth Engine. Instalar a API Earth Engine no próprio ambiente garante que ela e os pacotes dependentes não causem problemas de versionamento com o ambiente base ou qualquer outro que você tenha configurado anteriormente e vice-versa. Para mais informações sobre como gerenciar ambientes do 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 do shell. O comando é estruturado de acordo. Se você já instalou o conda por outro meio ou registrou o conda para uso no shell, faça o necessário para ativar o conda e siga as instruções a partir da etapa 2.

1. Ative o ambiente base do conda, se ainda não tiver feito isso.

Linux

source $HOME/miniconda3/bin/activate

Mac

source $HOME/miniconda3/bin/activate

Windows

%UserProfile%\miniconda3\condabin\activate

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

conda create --name ee

Será necessário confirmar a criação do ambiente.

3. Ative o ambiente ee do conda.

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ê vai precisar confirmar a instalação da API e das dependências dela. Após a confirmação, o conda vai fazer o download e instalar as dependências. Se tudo correr bem, você terá um ambiente conda chamado "ee" com todos os requisitos para acessar a API, bem como a ferramenta de linha de comando earthengine.

Receber credenciais

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

No ambiente do ee do conda, execute o comando a seguir e siga as instruções impressas. Um URL será fornecido para gerar um código de autorização após o acordo. 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 procurar este arquivo para autenticação. Se você 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 Python simples que mostra os metadados de um conjunto de dados DEM para testar a instalação da API. Ele precisa imprimir um objeto JSON no console.

1. Inicie um interpretador python no ambiente ee do conda.

python

2. Execute as linhas Python a seguir uma por vez para imprimir os metadados de um conjunto de dados 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 você quiser usar a API Earth Engine, primeiro ative o ambiente ee do conda. O procedimento de ativação depende se o conda está registrado para uso no shell ou não. Siga as instruções relevantes à instalação do conda abaixo.

Conda não registrada

O comando de ativação do ambiente ee do conda abaixo 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 comando a seguir 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 registrada

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 comando a seguir 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 o ambiente ee para a versão mais recente da API. Primeiro, ative o ambiente do 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 Python, imprima a propriedade __version__ da biblioteca ee. Inicie um interpretador Python digitando python na linha de comando do ambiente conda ee e, em seguida, digite os comandos abaixo.

import ee
print(ee.__version__)

Como compartilhar seu ambiente ee

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

No ambiente ee do conda, execute o comando a seguir para salvar um arquivo YAML chamado "ee-shared-env" no diretório principal, 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 comando conda abaixo.

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 os nomes do ambiente.

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