../../_images/logo_actinia.png ../../_images/OSGeo_community.png

Nota

Este proyecto solo se incluye en el disco de máquina virtual OSGeoLive (VMDK)

Guía de Inicio Rápido de Actinia

Actinia es una API REST de código abierto para el procesamiento escalable, distribuido y de alto rendimiento de datos geográficos que utiliza GRASS GIS para tareas computacionales. Actinia proporciona una API REST para procesar imágenes satelitales, series temporales de imágenes satelitales, datos ráster y vectoriales.

Actinia se puede utilizar de diferentes maneras:

  • curl o herramientas de línea de comando similares

  • a través de Jupyter notebooks

  • la interfaz Python

  • la extensión Postman o RESTman para navegadores

  • abrir una sesión GRASS GIS y usar la herramienta ace (ejecución de comando actinia)

  • otras interfaces para la API REST

En este inicio rápido, hacemos uso de GRASS GIS para iniciar convenientemente comandos desde la sesión al servidor actinia (que a su vez usa GRASS GIS). La idea es desarrollar rápidamente un flujo de trabajo localmente en pequeños conjuntos de datos para luego ejecutarlo en el servidor.

Uso de actinia con un cuaderno Jupyter

Numerosos cuadernos Jupyter para actinia están disponibles en https://github.com/actinia-org/actinia-jupyter

Introducción a ace - ejecución del comando actinia

