Desarrollo

Trends.Earth es un software gratuito y de código abierto, licenciado bajo la Licencia Pública General GNU, versión 2.0 o posterior.

Hay una serie de componentes para las Trends.Earth herramienta. El primero es un complemento QGIS que admite el cálculo de indicadores, el acceso a datos sin procesar, informes y producción de mapas impresos. El código para el complemento, y más instrucciones sobre cómo instalarlo si desea modificar el código, están en trends.earth Depósito de GitHub.

El complemento de QGIS Trends.Earth es compatible con varios scripts Python diferentes que permiten el cálculo de varios indicadores en Google Earth Engine (GEE). Estas secuencias de comandos se encuentran en la subcarpeta «gee» de ese repositorio de GitHub. Los scripts GEE son compatibles con el módulo Python landdegradation, que incluye código para procesar entradas y salidas para el complemento, así como otras funciones comunes que admiten el cálculo de integrales NDVI, significado estadístico y otro código compartido. El código para este módulo está disponible en landdegradation repositorio en GitHub.

A continuación encontrará más detalles sobre cómo contribuir a Trends.Earth trabajando en el código del complemento, modificando el código de procesamiento o contribuyendo a traducir el sitio web y el complemento.

Modificación del código del complemento QGIS

Instalar dependencias

Python

El complemento está codificado en Python. Además de usarse para ejecutar el complemento a través de QGIS, Python también se usa para admitir la administración del complemento (cambiar la versión, instalar versiones de desarrollo, etc.). Aunque Python está incluido con QGIS, también necesitará una versión local de Python que pueda configurar con el software necesario para administrar el complemento. La forma más fácil de administrar múltiples versiones de Python es a través de la distribución Anaconda. Para trabajar desarrollando el complemento, se requiere Python 3. Para descargar Python 3.7 (recomendado) a través de Anaconda, vea esta página.

Dependencias de Python

Para trabajar con el código de tendencias.earth, debe tener Invoke instalado en su máquina, así como una serie de otros paquetes que se utilizan para administrar la documentación, las traducciones, etc. Estos paquetes se enumeran en el «dev» archivo de requisitos para Trends.Earth, por lo que se pueden instalar navegando en un símbolo del sistema a la raíz de la carpeta de códigos trend.earth y escribiendo:

pip install -r requirements-dev.txt

Nota

Si está utilizando Anaconda, primero querrá activar un entorno virtual Python 3.7 antes de ejecutar el comando anterior (y cualquiera de los otros comandos de invocación enumerados en la página). Una forma de hacerlo es iniciando un «Anaconda prompt», siguiendo las instrucciones en esta página de Anaconda <https://docs.anaconda.com/anaconda/user-guide/getting-started/#write-a-python-program-using-anaconda-prompt-or-terminal>`_.

PyQt

PyQt5 es el kit de herramientas gráficas utilizado por QGIS3. Para compilar la interfaz de usuario de Trends.Earth para QGIS3 necesita instalar PyQt5. Este paquete se puede instalar desde pip usando:

pip install PyQt5

Nota

PyQt4 es el kit de herramientas gráficas utilizado por QGIS2. La mejor fuente para este paquete en Windows es el conjunto de paquetes mantenido por Christoph Gohlke en UC Irvine. Para descargar PyQt4, seleccione el paquete apropiado de esta página. Elija el archivo apropiado para la versión de Python que está utilizando. Por ejemplo, si está utilizando Python 2.7, elija la versión con «cp27»; en el nombre del archivo. Si está utilizando Python 3.7, elija la versión con «cp37»; en el nombre del archivo. Elija «amd64»; para python de 64 bits y «win32»; para python de 32 bits.

Después de descargar desde el enlace anterior, use pip para instalarlo. Por ejemplo, para la rueda de 64 bits para Python 3.7, ejecutaría:

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

Cambiar la versión del complemento

