Problema e strumenti

Il presente tutorial ha l'obiettivo di proporre soluzioni e spunti in caso di necessità di sviluppo di procedure territoriali sperimentali su commessa.

Cominciamo intanto dalla scelta degli strumenti e consideriamo di voler risolvere il problema richiesto in ambiente GRASS GIS usando Python come linguaggio di scripting per legare le singole procedure.

Non è da sottovalutare, a questo punto, anche lo strumento per la documentazione delle procedure e dei risultati ottenuti, per il quale potremmo pensare di adottare una soluzione molto evoluta come JupyterLab oggi molto in uso in abito accademico e di ricerca. In questo modo sarà possibile commentare il codice con strumenti di editing testuale di alto livello che prevedano una divisione degli argomenti in sezioni e capitoli a una integrazione del testo con grafici dinamici e allegati multimediali.

Un altro problema di cui preoccuparsi, a questo punto, è poter condividere, alla fine del nostro lavoro, non solo le procedure implementate e la loro documentazione, ma anche un ambiente adeguato e pienamente compatibile con il codice. In questo caso si può pensare di appoggiarsi ad una soluzione basata su Docker che ci aiuti a tenere traccia delle diverse dipendenze adottate, siano esse librerie python native o dipendenze di sistema come installazioni di software di terze parti dotate di adeguate API cui intendiamo appoggiarsi come può essere GRASS GIS nel nostro caso.

Pronti? via!

Se pensi di riconoscerti nel caso d'uso e nelle problematiche descritte fino a questo momento in questo capitolo troverai come scaricare e provare la soluzione proposta.

Requisiti

Attenzione in quanto segue vengono dati come assodati concetti di base relativamente all'uso di Docker e di Docker-compose ed alla loro installazione necessaria a proseguire il tutorial.

I comandi di seguito elencati sono pensati per un terminale di sistema GNU/Linux ma con pochi adattamenti il sistema può essere avviato su ogni piattaforma supportata da Docker.

Installazione

1. Scarica il progetto

    git clone https://gist.github.com/e56fe90399c44e02e7cb97d5ef95edbd.git jupyter-grass
    cd jupyter-grass
   

   N.B.: I prossimi comandi vanno lanciati dall'interno della cartella del progetto appena scaricato.

2. Crea una directory di lavoro per Jupyter Lab interna al progetto appena clonato

    mkdir notebook-home
   

   N.B.: La cartella notebook-home viene ignorata dal versionamento del progetto.

3. Crea il tuo container di lavoro

    docker-compose build --build-arg user="${USER}" --build-arg uid="${UID}"
   

4. Lancia il tuo ambiente di sviluppo

    docker-compose up
   

A questo punto il terminale indicherà i link di accesso all'ambiente Jupyter Lab come segue:

...
JupyterGrass     | [I 2022-10-21 09:51:09.548 ServerApp] Jupyter Server 1.21.0 is running at:
JupyterGrass     | [I 2022-10-21 09:51:09.548 ServerApp] http://localhost:8888/lab?token=12476cf1c5cd87cf0b7c3016895aa0c8962c250b5aaa9946
JupyterGrass     | [I 2022-10-21 09:51:09.548 ServerApp]  or http://127.0.0.1:8888/lab?token=12476cf1c5cd87cf0b7c3016895aa0c8962c250b5aaa9946
JupyterGrass     | [I 2022-10-21 09:51:09.548 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
JupyterGrass     | [C 2022-10-21 09:51:09.552 ServerApp]
JupyterGrass     |     
JupyterGrass     |     To access the server, open this file in a browser:
JupyterGrass     |         file:///home/manuele/.local/share/jupyter/runtime/jpserver-7-open.html
JupyterGrass     |     Or copy and paste one of these URLs:
JupyterGrass     |         http://localhost:8888/lab?token=12476cf1c5cd87cf0b7c3016895aa0c8962c250b5aaa9946
JupyterGrass     |      or http://127.0.0.1:8888/lab?token=12476cf1c5cd87cf0b7c3016895aa0c8962c250b5aaa9946
...

Jupyter Lab verrà esposto sulla porta locale 8888 e l'accesso senza autenticazione sarà possibile grazie al token indicato che sarà diverso ad ogni avvio.

Hello World

È possibile usare il seguente codice come test del sistema e come esempio di gestione delle sessioni GRASS GIS e spunto di inizio delle vostre procedure custom.

from packaging import version
from grass_session import version as grass_session_version

if version.parse(grass_session_version) < version.parse("0.5"):
    session_default_opts = {}
else:
    session_default_opts = {'loadlibs': True}

from grass_session import Session
import grass.script as gs

with Session(gisdb='./', location='newLocation5', create_opts="EPSG:4326", **session_default_opts):
    # Example code adapted from: https://neteler.gitlab.io/grass-gis-analysis/05_grass_gis_python_session/
    # import admin0 vector data - it downloads and imports including topological cleaning on the fly
    #   Data source: https://www.naturalearthdata.com/downloads/10m-cultural-vectors/
    #   VSI driver for remote access: http://www.gdal.org/gdal_virtual_file_systems.html#gdal_virtual_file_systems_vsicurl
    inputfile = "/vsizip/vsicurl/https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/ne_10m_admin_0_countries.zip"

    # note the pythonic underscore (we could also use v.import)
    gs.run_command('v.in.ogr', input=inputfile, output="countries", overwrite = True)

È possibile ora accedere con una nostra installazione locale di GRASS GIS alle sessioni create e usate dalle nostre procedure implementate con Jupyter Lab visto che di default sono salvate all'interno del volume condiviso nel quale troveremo anche i Notebook.