Desenvolvimento

Trends.Earth é um software livre e de código aberto, licenciado sob a GNU General Public License, version 2.0 or later.

Há vários componentes na ferramenta Trends.Earth. O primeiro é um plugin QGIS que suporta cálculos de indicadores, acesso a dados brutos, relatórios e produção de mapas impressos. O código para o plugin e mais instruções sobre como instalá-lo, se você deseja modificar o código, estão em trends.earth Repositório no GitHub.

O Trends.Earth plugin para QGIS é suportado por vários scripts Python diferentes que permitem o cálculo dos vários indicadores no Google Earth Engine (GEE). Esses scripts estão na subpasta «gee» dentro do repositório GitHub. Os scripts GEE são suportados pelo módulo Python landdegradation, que inclui código para processar entradas e saídas do plugin, bem como outras funções comuns que suportam o cálculo de integrais NDVI, significância estatística e outro código compartilhado. O código para este módulo está disponível no arquivo landdegradation repositório no GitHub.

Mais detalhes abaixo sobre como contribuir com o Trends.Earth trabalhando no código do plugin, modificando o código de processamento ou contribuindo para traduzir o site e o plugin.

Modificando o código QGIS Plugin

Instalando dependências

Python

O plugin é codificado em Python. Além de ser usado para executar o plugin através do QGIS, o Python também é usado para oferecer suporte ao gerenciamento do plugin (alterando a versão, instalando versões de desenvolvimento etc.). Embora Python esteja incluído no QGIS, você também precisará de uma versão local do Python que possa ser configurada com o software necessário para gerenciar o plugin. A maneira mais fácil de gerenciar várias versões do Python é através da distribuição Anaconda. Para o trabalho de desenvolvimento do plugin, é necessário o Python 3. Para baixar o Python 3.7 (recomendado) no Anaconda, consulte esta página.

Dependências do Python

Para trabalhar com o código trends.earth, é necessário ter o Invoke instalado em sua máquina, além de vários outros pacotes usados para gerenciar a documentação, traduções, etc. Esses pacotes estão todos listados no arquivo «dev» de requisitos para Trends.Earth, para que eles possam ser instalados navegando em um prompt de comando até a raiz da pasta de código trends.earth e digitando:

pip install -r requirements-dev.txt

Nota

Se você estiver usando Anaconda, primeiro deverá ativar um ambiente virtual Python 3.7 antes de executar o comando acima (e qualquer um dos outros comandos de chamada listados na página). Uma maneira de fazer isso é iniciando um «Anaconda prompt», seguindo as instruções nesta página do Anaconda.

PyQt

PyQt5 é o kit de ferramentas gráficas usado pelo QGIS3. Para compilar a interface do usuário do Trends.Earth for QGIS3, você precisa instalar o PyQt5. Este pacote pode ser instalado a partir do pip usando:

pip install PyQt5

Nota

PyQt4 é o kit de ferramentas gráficas usado pelo QGIS2. A melhor fonte para este pacote para Windows é o conjunto de pacotes mantidos por Christoph Gohlke na UC Irvine. Para baixar o PyQt4, selecione o pacote apropriado nesta página. Escolha o arquivo apropriado para a versão do Python que você está usando. Por exemplo, se você estiver usando o Python 2.7, escolha a versão com «cp27» no nome do arquivo. Se você estiver usando o Python 3.7, escolha a versão com «cp37» no nome do arquivo. Escolha «amd64» para python de 64 bits e «win32» para python de 32 bits.

Após fazer o download no link acima, use pip para instalá-lo. Por exemplo, para a roda de 64 bits para Python 3.7, você executaria:

pip install PyQt4-4.11.4-cp37-cp37m-win_amd64.whl

Alterando a versão do plugin

