Skip to content

Home

Jump to bottom
Markus Neteler edited this page Oct 13, 2023 · 51 revisions

Actinia - The GRASS GIS REST API

Actinia is an open source REST API for scalable, distributed, high performance processing of geographical data that mainly uses GRASS GIS for computational tasks.

It provides a REST API to e.g. process satellite images, time series of satellite images, arbitrary raster data with geographical relations and vector data.

The REST interface allows to access, manage and manipulate the GRASS GIS database via HTTP GET,PUT,POST and DELETE requests and to process raster, vector and time series data located in a persistent GRASS GIS database. Actinia allows the processing of cloud based data, for example all Landsat 4-8 scenes as well as all Sentinel-2 scenes in an ephemeral databases. The computational results of ephemeral processing are available via object storage as GeoTIFF files.

What does actinia mean?

Actinia is a beautiful sea creature and a genus of sea anemones in the family Actiniidae (see https://en.wikipedia.org/wiki/Actinia). While the sea creature is filtering the sea water, the actinia geoprocessing platform filters in large data oceans.

Tutorials

a) Actinia Documentation, Tutorial and Examples: Actinia - The GRASS GIS REST API, https://actinia.mundialis.de/tutorial/index.html

b) "A gentle introduction to actinia", https://neteler.gitlab.io/actinia-introduction/ (author: Markus Neteler, mundialis GmbH & Co. KG, Bonn):

  • This workshop introduces actinia and has a more detailed chapter about ace - the actinia command execution.

c) "A gentle introduction to actinia", https://mmacata.github.io/actinia-introduction/ (authors: Markus Neteler, Carmen Tawalika, Anika Weinmann, Guido Riembauer, mundialis GmbH & Co. KG, Bonn):

d) Jupyter Notebook to explore basic API calls: https://github.com/acoiman/actinia_jupyter (authors: Abraham Coiman)

How to contribute

Please see CONTRIBUTING.md

Actinia REST API documentation

Actinia is fully documented using the OpenAPI standard [1], better known as swagger [2]. The full API documentation is available on the mundialis testing environment here: API Docs.

The JSON definition of the API can be accessed here.
A more interactive API documentation generated with Redoc [3] from the OpenAPI definitions can be viewed here.
Also, the petstore swagger UI creator [4] can be used to show all available REST API calls and all response models in a convenient way.

For the releases and changelog, see https://github.com/actinia-org/actinia-core/releases

Actinia and GRASS GIS Addons

In general, all GRASS GIS modules and addons (official and self-developed) can be used in actinia. Some certain modules provide dedicated functionality for actinia itself:

Actinia and openEO

Compared to the OpenEO API actinia targets a broader range of applications as it includes the entire range of GRASS GIS functionality and more which isn't reflected in the openEO API. The openEO API in turn is generic and not tied to a specific GIS processing software stack. Instead, the openEO API intends to provide a common user interface to various different backends (data processing engines). As a consequence, the openEO API is focussing on earth-observation data and not GIS/RS processing in general, and it does not specify more specialized functionality, even though individual backends are allowed to add more functionality, as long as the interface conforms to openEO specifications.

Here a short attempt to illustrate some differences:

  • actinia offerings (overview of actinia API):

  • openeo-grassgis-driver offerings

    • openEO compliant functionality for raster, vector, time series processing, and more
    • if the openEO use cases fit and are sufficient (mainly processing and analysis of earth observation data) and if the concept of data cubes fits well to the data to be processed, then using the openEO API would be a better approach because of interchangeability.
    • benefit for the user is to use a standard
      • no research / implementation of multiple proprietary API specifications
      • out-of-the-box usage of multiple backends and various clients
      • a generic openEO python client is available to easily create more complex process graphs
      • a generic openEO web editor is available, providing a graphical user interface to openEO backends
    • benefit for platform operators might be easier error handling for multiple backends / clients although most likely experts of the specific implementations are needed
    • disadvantage for platform operators is that an additional layer is added on top of the actual data processing engine which makes debugging more difficult

Actinia deployment

Docker

Actinia requires a running redis database, which can be easily deployed together with actinia. For a quick and straightforward deployment, navigate to the actinia_core/docker directory and run

docker-compose -f docker-compose.yml build  # you can also specify the desired actinia version in the docker-compose.yml

docker-compose -f docker-compose.yml up 
# or in detached mode:
docker-compose -f docker-compose.yml up -d

For more information see https://github.com/actinia-org/actinia-core/tree/main/docker#readme

helm chart

Actinia can also be installed in kubernetes or openshift via a helm chart: https://github.com/actinia-org/helm-charts/tree/main/charts/actinia

pip

Actinia can also be installed with

pip install actinia-core

from PyPI at https://pypi.org/project/actinia-core/

However, it requires more incl. the installation of a redis server.

For a full installation procedure, see e.g.

https://github.com/OSGeo/OSGeoLive/blob/master/bin/install_actinia.sh

along with the needed configuration file:

https://github.com/OSGeo/OSGeoLive/tree/master/app-conf/actinia

Q&A using actinia

Q: For longer running processes, it would be nice if actinia could send a signal "Done"

Answer: While actinia does not send a signal on finished processing, a webhook can be used. See: https://github.com/actinia-org/actinia-core/blob/main/scripts/webhook-server

See also the related test: https://github.com/actinia-org/actinia-core/blob/main/tests/test_webhook.py

Q: How to manage central, persistent data as superadmin (via API?)