La convención para Trends.Earth es que los números de versión que terminan en un número impar (por ejemplo, 0.65) son versiones de desarrollo, mientras que las versiones que terminan en un número par (por ejemplo (0.66) son versiones de lanzamiento. Las versiones de desarrollo del complemento nunca se lanzan a través de el repositorio QGIS, por lo que nunca son vistos por los usuarios normales del complemento. El equipo de desarrollo de Trends.Earth utiliza versiones de desarrollo con números impares mientras prueba nuevas características antes de su lanzamiento público.

Si desea realizar cambios en el código y ha descargado una versión pública del complemento (uno que termina en un número par), el primer paso es actualizar la versión del complemento al siguiente número impar secuencial. Entonces, por ejemplo, si descargó la versión 0.66 del complemento, necesitaría actualizar la versión para que sea 0.67 antes de comenzar a hacer sus cambios. Hay varios lugares en el código donde se menciona la versión (así como dentro de cada script GEE), por lo que hay una tarea de invocación para ayudar a cambiar la versión. Para cambiar la versión a 0.67, debe ejecutar:

invoke set-version -v 0.67

La ejecución del comando anterior actualizará el número de versión en cada lugar al que se hace referencia en el código. Para evitar confusiones, nunca cambie la versión a una que ya haya sido lanzada, siempre AUMENTE el valor de la etiqueta de versión al siguiente número impar.

Probar cambios en el complemento

Después de realizar cambios en el código del complemento, deberá probarlos para asegurarse de que el complemento se comporta como se esperaba y para asegurarse de que no surjan errores o errores. El complemento debe someterse a pruebas exhaustivas antes de ser lanzado al repositorio QGIS (donde otros usuarios pueden acceder a él) para garantizar que cualquier cambio en el código no rompa el complemento.

Para probar cualquier cambio que haya realizado en el complemento dentro de QGIS, deberá instalarlo localmente. Hay tareas de invocación que ayudan con este proceso. El primer paso antes de instalar el complemento es asegurarse de haber configurado el complemento con todas las dependencias que necesita para ejecutarse desde QGIS. Para hacer esto, ejecute:

invoke plugin-setup

La tarea anterior solo debe ejecutarse inmediatamente después de descargar el código de tendencias de la tierra, o si se realizan cambios en las dependencias del complemento. Por defecto, plugin-setup reutilizará cualquier archivo en caché en su máquina. Para comenzar desde cero, agregue el indicador -c (limpiar) al comando anterior.

Después de ejecutar plugin-setup, está listo para instalar el complemento en la carpeta de complementos QGIS en su máquina. Para hacer esto, ejecute:

invoke plugin-install

Después de ejecutar el comando anterior, deberá 1) reiniciar QGIS o 2) usar el cargador de complementos para volver a cargar el complemento Trends.Earth para ver los efectos de los cambios que ha realizado.

Por defecto, plugin-install sobrescribirá cualquier archivo de complemento existente en su máquina, pero dejará en su lugar cualquier dato (límites administrativos, etc.) que el complemento podría haber descargado. Para comenzar desde cero, agregue el indicador -c (limpio) al comando anterior. Es posible que deba cerrar QGIS para realizar una instalación limpia del complemento utilizando el indicador -c.

Nota

De forma predeterminada, plugin-install supone que desea instalar el complemento que se utilizará en QGIS3. Para instalar el complemento para su uso en QGIS3, agregue el indicador -v 2 al comando plugin-install. Recuerde que el complemento puede o no ser completamente funcional en QGIS3: el complemento se diseñó originalmente para QGIS2 y todavía se está probando en QGIS3.

Sincronizar e implementar cambios en los binarios

Para acelerar los cálculos en Trends.Earth, algunas de las herramientas permiten utilizar binarios precompilados que se han compilado usando numba. Numba es un compilador de código abierto que puede compilar código Python y NumPy, haciéndolo más rápido que cuando se ejecuta como Python ordinario. Para evitar que los usuarios de Trends.Earth necesiten descargar Numba y todas sus dependencias, el equipo de Trends.Earth pone a disposición binarios precompilados para descargar si los usuarios eligen instalarlos.