A convenção para Trends.Earth é que os números de versão que terminam em um número ímpar (por exemplo, 0,65) são versões de desenvolvimento, enquanto as versões que terminam em um número par (por exemplo (0,66) são versões de lançamento. As versões de desenvolvimento do plug-in nunca são liberadas via o repositório QGIS, para que eles nunca sejam vistos pelos usuários normais do plug-in. Versões de desenvolvimento com números ímpares são usadas pela equipe de desenvolvimento do Trends.Earth ao testar novos recursos antes de seu lançamento público.

Se você deseja fazer alterações no código e baixou uma versão pública do plugin (que termina em um número par), a primeira etapa é atualizar a versão do plugin para o próximo número ímpar seqüencial. Portanto, por exemplo, se você baixou a versão 0.66 do plugin, seria necessário atualizar a versão para 0.67 antes de começar a fazer as alterações. Existem vários locais no código em que a versão é mencionada (assim como em todos os scripts GEE), portanto, há uma tarefa de chamada para ajudar na alteração da versão. Para alterar a versão para 0,67, você deve executar:

invoke set-version -v 0.67

A execução do comando acima atualizará o número da versão em todos os locais mencionados no código. Para evitar confusão, nunca mude a versão para uma que já foi lançada - sempre AUMENTE o valor da tag da versão para o próximo número ímpar.

Testando alterações no plugin

Depois de fazer alterações no código do plugin, você precisará testá-los para garantir que o plugin se comporte conforme o esperado e para garantir que não haja bugs ou erros. O plugin deve passar por testes extensivos antes de ser lançado no repositório QGIS (onde pode ser acessado por outros usuários) para garantir que quaisquer alterações no código não quebrem o plugin.

Para testar as alterações feitas no plugin no QGIS, será necessário instalá-lo localmente. Existem tarefas de chamada que auxiliam nesse processo. A primeira etapa antes da instalação do plug-in é garantir que você o tenha configurado com todas as dependências necessárias para executar no QGIS. Para fazer isso, execute:

invoke plugin-setup

A tarefa acima só precisa ser executada imediatamente após o download do código trends.earth ou se forem feitas alterações nas dependências do plugin. Por padrão, o plugin-setup reutiliza todos os arquivos em cache na sua máquina. Para começar do zero, adicione o sinalizador -c (clean) ao comando acima.

Após executar o plugin-setup, você está pronto para instalar o plugin na pasta de plug-ins do QGIS em sua máquina. Para fazer isso, execute:

invoke plugin-install

Após executar o comando acima, você precisará 1) reiniciar o QGIS ou 2) usar o plugin reloader para recarregar o plugin Trends.Earth e verificar os efeitos das alterações que você fez.

Por padrão, plugin-install substituirá os arquivos de plugin existentes em sua máquina, mas deixará em vigor quaisquer dados (limites administrativos etc.) que o plugin possa ter baixado. Para começar do zero, adicione o sinalizador -c (clean) ao comando acima. Pode ser necessário fechar o QGIS para executar com êxito uma instalação limpa do plugin usando o sinalizador -c.

Nota

Por padrão, a instalação assume que você deseja instalar o plugin a ser usado no QGIS3. Para instalar o plug-in para uso no QGIS3, adicione o sinalizador -v 2 ao comando plugin-install. Lembre-se de que o plugin pode ou não ser totalmente funcional no QGIS3 - o plugin foi originalmente projetado para o QGIS2 e ainda está sendo testado no QGIS3.

Sincronizando e implementando alterações nos binários

Para acelerar os cálculos no Trends.Earth, algumas das ferramentas permitem o uso de binários pré-compilados que foram compilados usando o numba. O Numba é um compilador de código aberto que pode compilar código Python e NumPy, tornando-o mais rápido do que quando é executado como Python comum. Para evitar que os usuários do Trends.Earth precisem baixar o Numba e todas as suas dependências, a equipe do Trends.Earth disponibiliza binários pré-compilados para download, se os usuários optarem por instalá-los.

Para gerar binários pré-compilados para o SO, bitness (32/64 bits) e a versão Python que você está executando em sua máquina, use:

invoke binaries-compile

Nota

Você precisará de um compilador C ++ para que o comando acima funcione. No Windows, consulte esta página do github para detalhes sobre como instalar o compilador Microsoft Visual C ++ necessário para sua versão do Python. No MacOS, você provavelmente precisará instalar o Xcode. No Linux, instale a versão apropriada do GCC.

Para disponibilizar publicamente os binários, eles são distribuídos por meio de um bucket do Amazon Web Services S3. Para fazer upload dos binários gerados com o comando acima no bucket, execute:

invoke binaries-sync

Nota

O comando acima falhará se você não tiver chaves que permitam acesso de gravação ao bucket trends.earth no S3.

O comando acima sincronizará cada arquivo binário individual com o S3. No entanto, os usuários da ferramenta baixam os binários como um único arquivo zip vinculado à versão do plug-in que eles estão usando. Para gerar esse arquivo zip para que ele possa ser acessado pelos usuários do Trends.Earth, execute:

invoke binaries-deploy

Nota

O comando acima falhará se você não tiver chaves que permitam acesso de gravação ao bucket trends.earth no S3.

Construindo um arquivo ZIP contendo o plugin

Existem várias tarefas de chamada para ajudar na criação de um arquivo ZIP para implantar o plugin no repositório QGIS ou para compartilhar a versão de desenvolvimento do plugin com outras pessoas. Para empacotar o plugin e todas as suas dependências em um arquivo ZIP que pode ser instalado seguindo o procedimento descrito no Leiame do Trends.Earth, execute:

