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

Nota

Questo progetto è incluso solo nel disco della macchina virtuale (VMDK) OSGeoLive

Guida rapida actinia

Actinia è un’API REST open source per l’elaborazione scalabile, distribuita e ad alte prestazioni di dati geografici che utilizza principalmente GRASS GIS per compiti di calcolo. Actinia fornisce un’API REST per elaborare immagini satellitari, serie temporali di immagini satellitari, dati raster e vettoriali.

L’attinia può essere usata in diversi modi:

  • curl o strumenti simili a riga di comando

  • attraverso Jupyter notebooks

  • l” interfaccia Python

  • le estensioni per browser Postman o RESTman

  • apri una sessione di GRASS GIS e usa lo strumento ace (actinia command execution)

  • altre interfacce per API REST

In questa guida rapida, utilizziamo GRASS GIS per lanciare comodamente i comandi dalla sessione al server actinia (che a sua volta utilizza GRASS GIS). L’idea è quella di sviluppare rapidamente un flusso di lavoro a livello locale su piccole serie di dati per poi eseguirlo sul server.

Usare actinia con un Jupyter notebook

Numerosi Jupyter notebooks per actinia sono disponibili https://github.com/actinia-org/actinia-jupyter

Introduzione a ace - esecuzione del comando actinia

Lo strumento ace (dettagli) permette l’esecuzione di un singolo comando GRASS GIS o di una lista di comandi GRASS GIS su un servizio REST actinia (https://actinia.mundialis.de/). Inoltre fornisce la gestione del lavoro, la possibilità di elencare le località, i set di mappe e i layer di mappe a cui l’utente ha accesso, nonché la creazione e la cancellazione dei set di mappe.

Lo strumento ace deve essere eseguito in una sessione attiva di GRASS GIS. È installato con g.extension extension=ace url=https://github.com/actinia-org/ace.

Tutti i comandi saranno eseguiti in maniera predefinita in un database effimero. Quindi, il risultato deve essere esportato utilizzando i comandi aumentati di GRASS.

L’opzione mapset=MAPSET_NAME permette l’esecuzione di comandi nel database utente persistente. Può essere usata con l’opzione location=LOCATION_NAME.

Imposta il tuo ambiente

Assicurati di eseguire i seguenti comandi in una sessione di GRASS GIS.

L’utente deve impostare le seguenti variabili ambientali per specificare il server actinia e le credenziali:

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

Accesso ai dati campione

Gli insiemi di dati selezionati sono disponibili per l’utente demo. Per elencare le posizioni a cui si ha accesso, eseguire

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

Il seguente comando elenca i set di mappe della posizione corrente nella sessione attiva di 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']

Accesso ai dati da fonti esterne

I comandi di GRASS GIS possono essere aumentati con estensioni specifiche di actinia. L’operatore @ può essere specificato per un parametro in ingresso per importare una risorsa situata sul web e per specificare l’esportazione di un parametro in uscita.

È importante che il nome della posizione locale e del mapset corrisponda a quello del server REST di actinia.

I set di dati attualmente disponibili sono (organizzati per proiezioni):

Ispeziona la chiamata REST prima della sottomissione

Per generare la richiesta JSON della catena di processo di actinia è sufficiente aggiungere il flag -d (dry-run):

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

Visualizza una mappa - rendering della mappa

È molto facile (e veloce) visualizzare una mappa:

# 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"
Mappa ESA Globcover mostrata da actinia

Mappa ESA Globcover mostrata da actinia

L’elaborazione effimera è l’approccio predefinito di elaborazione di actinia. I comandi vengono eseguiti in un mapset effimero che verrà rimosso dopo l’elaborazione. È possibile esportare l’output dei moduli GIS di GRASS per memorizzare il risultato del calcolo per il download e ulteriori analisi. Attualmente sono supportati i seguenti formati di esportazione:

  • raster: COG, GTiff

  • vettore: GPKG, GML, GeoJSON, ESRI_Shapefile

  • tabelle: CSV, TXT

Script di esempio

Esempio 1: calcolare la pendenza e l’aspetto e le statistiche univariate da un modello di elevazione

I seguenti comandi (da memorizzare in uno script ed eseguire con ace) importano un layer raster da una fonte internet come mappa raster elev, impostano la regione di calcolo sulla mappa e calcolano la pendenza. Ulteriori informazioni sul layer sono richieste con r.info.

Memorizza il seguente script come file di testo 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

Salava lo script nel file di testo in /tmp/ace_dtm_statistics.sh ed esegui lo script salvato come

ace --location nc_spm_08 --script ace_dtm_statistics.sh

I risultati (messaggi, statistiche, file) sono forniti come risorse REST.

Per generare la richiesta JSON della catena di processo di actinia è sufficiente aggiungere il flag -d (dry-run):

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

L’output dovrebbe essere simile a questo:

{
  "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"
        }
      ]
    }
  ]
}

Esempio 2: Segmentazione dell’immagine ortofoto con esportazione

Memorizza il seguente script come file di testo /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

Esegui lo script salvato in un file di testo come

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

I risultati (messaggi, statistiche, file) sono forniti come risorse REST.

Esempi di elaborazione persistente

I comandi di GRASS GIS possono essere eseguiti in un database persistente specifico dell’utente. L’utente deve creare un mapset in una posizione esistente. Si può accedere a questo mapset tramite ace. Tutti i risultati dell’elaborazione dei comandi eseguiti in questo mapset saranno memorizzati in modo persistente. Siate consapevoli che l’elaborazione verrà eseguita in un database effimero che verrà spostato nella memoria persistente usando il nome corretto dopo l’elaborazione.

Per creare un nuovo mapset nella posizione nc_spm_08 con il nome test_mapset deve essere eseguito il seguente comando

ace location="nc_spm_08" create_mapset="test_mapset"

Esegui i comandi dello script statistico nel nuovo mapset persistente

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

Mostra tutte le mappe raster che sono state create con lo script in test_mapset

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

Mostra informazioni sulla mappa raster elev e 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"

Cancella il test_mapset (controlla sempre due volte i nomi quando si cancella)

ace location="nc_spm_08" delete_mapset="test_mapset"

Se la sessione attiva di GRASS GIS ha nomi di località/mappe identici, allora si può usare un alias per evitare l’opzione persistente in ogni singola chiamata di comando:

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

Assumi che nella sessione attiva di GRASS GIS la località corrente sia nc_spm_08 e il mapset corrente sia test_mapset. Allora i comandi di cui sopra possono essere eseguiti nel modo seguente:

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"

Cose da provare

Installazione su una macchina virtuale OSGeoLive con Docker Compose

Requisiti: docker e docker-compose (già disponibili nella versione OSGeoLive VM)

Per compilare ed utilizzare actinia, eseguire

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

Ora avete un’istanza di Actinia funzionante in locale! Controllare con

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

Crea nuove location

# (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"

Installa GRASS GIS addons (estensioni)

# (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\""

E ora?

  • Visita il sito web di actinia: https://actinia.mundialis.de

  • actinia tutorial: https://neteler.gitlab.io/actinia-introduction

  • Ulteriori letture: 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)