Para generar binarios precompilados para el sistema operativo, el bitness (32/64 bit) y la versión de Python que está ejecutando en su máquina, use:

invoke binaries-compile

Nota

Necesitará un compilador de C ++ para que funcione el comando anterior. En Windows, vea esta página de github para obtener detalles sobre cómo instalar el compilador de Microsoft Visual C ++ necesario para su versión de Python. En MacOS, lo más probable es que necesites instalar Xcode. En Linux, instale la versión adecuada de GCC.

Para que los binarios estén disponibles públicamente, se distribuyen a través de un bucket de servicios web de Amazon S3. Para cargar los binarios generados con el comando anterior en el depósito, ejecute:

invoke binaries-sync

Nota

El comando anterior fallará si no tiene teclas que permitan el acceso de escritura al bucket trends.earth en S3.

El comando anterior sincronizará cada archivo binario individual con S3. Sin embargo, los usuarios de la caja de herramientas descargan los archivos binarios como un único archivo zip vinculado a la versión del complemento que están utilizando. Para generar ese archivo zip para que los usuarios de Trends.Earth puedan acceder a él, ejecute:

invoke binaries-deploy

Nota

El comando anterior fallará si no tiene teclas que permitan el acceso de escritura al bucket trends.earth en S3.

Crear un archivo ZIP de complemento

Hay varias tareas de invocación para ayudar a construir un archivo ZIP para implementar el complemento en el repositorio QGIS, o para compartir la versión de desarrollo del complemento con otros. Para empaquetar el complemento y todas sus dependencias en un archivo ZIP que se puede instalar siguiendo el proceso descrito en el archivo Léame de Trends.Earth, ejecutar:

invoke zipfile-build

Este comando creará una carpeta llamada build en la raíz de la carpeta de tendencias trend.earth, y en esa carpeta creará un archivo llamado LDMP.zip. Este archivo se puede compartir con otros, que pueden usarlo para instalar manualmente Trends.Earth. Esto puede ser útil si es necesario compartir las últimas funciones con alguien antes de que estén disponibles en la versión pública del complemento.

Implementación del archivo ZIP de la versión de desarrollo

La página Trends.Earth GitHub proporciona un enlace a un archivo ZIP que permite a los usuarios que no sean desarrolladores acceder a la versión de desarrollo de Trends.Earth. Para crear un archivo ZIP y ponerlo a disposición en esa página (el archivo ZIP se almacena en S3), ejecute:

invoke zipfile-deploy

Este comando empaquetará el complemento y lo copiará a https://s3.amazonaws.com/trends.earth/sharing/LDMP.zip.

Nota

El comando anterior fallará si no tiene teclas que permitan el acceso de escritura al bucket trends.earth en S3.

Modificar el código de procesamiento de Earth Engine

Las secuencias de comandos de procesamiento de Google Earth Engine (GEE) utilizadas por Trends.Earth se almacenan en la carpeta «gee»; debajo de la carpeta Trends.earth principal. Para que este script sea accesible para los usuarios del plugin Trends.earth QGIS, deben implementarse en el servicio api.trends.earth que Conservation International mantiene para permitir a los usuarios del plugin usar Earth Engine sin la necesidad de saber cómo programar o tener cuentas de usuario individuales en GEE. A continuación se describe cómo probar e implementar scripts GEE para usar con Trends.Earth.

Configurar dependencias

docker

El paquete trends.earth-CLI requiere docker para funcionar. Siga estas instrucciones para instalar Docker en Windows y` estas instrucciones para instalar Docker en Mac OS <https://docs.docker.com/docker-for-mac/install/>`_. Si está ejecutando Linux, siga las instrucciones en esta página que son apropiados para la distribución de Linux que está utilizando.

Probar un script de Earth Engine localmente