invoke zipfile-build

Este comando criará uma pasta chamada build na raiz da pasta de código trends.earth, e nessa pasta criará um arquivo chamado LDMP.zip. Este arquivo pode ser compartilhado com outras pessoas, que podem usá-lo para instalar manualmente o Trends.Earth. Isso pode ser útil se houver a necessidade de compartilhar os recursos mais recentes com alguém antes que eles estejam disponíveis na versão divulgada publicamente do plugin.

Implementando o Arquivo ZIP da versão em desenvolvimento

A página Trends.Earth GitHub fornece um link para um arquivo ZIP que permite que usuários que não sejam desenvolvedores acessem a versão de desenvolvimento do Trends.Earth. Para criar um arquivo ZIP e disponibilizá-lo nessa página (o arquivo ZIP está armazenado no S3), execute:

invoke zipfile-deploy

Este comando irá empacotar o plugin e copiá-lo para https://s3.amazonaws.com/trends.earth/sharing/LDMP.zip.

Nota

O comando acima falhará se você não tiver chaves que permitam acesso de gravação ao bucket trends.earth no S3.

Modificando o código de processamento do Earth Engine

Os scripts de processamento do Google Earth Engine (GEE) usados pelo Trends.Earth são todos armazenados na pasta «gee», na pasta principal trends.earth. Para que esses scripts sejam acessíveis aos usuários do plugin trends.earth QGIS, eles precisam ser implantados no serviço api.trends.earth que a Conservação Internacional mantém para permitir que os usuários do plugin usem o Earth Engine sem a necessidade de saber como programar ou ter contas de usuário individuais no GEE. A seguir, descrevemos como testar e implantar scripts GEE para serem usados com o Trends.Earth.

Configurando dependências

docker

O pacote trends.earth-CLI requer docker para funcionar. Siga estas instruções para instalar a janela de encaixe no Windows e` estas instruções para instalar a janela de encaixe no Mac OS <https://docs.docker.com/docker-for-mac/install/>`_. Se você estiver executando o Linux, siga as instruções nesta página que são apropriados para a distribuição Linux que você está usando.

Testando um script do Google Earth Engine localmente

Depois de instalar o pacote trends.earth-CLI, você precisará configurar um arquivo .tecli.yml com um token de acesso a uma conta de serviço GEE para testar scripts no GEE. Para configurar a conta de serviço GEE para o tecli, primeiro obtenha a chave da sua conta de serviço no formato JSON (no console do Google Cloud) e, em seguida, codifique-a em base64. Forneça a chave codificada base64 ao tecli com o seguinte comando:

invoke tecli-config set EE_SERVICE_ACCOUNT_JSON key

onde «chave» é a chave da conta de serviço no formato JSON codificado em base64.

Ao converter um script que especifica o código a ser executado no GEE de JavaScript para Python, ou ao fazer modificações nesse código, pode ser útil testar o script localmente, sem implementá-lo no servidor api.trends.earth. Para fazer isso, use a tarefa de chamada run. Por exemplo, para testar o script «land_cover», vá para o diretório raiz do código Trends.Earth e, em um prompt de comando, execute:

invoke tecli-run land_cover

Isso usará o pacote trends.earth-CLI para criar e executar um contêiner de docker que tentará executar o script «land_cover». Se houver algum erro de sintaxe no script, eles aparecerão quando o contêiner for executado. Antes de enviar um novo script para api.trends.earth, sempre verifique se invoke tecli-run é capaz de executar o script sem erros.

Ao usar invoke tecli-run, você pode receber um erro dizendo:

Invalid JWT: Token must be a short-lived token (60 minutes) and in a
reasonable timeframe. Check your iat and exp values and use a clock with
skew to account for clock differences between systems.

Este erro pode ser causado se o relógio no contêiner do docker ficar fora de sincronia com o relógio do sistema. Reiniciar docker deve corrigir esse erro.

Contribuindo para a documentação

Sumário

A documentação para Trends.Earth é produzida usando o Sphinx, e está escrito em` reStructuredText <http://docutils.sourceforge.net/rst.html>`_ formato. Se você não for familiarizado com nenhuma dessas ferramentas, consulte a documentação para obter mais informações sobre como elas são usadas.