La herramienta ace (detalles) permite la ejecución de un solo comando GRASS GIS o una lista de comandos GRASS GIS en un servicio REST actinia (https://actinia.mundialis.de/). Además, proporciona gestión de trabajos, la capacidad de enumerar ubicaciones, conjuntos de mapas y capas de mapas a los que el usuario tiene acceso, así como la creación y eliminación de conjuntos de mapas.

La herramienta “”ace”” debe ejecutarse en una sesión activa de GRASS GIS. Se instala con g.extension extension=ace url=https://github.com/actinia-org/ace.

odos los comandos se ejecutarán por defecto en una base de datos efímera . Por lo tanto, la salida generada debe exportarse utilizando comandos GRASS aumentados.

La opción mapset=MAPSET_NAME permite la ejecución de comandos en la base de datos de usuario persistente Se puede usar con la opción location=LOCATION_NAME.

Configurar su entorno

Asegúrese de ejecutar los siguientes comandos en una sesión de GRASS SIG .

El usuario debe configurar las siguientes variables de entorno para especificar el servidor actinia y las credenciales:

# set credentials and REST server URL
export ACTINIA_USER='demouser'
export ACTINIA_PASSWORD='gu3st!pa55w0rd'
export ACTINIA_URL='https://actinia.mundialis.de/latest'

Acceder a datos de muestra

Los conjuntos de datos seleccionados están disponibles para el usuario de demostración. Para enumerar las ubicaciones a las que tiene acceso, ejecute

ace -l
['latlong_wgs84', 'ECAD', 'nc_spm_08']

El siguiente comando enlista los conjuntos de mapas de la ubicación actual en la sesión activa de GRASS GIS (nc_spm_08):

# running ace in the "nc_spm_08" location
# (the current location name is propagated to the server):
ace location="nc_spm_08" -m
['PERMANENT', 'landsat', 'modis_lst']

Acceso a datos de fuentes externas

Los comandos GRASS GIS se pueden aumentar con extensiones específicas de actinia. El operador @ se puede especificar para un parámetro de entrada para importar un recurso ubicado en la web y para especificar la exportación de un parámetro de salida.

Es importante destacar que el nombre de la ubicación local y el conjunto de mapas deben corresponder con el del servidor REST de actinia.

Los conjuntos de datos disponibles actualmente son (organizados por proyecciones):

Inspeccione la llamada REST antes del envío

Para generar la solicitud JSON de cadena de proceso actinia, simplemente agregue la bandera -d (dry-run):

ace location="nc_spm_08" grass_command="r.slope.aspect elevation=elevation slope=myslope" -d

Mostrar un mapa - representación del mapa

Es muy fácil (y rápido) renderizar un mapa:

# check amount of pixels, just FYI
ace location="latlong_wgs84" grass_command="r.info globcover@globcover"
# render the map ... 7 billion pixels
ace location="latlong_wgs84" render_raster="globcover@globcover"
Mapa de ESA Globcover mostrado por actinia

Mapa de ESA Globcover mostrado por actinia

El procesamiento efímero es el enfoque de procesamiento predeterminado de actinia. Los comandos se ejecutan en un conjunto de mapas efímero que se eliminará después del procesamiento. Puede exportar la salida de los módulos GRASS GIS para almacenar el resultado computacional para su descarga y análisis posterior. Actualmente se admiten los siguientes formatos de exportación:

  • ráster: COG, GTiff

  • vector: GPKG, GML, GeoJSON, ESRI_Shapefile

  • tabla: CSV, TXT

Ejemplos de script

Ejemplo 1: cálculo de pendiente y aspecto y estadísticas univariadas de un modelo de elevación

Los siguientes comandos (que se almacenarán en un script y se ejecutarán con ace) importarán una capa ráster desde una fuente de Internet como mapa ráster elev, establece la región de cálculo en el mapa y calcula la pendiente. Se solicita información adicional sobre la capa ráster con r.info.

Almacene el siguiente script como archivo de texto ace_dtm_statistics.sh:

# grass ~/grassdata/nc_spm_08/user1/
# Import the web resource and set the region to the imported map
g.region raster=elev@https://storage.googleapis.com/graas-geodata/elev_ned_30m.tif -ap
# Compute univariate statistics
r.univar map=elev
r.info elev
# Compute the slope of the imported map and mark it for export as a COG file (Cloud Optimized GeoTIFF)
r.slope.aspect elevation=elev slope=slope_elev+COG
r.info slope_elev

Guarde el script en el archivo de texto en /tmp/ace_dtm_statistics.sh y ejecute el script guardado como

ace --location nc_spm_08 --script ace_dtm_statistics.sh

Los resultados (mensajes, estadísticas, archivos) se proporcionan como recursos REST.

Para generar la solicitud JSON de cadena de proceso actinia, simplemente agregue la bandera -d (dry-run):

ace -d location="nc_spm_08" script="/tmp/ace_dtm_statistics.sh"

La salida debería verse así:

{
  "version": "1",
  "list": [
    {
      "module": "g.region",
      "id": "g.region_1804289383",
      "flags": "pa",
      "inputs": [
        {
          "import_descr": {
            "source": "https://storage.googleapis.com/graas-geodata/elev_ned_30m.tif",
            "type": "raster"
          },
          "param": "raster",
          "value": "elev"
        }
      ]
    },
    {
      "module": "r.univar",
      "id": "r.univar_1804289383",
      "inputs": [
        {
          "param": "map",
          "value": "elev"
        },
        {
          "param": "percentile",
          "value": "90"
        },
        {
          "param": "separator",
          "value": "pipe"
        }
      ]
    },
    {
      "module": "r.info",
      "id": "r.info_1804289383",
      "inputs": [
        {
          "param": "map",
          "value": "elev"
        }
      ]
    },
    {
      "module": "r.slope.aspect",
      "id": "r.slope.aspect_1804289383",
      "inputs": [
        {
          "param": "elevation",
          "value": "elev"
        },
        {
          "param": "format",
          "value": "degrees"
        },
        {
          "param": "precision",
          "value": "FCELL"
        },
        {
          "param": "zscale",
          "value": "1.0"
        },
        {
          "param": "min_slope",
          "value": "0.0"
        }
      ],
      "outputs": [
        {
          "export": {
            "format": "COG",
            "type": "raster"
          },
          "param": "slope",
          "value": "slope_elev"
        }
      ]
    },
    {
      "module": "r.info",
      "id": "r.info_1804289383",
      "inputs": [
        {
          "param": "map",
          "value": "slope_elev"
        }
      ]
    }
  ]
}

Ejemplo 2: Segmentación de imagen de ortofoto con exportación

Almacene el siguiente script como archivo de texto /tmp/ace_segmentation.sh:

# grass ~/grassdata/nc_spm_08/user1/
# Import the web resource and set the region to the imported map
# we apply a importer trick for the import of multi-band GeoTIFFs:
# install with: g.extension importer url=https://github.com/actinia-org/importer
importer raster=ortho2010@https://apps.mundialis.de/workshops/osgeo_ireland2017/north_carolina/ortho2010_t792_subset_20cm.tif
# The importer has created three new raster maps, one for each band in the geotiff file
# stored them in an image group
r.info map=ortho2010.1
r.info map=ortho2010.2
r.info map=ortho2010.3
# Set the region and resolution
g.region raster=ortho2010.1 res=1 -p
# Note: the RGB bands are organized as a group
# export as a as COG file (Cloud Optimized GeoTIFF)
i.segment group=ortho2010 threshold=0.25 output=ortho2010_segment_25+COG goodness=ortho2010_seg_25_fit+COG
# Finally vectorize segments with r.to.vect and export as a GeoJSON file
r.to.vect input=ortho2010_segment_25 type=area output=ortho2010_segment_25+GeoJSON

Ejecute el script guardado en un archivo de texto como

ace location="nc_spm_08" script="/tmp/ace_segmentation.sh"

Los resultados (mensajes, estadísticas, archivos) se proporcionan como recursos REST.

Ejemplos de procesamiento persistente

Los comandos GRASS GIS se pueden ejecutar en una base de datos persistente específica del usuario. El usuario debe crear un conjunto de mapas en una ubicación existente. Se puede acceder a estos conjuntos de mapas a través de ace. Todos los resultados de procesamiento de los comandos ejecutados en este conjunto de mapas se almacenarán de forma persistente. Tenga en cuenta que el procesamiento se realizará en una base de datos efímera que se moverá al almacenamiento persistente usando el nombre correcto después del procesamiento.

Para crear un nuevo conjunto de mapas en la ubicación nc_spm_08 con el nombre test_mapset, se debe ejecutar el siguiente comando

ace location="nc_spm_08" create_mapset="test_mapset"

Ejecute los comandos desde el script de estadísticas en el nuevo conjunto de mapas persistente

ace location="nc_spm_08" mapset="test_mapset" script="/path/to/ace_dtm_statistics.sh"

Mostrar todos los mapas ráster que se han creado con el script en test_mapset

ace location="nc_spm_08" mapset="test_mapset" grass_commmand="g.list type=raster mapset=test_mapset"

Mostrar información sobre el mapa ráster elev y slope_elev

ace location="nc_spm_08" mapset="test_mapset" grass_command="r.info elev@test_mapset"
ace location="nc_spm_08" mapset="test_mapset" grass_command="r.info slope_elev@test_mapset"

Eliminar el test_mapset (siempre compruebe los nombres al eliminar)

ace location="nc_spm_08" delete_mapset="test_mapset"

Si la sesión SIG GRASS activa tiene nombres de ubicación/conjunto de mapas idénticos, se puede utilizar un alias para evitar la opción persistente en cada llamada de comando único:

alias acp="ace --persistent `g.mapset -p`"

Suponemos que en la sesión activa de GRASS GIS la ubicación actual es nc_spm_08 y el conjunto de mapas actual es test_mapset. Luego, los comandos de arriba se pueden ejecutar de la siguiente manera:

ace location="nc_spm_08" create_mapset="test_mapset"
acp location="nc_spm_08" script="/path/to/ace_dtm_statistics.sh"
acp location="nc_spm_08" grass_command="g.list type=raster mapset=test_mapset"
acp location="nc_spm_08" grass_command="r.info elev@test_mapset"
acp location="nc_spm_08" grass_command="r.info slope_elev@test_mapset"

Cosas para probar

Instalar en OSGeoLive VM con Docker Compose

Requisitos: docker y docker-compose (ya disponible en la versión OSGeoLive VM)

Para crear e implementar actinia, ejecute

git clone https://github.com/actinia-org/actinia-core.git
cd actinia_core
docker-compose -f docker/docker-compose.yml up

¡Ahora tiene una instancia de actinia en ejecución localmente! Consulte con

curl http://127.0.0.1:8088/api/v3/version

Crear nuevas ubicaciones

# (note: the "demouser" is not enabled for this)
#
# create new location
ace create_location="mylatlon 4326"
# create new mapset within location
ace location="mylatlon" create_mapset="user1"

Instalar complementos GRASS GIS (extensiones)

# (requires elevated user privileges)
#
# list existing addons, see also
# https://grass.osgeo.org/grass-stable/manuals/addons/
ace location="latlong_wgs84" grass_command="g.extension -l"

# install machine learning addon r.learn.ml2
ace location="latlong_wgs84" grass_command="g.extension extension=\"r.learn.ml2\""

¿Qué sigue?

  • Visite el sitio web de actinia en https://actinia.mundialis.de

  • Tutorial de actinia: https://neteler.gitlab.io/actinia-introduction

  • Otras lecturas: Neteler, M., Gebbert, S., Tawalika, C., Bettge, A., Benelcadi, H., Löw, F., Adams, T, Paulsen, H. (2019). Actinia: cloud based geoprocessing. In Proc. of the 2019 conference on Big Data from Space (BiDS’2019) (pp. 41-44). EUR 29660 EN, Publications Office of the European Union 5, Luxembourg: P. Soille, S. Loekken, and S. Albani (Eds.). (DOI)