Después de instalar el paquete trends.earth-CLI, deberá configurar un archivo .tecli.yml con un token de acceso a una cuenta de servicio GEE para probar los scripts en GEE. Para configurar la cuenta de servicio GEE para tecli, primero obtenga la clave para su cuenta de servicio en formato JSON (de la consola de Google Cloud), luego codifíquela en base64. Proporcione esa clave codificada en base64 a tecli con el siguiente comando:

invoke tecli-config set EE_SERVICE_ACCOUNT_JSON key

donde «key» es la llave de la cuenta de servicio de formato JSON codificada en base64.

Al convertir un script que especifica el código que se ejecutará en GEE de JavaScript a Python, o al realizar modificaciones en ese código, puede ser útil probar el script localmente, sin implementarlo en el servidor api.trends.earth. Para hacer esto, use la tarea de invocación ejecutar. Por ejemplo, para probar el script «land_cover», vaya al directorio raíz del código Trends.Earth y, en un símbolo del sistema, ejecute:

invoke tecli-run land_cover

Esto usará el paquete trends.earth-CLI para construir y ejecutar un contenedor acoplable que intentará ejecutar el script &quot;land_cover&quot;. Si hay errores de sintaxis en el script, estos aparecerán cuando se ejecute el contenedor. Antes de enviar un nuevo script a api.trends.earth, asegúrese siempre de que invoke tecli-run pueda ejecutar el script sin ningún error.

Al usar invoke tecli-run, puede recibir un error que dice:

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 error puede ser causado si el reloj en el contenedor docker no está sincronizado con el reloj del sistema. Reiniciar Docker debería corregir este error.

Contribuyendo a la documentación

Visión general

La documentación para Trends.Earth se produce usando Sphinx, y está escrito en` reStructuredText <http://docutils.sourceforge.net/rst.html>`_ formato. Si no está familiarizado con ninguna de estas herramientas, consulte su documentación para obtener más información sobre cómo se utilizan.

La documentación de Trends.Earth se almacena en la carpeta &quot;docs&quot; en el directorio principal de trends.earth. Dentro de esa carpeta hay una serie de archivos y carpetas clave a tener en cuenta:

  • build: contiene la documentación de construcción de trends.earth (en formato PDF y HTML). Tenga en cuenta que solo aparecerá en su máquina después de ejecutar la tarea de invocación docs-build.

  • i18n: contiene traducciones de la documentación a otros idiomas. Los archivos aquí normalmente se procesan automáticamente mediante tareas de invocación, por lo que nunca debería tener motivos para modificar nada en esta carpeta.

  • recursos: contiene todos los recursos (principalmente imágenes o PDF) a los que se hace referencia en la documentación. Actualmente solo hay una carpeta («EN», para inglés) ya que todas las imágenes en la documentación son de la versión en inglés del complemento, si se pueden agregar carpetas adicionales apropiadas en «recursos»; con códigos de idioma de dos letras para incluir imágenes específicas de un idioma en particular.

  • fuente: contiene los archivos fuente reStructuredText que definen la documentación (estos son el texto real en inglés de la documentación y son los archivos que es más probable que necesite modificar).

Instalar dependencias

Dependencias de Python

Para trabajar con la documentación, debe tener invoke, Sphinx, sphinx-intl y sphinx-rtd-theme (el tema para el sitio web Trends.Earth) instalado en su máquina. Todos estos paquetes se enumeran en el archivo de requisitos &quot;dev&quot; para Trends.Earth, por lo que se pueden instalar navegando en un símbolo del sistema a la raíz de la carpeta de códigos de tendencias.earth y escribiendo:

pip install -r requirements-dev.txt

LaTeX

LaTeX se utiliza para producir salidas en PDF de la documentación para Trends.Earth.

Para instalar en Windows, siga el proceso descrito aquí para instalar la distribución proTeXt de LaTeX desde` el archivo zip disponible aquí <http://ftp.math.purdue.edu/mirrors/ctan.org/systems/windows/protext/>`_. El instalador de LaTeX es bastante grande (varios GB), por lo que puede llevar un tiempo descargarlo e instalarlo.