A documentação do Trends.Earth é armazenada na pasta «docs», no diretório principal trends.earth. Dentro dessa pasta, há vários arquivos e pastas importantes que você deve conhecer:

  • build: contém a documentação da build para trends.earth (no formato PDF e HTML). Observe que ele só aparecerá na sua máquina depois de executar a tarefa de chamada docs-build.

  • i18n: contém traduções da documentação para outros idiomas. Os arquivos aqui são normalmente processados automaticamente usando tarefas com o comando «invoke», portanto, você nunca deve ter motivos para modificar nada nesta pasta.

  • recursos: contém todos os recursos (principalmente imagens ou PDFs) mencionados na documentação. Atualmente, existe apenas uma pasta («EN», em inglês), pois todas as imagens na documentação são da versão em inglês do plugin - pastas adicionais apropriadas podem ser adicionadas em «resources» com códigos de duas letras identificando o idioma para incluir imagens específicas para um idioma específico.

  • source: contém os arquivos de origem reStructuredText que definem a documentação (esse é o texto em inglês real da documentação e os arquivos que você provavelmente precisará modificar).

Instalando dependências

Dependências do Python

Para trabalhar com a documentação, você deve ter os pacotes invoke, Sphinx, sphinx-intl e sphinx-rtd-theme (o tema do site Trends.Earth) instalados em sua máquina. Esses pacotes estão todos listados no arquivo de requisitos «dev» do Trends.Earth, para que possam ser instalados navegando em um prompt de comando até a raiz da pasta de código trends.earth e digitando:

pip install -r requirements-dev.txt

LaTeX

O LaTeX é usado para produzir saídas em PDF da documentação para Trends.Earth.

Para instalar LaTeX no Windows, siga o processo descrito aqui para instalar a distribuição proTeXt do LaTeX a partir do arquivo zip disponível aqui. O instalador do LaTeX é bastante grande (vários GB), portanto, pode levar algum tempo para baixar e instalar.

No MacOS, o MacTeX é uma boa opção e pode ser instalado seguindo as instruções aqui.

No Linux, a instalação do LaTeX deve ser muito mais fácil - use o gerenciador de pacotes da sua distribuição para encontrar e instalar qualquer distribuição do LaTeX incluída por padrão.

Qt Linguist

O Qt Linguist também é necessário para extrair strings do código e da GUI para tradução. O comando «lrelease» deve estar disponível e no seu caminho. Tente tentar

lrelease

dentro de uma janela do terminal. Se o arquivo não for encontrado, você precisará instalar o Qt Linguist. Esta página é uma fonte de instaladores para o Qt Linguist. Depois de instalar o Qt Linguist, adicione a pasta que contém lrelease ao seu caminho para que o script de chamada Trends.Earth possa encontrá-lo.

Atualizando e preparando a documentação

Depois de instalar os requisitos do pacote sphinx, você estará pronto para começar a modificar a documentação. Os arquivos a serem modificados estão localizados na pasta «docs\source». Depois de fazer alterações nesses arquivos, você precisará criar a documentação para visualizar os resultados. Existem duas versões da documentação do Trends.Earth: uma versão HTML (usada para o site) e uma versão PDF (para download offline). Para criar a documentação do Trends.Earth, use a tarefa «docs-build» do invoke. Por padrão, esta tarefa cria a documentação completa do Trends.Earth, em HTML e PDF, para todos os idiomas suportados. Isso pode levar algum tempo para ser executado (até algumas horas). Se você está apenas testando os resultados de algumas pequenas alterações na documentação, geralmente é melhor usar a opção -f (de «fast» = rápido). Esta opção criará apenas a documentação HTML em inglês, que deve levar apenas alguns segundos. Para criar usando a opção rápida, execute:

invoke docs-build -f

O comando acima levará alguns segundos para ser executado e, se você procurar em «docs\ build\html\en», verá a versão HTML da documentação. Carregue o arquivo «index.html» em um navegador da Web para ver como fica.

Para criar a documentação completa, para todos os idiomas, em PDF e HTML (lembre-se de que isso pode levar algumas horas para ser concluído), execute:

invoke docs-build

Após executar o comando acima, você verá (em inglês) a documentação HTML em «docs\build\html\en», e os PDFs da documentação em «docs\build\html\en\pdfs».

Se você quiser testar um idioma específico (testar traduções, por exemplo), poderá especificar um código de duas letras identificando o idioma para criar apenas os documentos para esse idioma. Por exemplo, para criar apenas a documentação em espanhol, execute:

invoke docs-build -l es

Observe que as opções podem ser combinadas; portanto, você pode usar a opção rápida para criar apenas a versão HTML da documentação em espanhol executando:

invoke docs-build -f -l es

Ao criar a documentação completa para o site, é uma boa idéia remover primeiro todas as versões antigas da documentação, pois elas podem conter arquivos que não são mais usados na documentação atualizada. Para fazer isso, use a opção -c (clean):