Answer: In general it is not recommended to create the shared data pool via API. By design the persistent DB is not editable via API and often mounted read-only, so that no data loss can occur. There are different options:

  • If it is a basic docker on a server deployment, the data storage might be mounted and data edited directly with GRASS GIS
  • If it is a kubernetes deployment or similar, it is possible to create the data pool with a so-called init container, example can be seen here
  • As mapsets are shared amongst groups, if all users are in the same group, the API can be used to edit the user database.

actinia presentations and workshops

2023:

  • Neues von actinia (presentation), Tawalika, C. FOSSGIS 2023, Berlin, Germany. Slides (use Chromium/Chrome browser)

2022:

  • A gentle introduction to actinia: geoprocessing in the cloud (workshop), Tawalika, C., Neteler, M. FOSS4G 2022, Florence, Italy. Slides (use Chromium/Chrome browser)
  • News from actinia - let's STAC! (presentation), Tawalika, C., Herrera Maldonado, J.A., FOSS4G 2022, Florence, Italy. Slides (use Chromium/Chrome browser)
  • Neues von actinia (presentation), Tawalika, C. FOSSGIS 2022, Marburg, Germany. Online. Slides (use Chromium/Chrome browser)
  • STAC und openEO in der Praxis: Integration in actinia (presentation), Tawalika, C. FOSSGIS 2022, Marburg, Germany. Online. Slides (use Chromium/Chrome browser)

2021:

  • News from actinia (presentation), Tawalika, C. FOSS4G 2021, Buenos Aires, Argentina. Online, video
  • A gentle introduction to actinia: geoprocessing in the cloud (workshop), Tawalika, C. FOSS4G 2021, Buenos Aires, Argentina. Online, material
  • actinia: geoprocessamento nel cloud (workshop in italiano), Neteler, M., supported by Delucchi, L.
    • Corsi GEAM e GFOSS 2020-2021, Italy, March 12, 2021, 2:30-6:30 p.m., online, material, video

2020:

  • Geoprocessing in the cloud with actinia (presentation), Neteler, M.
    • DOI Open Source Geospatial Meeting, USA, October 29, 2020 7:00-8:00 p.m., online
  • actinia: geoprocessing in the cloud (presentation), Neteler, M.
    • FOSDEM 2020 Feb. 2020, video

2019:

  • Die Open Source Geoprozessierungsplattform actinia (presentation). Neteler, M.
    • Neue Perspektiven der Erdbeobachtung, 2. Symposium zur angewandten Satellitenerdbeobachtung, 12.-13. Nov. 2019, Köln, Germany
  • GRASS GIS in the cloud: actinia geoprocessing (presentation). Tawalika, C., Neteler, M.
    • FOSS4G 2019, Aug. 2019, Bucharest, Romania (slides and video)
  • Cloud based processing of geo and Earth observation data (workshop), Neteler, M.
    • GeoSTAT 2019, Sep 2019, Münster, Germany
  • Actinia: Cloud based geoprocessing (presentation). Neteler, M., Gebbert, S., Tawalika, C., Bettge, A., Benelcadi, H., Löw, F., Adams, T., Paulsen, H.
    • Big Data from Space (BiDS'19) - Turning Data into Insights. 19-21 Feb 2019, Munich, Germany (paper

2018:

  • Actinia Open Source – geoprocessing in the cloud (presentation), Adams, T.
    • FOSS4G 2018, Aug. 2018, Dar es Salaam, Tanzania

2017:

  • Processing and spatial analysis of multi-temporal remote sensing data (presentation), M. Neteler, C. Tawalika, T. Adams, H. Paulsen
    • Feld-Phänotypisierung - Merkmale von oben messen, 27. - 29. Juni 2017
  • actinia – API zur Prozessierung von Copernicus-Daten (presentation), T. Adams.
    • GeoIT round table, June 2017

Citing actinia

Overview article

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.), http://doi.org/10.5281/zenodo.2631917

OSGeo community project page

actinia at OSGeo: https://www.osgeo.org/projects/actinia/

actinia server

https://actinia.mundialis.de/

Software citation

DOI

If you use this software, please cite it properly, depending on the version you use:

  • Tawalika, Carmen, Weinmann, Anika, Riembauer, Guido, Metz, Markus, Haas, Julia, Jansen, Marc, Herrera Maldonado, Jorge A., Gebbert, Sören, & Neteler, Markus. (2022). actinia-core (3.0.0). Zenodo. https://doi.org/10.5281/zenodo.5865317
  • Tawalika, Carmen, Weinmann, Anika, Riembauer, Guido, Metz, Markus, Haas, Julia, Jansen, Marc, Gebbert, Sören, & Neteler, Markus. (2021). actinia-core (2.0.0). Zenodo. https://doi.org/10.5281/zenodo.5865265
  • Gebbert, Sören, Tawalika, Carmen, Weinmann, Anika, Riembauer, Guido, Metz, Markus, Jansen, Marc, & Neteler, Markus. (2021). actinia-core (1.0.0). Zenodo. https://doi.org/10.5281/zenodo.5864848

actinia Project Steering Committee (PSC)

The actinia Project Steering Committee (PSC) is the official managing body of actinia and is responsible for setting overall project direction. The committee is drawn from the actinia community and is based on merit and interest.

Contact us!

Links:

[1] https://www.openapis.org/

[2] https://swagger.io

[3] https://redocly.github.io/redoc/

[4] https://petstore.swagger.io

Clone this wiki locally