En MacOS, MacTeX es una buena opción y se puede instalar siguiendo las instrucciones aquí.

En Linux, la instalación de LaTeX debería ser mucho más fácil: use el administrador de paquetes de su distribución para encontrar e instalar cualquier distribución de LaTeX que se incluya por defecto.

Qt Linguist

Qt Linguist también es necesario para extraer cadenas del código y la GUI para la traducción. El comando «lrelease» debe estar disponible y en su camino. Intenta probar:

lrelease

dentro de una ventana de terminal. Si no se encuentra el archivo, deberá instalar Qt Linguist. Esta página es una fuente de instaladores para Qt Linguist. Una vez que instale Qt Linguist, asegúrese de agregar la carpeta que contiene lrelease a su ruta para que el script de invocación Trends.Earth pueda encontrarla.

Actualización y construcción de la documentación.

Una vez que haya instalado los requisitos de sphinx, estará listo para comenzar a modificar la documentación. Los archivos a modificar se encuentran en la carpeta «docs\source»;. Después de realizar cualquier cambio en estos archivos, deberá compilar la documentación para ver los resultados. Existen dos versiones de la documentación de Trends.Earth: una versión HTML (utilizada para el sitio web) y una versión PDF (para descargar sin conexión). Para compilar la documentación de Trends.Earth, use la tarea de invocación &quot;docs-build&quot;. De forma predeterminada, esta tarea generará la documentación completa para Trends.Earth, en HTML y PDF, para todos los idiomas admitidos. Esto puede tardar un tiempo en ejecutarse (hasta unas pocas horas). Si solo está probando los resultados de algunos cambios menores en la documentación, generalmente es mejor usar la opción -f (para «rápido»). Esta opción construirá solo la documentación HTML en inglés, que debería tomar solo unos segundos. Para construir usando la opción rápida, ejecute:

invoke docs-build -f

El comando anterior tardará unos segundos en ejecutarse, y luego si busca en «docs\build\html\en», verá la versión HTML de la documentación. Cargue el archivo «index.html» en un navegador web para ver cómo se ve.

Para compilar la documentación completa, para todos los idiomas, en PDF y en HTML (recuerde que esto puede tardar algunas horas en completarse), ejecute:

invoke docs-build

Después de ejecutar el comando anterior, verá (para inglés) la documentación HTML en «docs\build\html\en», y los PDF de la documentación en «docs\build\html\en\pdfs».

Si desea probar un idioma específico (al probar traducciones, por ejemplo), puede especificar un código de idioma de dos letras para crear solo los documentos para ese idioma. Por ejemplo, para construir solo la documentación en español, ejecute:

invoke docs-build -l es

Tenga en cuenta que las opciones se pueden combinar, por lo que puede usar la opción rápida para crear solo la versión HTML de la documentación en español ejecutando:

invoke docs-build -f -l es

Al compilar la documentación completa para el sitio web, es una buena idea eliminar primero las compilaciones antiguas de la documentación, ya que pueden contener archivos que ya no se usan en la documentación actualizada. Para hacer esto, use la opción -c (limpiar):

invoke docs-build -c

En general, docs-build DEBE completarse sin ningún error si planea compartir la documentación o publicarla en el sitio web. Sin embargo, al probar cosas localmente, es posible que desee ignorar los errores de documentación que aparecen solo para algunos de los idiomas (debido a errores de sintaxis que surgen de errores de traducción, etc.) y continuar construyendo la documentación restante independientemente de si hay algún error . Para hacer esto, use la opción -i (ignorar errores):

invoke docs-build -i

Siempre que realice cambios en el texto de la documentación, es una buena idea enviar las últimas cadenas a Transifex para que puedan traducirse. Para actualizar las cadenas en Transifex con cualquier cambio nuevo, ejecute:

invoke translate-push

Nota

Para ejecutar con éxito el comando anterior, necesitará tener la clave para la cuenta Transifex de Trends.Earth.