invoke docs-build -c

Em geral, a preparação dos documentos DEVE ser concluído sem erros se você planeja compartilhar a documentação ou publicá-la no site. No entanto, ao testar localmente, convém ignorar os erros de documentação que aparecem somente em alguns idiomas (devido a erros de sintaxe decorrentes de erros de tradução etc.) e continuar a compilar a documentação restante, independentemente de haver erros. Para fazer isso, use a opção -i (ignorar erros):

invoke docs-build -i

Sempre que você fizer alterações no texto da documentação, é uma boa ideia enviar as últimas atualizações para o Transifex, para que possam ser traduzidas. Para atualizar as seqüências de caracteres no Transifex com novas alterações, execute:

invoke translate-push

Nota

Para executar com êxito o comando acima, você precisará da chave da conta transifex Trends.Earth.

Preparando a documentação para publicar a nova versão

Antes de liberar a nova documentação, sempre baixe as últimas traduções do Transifex para que todas as traduções estejam atualizadas. Para fazer isso, execute:

invoke translate-pull

Para criar uma versão pública da documentação (no site ou em PDF), você deve compilar toda a documentação usando docs-build sem parâmetros adicionais:

invoke docs-build

Esse processo deve ser concluído com êxito, sem erros. Se ocorrer algum erro durante o processo, revise a mensagem de erro e faça as modificações necessárias para permitir que a compilação seja concluída com êxito. Depois que a compilação é concluída sem erros, os arquivos estão prontos para serem implementados no site.

Nota

Ambos os comandos acima também têm opções -f (force) que forçam a baixar ou subir as últimas traduções do ou para o Transifex (respectivamente). Use essas opções apenas se tiver MUITO certo do que está fazendo, pois elas podem substituir completamente as traduções no Transifex, resultando em perda de trabalho dos tradutores se as traduções mais recentes ainda não foram submetidas para o repositório github.

Adicionando novo texto de documentação

Quaisquer novos arquivos .rst adicionados à documentação precisam ser adicionados a vários arquivos de configuração para garantir que apareçam no menu de navegação, que sejam traduzidos corretamente, e (para tutoriais) para garantir que sejam gerados em PDF para que possam ser baixados para uso offline.

  • docs\source\index.rst: adicione novos arquivos .rst no local apropriado aqui para garantir que eles estejam vinculados no menu de navegação.

  • .tx\config: lista os novos arquivos .rst aqui (no mesmo formato dos outros arquivos já incluídos) para tornar o software de tradução ciente deles, para que possam ser traduzidos

  • docs\source\conf.py: se você deseja gerar um arquivo PDF da página do site, deve listar essa página na lista latex_documents. Normalmente, fazemos isso apenas para as páginas de tutoriais que queremos disponibilizar aos participantes do workshop em PDFs individuais. Todas as páginas do site serão incluídas na versão PDF do site como um todo, independentemente de estar na lista latex_documents.

Adicionando novas imagens ou outros recursos

Quaisquer novas imagens ou outros recursos (PDFs etc.) necessários à documentação devem ser adicionados em «docs\resources\en». Se desejar, é possível fazer upload de versões diferentes de uma imagem para que a imagem apareça com as traduções adequadas. Isso pode ser útil se você quiser mostrar a interface da GUI no idioma apropriado, por exemplo. Para fazer isso, primeiro faça upload de uma cópia da imagem para «docs\resourcesen» (com o texto em inglês). Em seguida, crie uma cópia da imagem com texto traduzido e coloque-a na pasta apropriada para esse idioma (por exemplo, uma imagem mostrando traduções em espanhol seria exibida em «docs\resources\es»). A versão em inglês da imagem será usada como padrão para todos os idiomas para os quais uma versão nativa da imagem não é fornecida, enquanto uma versão localizada será usada quando disponível.

Nota

Há outra pasta, docs\\source\\static, usada para reter recursos temporariamente enquanto executa os scripts que preparam a documentação do Trends.Earth. Você pode ter imagens listadas nessa pasta, se alguma vez construiu a documentação nessa máquina. Esta pasta nunca deve ser usada para adicionar novos recursos - os novos recursos sempre devem estar em docs\\resources\\en ou, para imagens traduzidas, na pasta específica do idioma apropriada em docs\\resources.

Contribuindo como tradutor

As traduções para o plugin QGIS e também para este site são gerenciadas pelo transifex. Se você quiser contribuir com a tradução do plugin e da documentação (e gostaríamos muito de ter sua ajuda!), pode solicitar para se juntar a nossa equipe por meio de transifex, ou enviando um email para trends.earth@conservation.org.