Part 2. Introduction to Actinia

Learn how to use actinia to create a cloud-based processing environment for GRASS GIS.
geospatial
GRASS v8.5
jupyter
lidar
STAC
Authors

Corey T. White

Vaclav Petras

Published

September 10, 2024

!figlet "actinia 101"
            _   _       _         _  ___  _ 
  __ _  ___| |_(_)_ __ (_) __ _  / |/ _ \/ |
 / _` |/ __| __| | '_ \| |/ _` | | | | | | |
| (_| | (__| |_| | | | | | (_| | | | |_| | |
 \__,_|\___|\__|_|_| |_|_|\__,_| |_|\___/|_|

A REST API for GRASS GIS

  • GRASS GIS is a Geospatial Processing Engine
  • Open Source (GPL v2)
  • Developed by International and Multi-institutional groups and individuals (GRASS Development Team)
  • Member of the Open Source Geospatial Foundatispace
  • Recieved Open Source Security Foundation (OpenSSF) Best Practices Badge - 2024

flowchart LR
  A[Client] -->|Http Request| B[Actinia REST API]
  B <--> D[GRASS GIS Processing Node]
  B -->|Http Response| A

Import Python Libraries

import os
import subprocess
from pprint import pprint
import sys
import json
import time

import requests
from requests.auth import HTTPBasicAuth

Setup Environment

Deploy Docker container with Actinia

Follow Instructions at : https://github.com/OpenPlainsInc/foss4gna-2024-workshop

Setup Variables

ACTINIA_USER = 'actinia-gdi'
ACTINIA_PASSWORD = 'actinia-gdi'
AUTH = 'actinia-gdi:actinia-gdi'
ACTINIA_URL = 'http://localhost:8088'
# ACTINIA_URL = 'https://openplains.app/actinia'
ACTINIA_VERSION = 'v3'
ACTINIA_BASEURL = 'http://localhost:8088'
# ACTINIA_BASEURL = 'https://openplains.app/actinia'
ACTINIA_URL = ACTINIA_BASEURL + "/api/" + ACTINIA_VERSION
ACTINIA_AUTH = HTTPBasicAuth(ACTINIA_USER, ACTINIA_PASSWORD)
def print_as_json(data):
    print(json.dumps(data, indent=2))

actinia REST API

actinia Docker Image

Tools

Acinia Basics

url = f"{ACTINIA_URL}/version"
response = requests.get( url)
# pprint(response.json())
print_as_json(response.json().get('version'))
"4.14.1"

User Roles

  1. Superadmin
    • Create, modify and delete users
    • Read/write access to all databases
    • Can access all API calls
  2. Admin
    • All API Calls
    • Create, modify and delete users with the maximum user-role user of the same user grou
    • Access to persistent databases that were granted by a superadmin
  3. User
    • Can run computational tasks in ephemeral and user specific databases
    • Create, modify and delete locations in a user specific database
    • Create, modify and delete mapsets in user specific databases
    • Limited access to API calls
    • Has limited access to persistent databases
  4. Guest
    • Has very limited access to API calls
    • Limited access to persistent databases

https://actinia-org.github.io/actinia-core/actinia_concepts/

GRASS Projects

Let’s start by requesting a list of GRASS projects from actinia.

flowchart LR
  A["/api/v3/locations"]


url = f"{ACTINIA_URL}/locations"

response = requests.get( url, auth=ACTINIA_AUTH)

pprint(response.json().get('locations'))
['foss4g2024', 'nc_spm_08_grass7', 'nc_spm_08']

Now we will get extra information about a specific project.

flowchart LR
  A["/api/v3/locations/"]
  A --- C["{location_id}"]
  C --- D["/info"]


location_id = 'nc_spm_08_grass7'
url = f"{ACTINIA_URL}/locations/{location_id}/info"

response = requests.get( url, auth=ACTINIA_AUTH)

pprint(response.json().get('process_results'))
{'projection': 'PROJCRS["NAD83(HARN) / North '
               'Carolina",BASEGEOGCRS["NAD83(HARN)",DATUM["NAD83 (High '
               'Accuracy Reference Network)",ELLIPSOID["GRS '
               '1980",6378137,298.257222101,LENGTHUNIT["metre",1]]],PRIMEM["Greenwich",0,ANGLEUNIT["degree",0.0174532925199433]],ID["EPSG",4152]],CONVERSION["SPCS83 '
               'North Carolina zone (meter)",METHOD["Lambert Conic Conformal '
               '(2SP)",ID["EPSG",9802]],PARAMETER["Latitude of false '
               'origin",33.75,ANGLEUNIT["degree",0.0174532925199433],ID["EPSG",8821]],PARAMETER["Longitude '
               'of false '
               'origin",-79,ANGLEUNIT["degree",0.0174532925199433],ID["EPSG",8822]],PARAMETER["Latitude '
               'of 1st standard '
               'parallel",36.1666666666667,ANGLEUNIT["degree",0.0174532925199433],ID["EPSG",8823]],PARAMETER["Latitude '
               'of 2nd standard '
               'parallel",34.3333333333333,ANGLEUNIT["degree",0.0174532925199433],ID["EPSG",8824]],PARAMETER["Easting '
               'at false '
               'origin",609601.22,LENGTHUNIT["metre",1],ID["EPSG",8826]],PARAMETER["Northing '
               'at false '
               'origin",0,LENGTHUNIT["metre",1],ID["EPSG",8827]]],CS[Cartesian,2],AXIS["easting '
               '(X)",east,ORDER[1],LENGTHUNIT["metre",1]],AXIS["northing '
               '(Y)",north,ORDER[2],LENGTHUNIT["metre",1]],USAGE[SCOPE["Engineering '
               'survey, topographic mapping."],AREA["United States (USA) - '
               'North Carolina - counties of Alamance; Alexander; Alleghany; '
               'Anson; Ashe; Avery; Beaufort; Bertie; Bladen; Brunswick; '
               'Buncombe; Burke; Cabarrus; Caldwell; Camden; Carteret; '
               'Caswell; Catawba; Chatham; Cherokee; Chowan; Clay; Cleveland; '
               'Columbus; Craven; Cumberland; Currituck; Dare; Davidson; '
               'Davie; Duplin; Durham; Edgecombe; Forsyth; Franklin; Gaston; '
               'Gates; Graham; Granville; Greene; Guilford; Halifax; Harnett; '
               'Haywood; Henderson; Hertford; Hoke; Hyde; Iredell; Jackson; '
               'Johnston; Jones; Lee; Lenoir; Lincoln; Macon; Madison; Martin; '
               'McDowell; Mecklenburg; Mitchell; Montgomery; Moore; Nash; New '
               'Hanover; Northampton; Onslow; Orange; Pamlico; Pasquotank; '
               'Pender; Perquimans; Person; Pitt; Polk; Randolph; Richmond; '
               'Robeson; Rockingham; Rowan; Rutherford; Sampson; Scotland; '
               'Stanly; Stokes; Surry; Swain; Transylvania; Tyrrell; Union; '
               'Vance; Wake; Warren; Washington; Watauga; Wayne; Wilkes; '
               'Wilson; Yadkin; '
               'Yancey."],BBOX[33.83,-84.33,36.59,-75.38]],ID["EPSG",3358]]\n',
 'region': {'b': 0.0,
            'cells': 29535,
            'cells3': 29535,
            'cols': 179,
            'cols3': 179,
            'depths': 1,
            'e': 639530.0,
            'ewres': 10.0,
            'ewres3': 10.0,
            'n': 221230.0,
            'nsres': 10.0,
            'nsres3': 10.0,
            'projection': 99,
            'rows': 165,
            'rows3': 165,
            's': 219580.0,
            't': 1.0,
            'tbres': 1.0,
            'w': 637740.0,
            'zone': 0}}

Mapsets

We will now get a list of mapsets for a specific project.

flowchart LR
  A["/api/v3/locations/"]
  A --- B("{location_id}")
  B --- C["/mapsets"]


# mapset = 'nc_spm_08'
location_id = 'nc_spm_08_grass7'
url = f"{ACTINIA_URL}/locations/{location_id}/mapsets"

response = requests.get( url, auth=ACTINIA_AUTH)

pprint(response.json().get('process_results'))
['PERMANENT']

Now let’s get extra information about a specific mapset PERMANENT.

flowchart LR
  A["/api/v3/locations/"]
  A --- B("{location_id}")
  B --- C["/mapsets/"]
  C --- D("{mapset_id}")
  D --- E["/info"]


mapset_id = 'PERMANENT'
location_id = 'nc_spm_08_grass7'
url = f"{ACTINIA_URL}/locations/{location_id}/mapsets/{mapset_id}/info"

response = requests.get( url, auth=ACTINIA_AUTH)

pprint(response.json().get('process_results'))
{'projection': 'PROJCRS["NAD83(HARN) / North '
               'Carolina",BASEGEOGCRS["NAD83(HARN)",DATUM["NAD83 (High '
               'Accuracy Reference Network)",ELLIPSOID["GRS '
               '1980",6378137,298.257222101,LENGTHUNIT["metre",1]]],PRIMEM["Greenwich",0,ANGLEUNIT["degree",0.0174532925199433]],ID["EPSG",4152]],CONVERSION["SPCS83 '
               'North Carolina zone (meter)",METHOD["Lambert Conic Conformal '
               '(2SP)",ID["EPSG",9802]],PARAMETER["Latitude of false '
               'origin",33.75,ANGLEUNIT["degree",0.0174532925199433],ID["EPSG",8821]],PARAMETER["Longitude '
               'of false '
               'origin",-79,ANGLEUNIT["degree",0.0174532925199433],ID["EPSG",8822]],PARAMETER["Latitude '
               'of 1st standard '
               'parallel",36.1666666666667,ANGLEUNIT["degree",0.0174532925199433],ID["EPSG",8823]],PARAMETER["Latitude '
               'of 2nd standard '
               'parallel",34.3333333333333,ANGLEUNIT["degree",0.0174532925199433],ID["EPSG",8824]],PARAMETER["Easting '
               'at false '
               'origin",609601.22,LENGTHUNIT["metre",1],ID["EPSG",8826]],PARAMETER["Northing '
               'at false '
               'origin",0,LENGTHUNIT["metre",1],ID["EPSG",8827]]],CS[Cartesian,2],AXIS["easting '
               '(X)",east,ORDER[1],LENGTHUNIT["metre",1]],AXIS["northing '
               '(Y)",north,ORDER[2],LENGTHUNIT["metre",1]],USAGE[SCOPE["Engineering '
               'survey, topographic mapping."],AREA["United States (USA) - '
               'North Carolina - counties of Alamance; Alexander; Alleghany; '
               'Anson; Ashe; Avery; Beaufort; Bertie; Bladen; Brunswick; '
               'Buncombe; Burke; Cabarrus; Caldwell; Camden; Carteret; '
               'Caswell; Catawba; Chatham; Cherokee; Chowan; Clay; Cleveland; '
               'Columbus; Craven; Cumberland; Currituck; Dare; Davidson; '
               'Davie; Duplin; Durham; Edgecombe; Forsyth; Franklin; Gaston; '
               'Gates; Graham; Granville; Greene; Guilford; Halifax; Harnett; '
               'Haywood; Henderson; Hertford; Hoke; Hyde; Iredell; Jackson; '
               'Johnston; Jones; Lee; Lenoir; Lincoln; Macon; Madison; Martin; '
               'McDowell; Mecklenburg; Mitchell; Montgomery; Moore; Nash; New '
               'Hanover; Northampton; Onslow; Orange; Pamlico; Pasquotank; '
               'Pender; Perquimans; Person; Pitt; Polk; Randolph; Richmond; '
               'Robeson; Rockingham; Rowan; Rutherford; Sampson; Scotland; '
               'Stanly; Stokes; Surry; Swain; Transylvania; Tyrrell; Union; '
               'Vance; Wake; Warren; Washington; Watauga; Wayne; Wilkes; '
               'Wilson; Yadkin; '
               'Yancey."],BBOX[33.83,-84.33,36.59,-75.38]],ID["EPSG",3358]]\n',
 'region': {'b': 0.0,
            'cells': 29535,
            'cells3': 29535,
            'cols': 179,
            'cols3': 179,
            'depths': 1,
            'e': 639530.0,
            'ewres': 10.0,
            'ewres3': 10.0,
            'n': 221230.0,
            'nsres': 10.0,
            'nsres3': 10.0,
            'projection': 99,
            'rows': 165,
            'rows3': 165,
            's': 219580.0,
            't': 1.0,
            'tbres': 1.0,
            'w': 637740.0,
            'zone': 0}}

Layers

Raster Layers

Let’s see all of the mapsets raster layers.

flowchart LR
  A["/api/v3/locations/"]
  A --- B("{location_id}")
  B --- C["/mapsets/"]
  C --- D("{mapset_id}")
  D --- E["/raster_layers"]


mapset_id = 'PERMANENT'
location_id = 'nc_spm_08_grass7'
url = f"{ACTINIA_URL}/locations/{location_id}/mapsets/{mapset_id}/raster_layers"

response = requests.get( url, auth=ACTINIA_AUTH)

pprint(response.json().get('process_results'))
['aspect',
 'basin_50K',
 'boundary_county_500m',
 'cfactorbare_1m',
 'cfactorgrow_1m',
 'el_D782_6m',
 'el_D783_6m',
 'el_D792_6m',
 'el_D793_6m',
 'elev_lid792_1m',
 'elev_ned_30m',
 'elev_srtm_30m',
 'elev_state_500m',
 'elevation',
 'elevation_shade',
 'facility',
 'geology_30m',
 'lakes',
 'landclass96',
 'landcover_1m',
 'landuse96_28m',
 'lsat7_2002_10',
 'lsat7_2002_20',
 'lsat7_2002_30',
 'lsat7_2002_40',
 'lsat7_2002_50',
 'lsat7_2002_61',
 'lsat7_2002_62',
 'lsat7_2002_70',
 'lsat7_2002_80',
 'ncmask_500m',
 'ortho_2001_t792_1m',
 'roadsmajor',
 'slope',
 'soilsID',
 'soils_Kfactor',
 'streams_derived',
 'towns',
 'urban',
 'zipcodes',
 'zipcodes_dbl']

Vector Layers

flowchart LR
  A["/api/v3/locations/"]
  A --- B("{location_id}")
  B --- C["/mapsets/"]
  C --- D("{mapset_id}")
  D --- E["/vector_layers"]


mapset_id = 'PERMANENT'
location_id = 'nc_spm_08_grass7'
url = f"{ACTINIA_URL}/locations/{location_id}/mapsets/{mapset_id}/vector_layers"

payload = {}
headers = {}

response = requests.get( url, auth=ACTINIA_AUTH, headers=headers)

pprint(response.json().get('process_results'))
['P079214',
 'P079215',
 'P079218',
 'P079219',
 'boundary_county',
 'boundary_municp',
 'bridges',
 'busroute1',
 'busroute11',
 'busroute6',
 'busroute_a',
 'busroutesall',
 'busstopsall',
 'census_wake2000',
 'censusblk_swwake',
 'comm_colleges',
 'elev_lid792_bepts',
 'elev_lid792_cont1m',
 'elev_lid792_randpts',
 'elev_lidrural_mrpts',
 'elev_lidrural_mrptsft',
 'elev_ned10m_cont10m',
 'firestations',
 'geodetic_pts',
 'geodetic_swwake_pts',
 'geology',
 'geonames_NC',
 'geonames_wake',
 'hospitals',
 'lakes',
 'nc_state',
 'overpasses',
 'poi_names_wake',
 'precip_30ynormals',
 'precip_30ynormals_3d',
 'railroads',
 'roadsmajor',
 'schools_wake',
 'soils_general',
 'soils_wake',
 'streams',
 'streets_wake',
 'swwake_10m',
 'urbanarea',
 'usgsgages',
 'zipcodes_wake']

Processing

Syncronous Processing

Emphemeral process

flowchart LR
  A["/api/v3/locations/"]
  A --- B("{location_id}")
  B --- C["/mapsets/"]
  C --- D("{mapset_id}")
  D --- E["/processing"]


mapset_id = 'PERMANENT'
location_id = 'nc_spm_08_grass7'
url = f"{ACTINIA_URL}/locations/{location_id}/mapsets/{mapset_id}/processing"

data = {}

response = requests.post( url, auth=ACTINIA_AUTH, json=data)

pprint(response.json().get('process_results'))
None

Asyncronous Processing

flowchart LR
  A["/api/v3/locations/"]
  A --- B("{location_id}")
  B --- C["/mapsets/"]
  C --- D("{mapset_id}")
  D --- E["/processing_async"]


mapset_id = 'PERMANENT'
location_id = 'nc_spm_08_grass7'
url = f"{ACTINIA_URL}/locations/{location_id}/mapsets/{mapset_id}/processing_async"

data = {}

response = requests.post( url, auth=ACTINIA_AUTH, json=data)

pprint(response.json().get('process_results'))
{}

Let’s look at the complete API within PostMan or Insomnia.

https://localhost:8080/api/v3/swagger-ui/index.html

Process Chains

Let move on to creating process chains in Part 3.