Documentación de construcción para lanzamiento

Antes de lanzar nueva documentación, siempre obtenga las últimas traducciones de Transifex para que todas las traducciones estén actualizadas. Para hacer esto, ejecute:

invoke translate-pull

Para compilar una versión de la documentación para publicación pública (ya sea en el sitio web o en PDF), debe compilar toda la documentación utilizando docs-build sin parámetros adicionales:

invoke docs-build

Este proceso debe completarse con éxito sin errores. Si se produce algún error durante el proceso, revise el mensaje de error y realice las modificaciones necesarias para permitir que la compilación se complete con éxito. Una vez que la compilación se completa sin errores, los archivos están listos para implementarse en el sitio web.

Nota

Los dos comandos anteriores también tienen opciones -f (forzar) que fuerzan a tirar o empujar las últimas traducciones desde o hacia Transifex (respectivamente). Solo use estas opciones si está MUY seguro de lo que está haciendo, ya que pueden sobrescribir completamente las traducciones en Transifex, lo que lleva a la pérdida del trabajo realizado por los traductores si las últimas traducciones aún no se han comprometido con github.

Agregar nuevo texto de documentación

Todos los archivos .rst nuevos que se agreguen a la documentación deben agregarse a varios archivos de configuración para asegurarse de que aparezcan en el menú de navegación, que estén traducidos correctamente y (para tutoriales) que se generen en PDF para que puedan ser descargado para su uso sin conexión.

  • docs\source\index.rst: agregue nuevos archivos .rst en el lugar apropiado aquí para asegurarse de que estén vinculados desde el menú de navegación.

  • .tx\config: enumere los nuevos archivos .rst aquí (en el mismo formato que los otros archivos ya incluidos) para que el software de traducción los conozca y pueda traducirlos

  • docs\source\conf.py: si desea generar un archivo PDF de la página del sitio web, debe incluir esa página aquí en la lista latex_documents. Por lo general, hacemos esto solo para las páginas de tutoriales que queremos poner a disposición de los participantes del taller en archivos PDF individuales. Cada página del sitio se incluirá en la versión PDF del sitio web en su conjunto, independientemente de si está en la lista de documentos de latex.

Agregar nuevas imágenes u otros recursos

Cualquier nueva imagen u otro recurso (PDF, etc.) que necesite la documentación debe agregarse en «docs\resources\en». Si lo desea, es posible cargar diferentes versiones de una imagen para que la imagen aparezca con las traducciones adecuadas. Esto podría ser útil si desea mostrar la interfaz GUI en el idioma apropiado, por ejemplo. para hacer esto, primero suba una copia de la imagen a «docs\resources\en» (con texto en inglés). Luego, cree una copia de la imagen con el texto traducido y colóquela en la carpeta correspondiente a ese idioma (por ejemplo, una imagen que muestre traducciones al español iría en «docs\resources\es»). La versión en inglés de la imagen se utilizará como predeterminada para todos los idiomas para los que no se proporciona una versión nativa de la imagen, mientras que se utilizará una versión localizada cuando esté disponible.

Nota

Hay otra carpeta, docs\\source\\static, que se usa para contener recursos temporalmente mientras se ejecutan los scripts que compilan la documentación de Trends.Earth. Es posible que tenga imágenes en esa carpeta si alguna vez ha creado la documentación en esa máquina. Esta carpeta nunca debe usarse para agregar nuevos recursos - los nuevos recursos siempre deben ir bajo docs\\resources\\en o, para las imágenes traducidas, la carpeta específica del idioma correspondiente bajo docs\\recursos.

Contribuyendo como traductor

Transifex gestiona las traducciones para el complemento QGIS y también para este sitio. Si desea contribuir a traducir el complemento y la documentación (¡y nos encantaría contar con su ayuda!), Puede solicitar unirse a nuestro equipo a través de transifex, o enviándonos un correo electrónico a trends.earth@conservation.org.