Skip to content

Home

Jump to bottom
Markus Neteler edited this page Sep 9, 2024 · 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 illustration of 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 might be a better approach because of interchangeability.
    • benefit for the user is to use a standard API:
      • 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.

Q: What makes actinia unique?

Answer: actinia 's uniqueness lies in its cloud-based, open source REST API that enables scalable and distributed high performance processing of geospatial data. Its integration with GRASS GIS and GDAL for computational tasks and its ability to process a wide range of geospatial data, including satellite imagery and time series, sets it apart. Its modular design with plug-ins for various functionalities such as metadata catalogue management and parallelization further enhances its advantages.

Q: Why should a person choose actinia over its competitors?

Answer: A person should choose actinia for its:

  • High scalability and performance in cloud environments.
  • Open source nature, providing flexibility and community support.
  • Advanced geospatial processing capabilities, including satellite image processing and time series analysis.
  • Modular architecture that allows for customised deployments.
  • Integration capabilities with Jupyter Notebooks and Hub for ease of use in data science workflows.

Q: How would you describe your primary audience?

Answer: The primary audience for actinia includes

  • Companies, organisations and institutions requiring advanced geospatial processing capabilities in cloud environments.
  • Professionals working with satellite imagery and geospatial data.
  • Geospatial and Earth observation analysts and scientists.
  • Developers and engineers looking for a scalable, cloud-based geospatial processing platform.

Q: What is the story behind actinia?

Answer: The story behind actinia revolves around the need for a scalable, efficient, and flexible platform for processing complex geospatial data in the cloud. Originally developed by Sören Gebbert and mundialis (Germany) in 2017 in the wake of high-quality data from the Copernicus program, it has since evolved into a tool that also addresses data offerings from New Space satellite sensors. Actinia aims to harness the power of cloud computing and open source software to bring advanced geospatial processing capabilities to a wide range of users. It is a community project of the Open Source Geospatial Foundation (OSGeo.org).

Q: Which are the primary technologies used for building actinia?

Answer: The primary technologies used in building actinia include:

  • actinia is written in Python.
  • actinia uses mainly GRASS GIS and GDAL for geospatial data processing.
  • for deployment, cloud computing technologies are used for scalability and distributed processing.
  • REST API for easy integration and accessibility.
  • various actinia plugins for extended functionalities like OGC-CSW, STAC support, and parallel processing techniques.

Q: Who are some of the biggest customers of actinia?

Answer: While specific customer names are not provided, actinia 's biggest customers are:

  • Large corporations in sectors like telecommunication, supply chain management, urban planning, and environmental management that rely on geospatial data.
  • Tech companies and startups needing a robust, scalable platform for geospatial data processing in their products or services.
  • International, governmental and environmental agencies requiring advanced geospatial data analysis.
  • Research institutions and universities engaged in geographical and environmental studies.

actinia presentations and workshops

2024:

  • Blumentrath, S., Are Antonsen, Y., Widforss, A., Fossli Gjersø, N., Verpe Engeset, R., and Havstad Winsvold, S. (2024): Implementing National Copernicus services for hydrology and natural hazard monitoring at NVE using Open Source tools Apache Airflow and actinia, EGU General Assembly 2024, Vienna, Austria, 14–19 Apr 2024, EGU24-19421, https://doi.org/10.5194/egusphere-egu24-19421.

2023:

  • Implementing Copernicus services at the (NVE) with Airflow and actinia. Blumentrath, S., FOSS4G Prizren Kosovo 2023. 10.5446/66441 (DOI)
  • Neues von actinia (presentation), Tawalika, C. FOSSGIS 2023, Berlin, Germany. Slides (use Chromium/Chrome browser)
  • Oberflächenklassifikation aus Luft- und Satellitenbildern mit Hilfe von actinia (Workshop). FOSSGIS 2023, Berlin, Germany (abstract | Jupyter notebook)
  • Einführung in actinia (Workshop). FOSSGIS 2023, Berlin, Germany (Jupyter notebook)

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.), https://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