From 67774719a456272aa8951b4c08c830be098145cd Mon Sep 17 00:00:00 2001 From: Haoyu <80379456+Haoyu-Gao@users.noreply.github.com> Date: Fri, 15 Nov 2024 11:12:25 +1100 Subject: [PATCH 1/2] Update README.md --- README.md | 193 ++++++++++++++---------------------------------------- 1 file changed, 49 insertions(+), 144 deletions(-) diff --git a/README.md b/README.md index e120751e4..da6283b04 100644 --- a/README.md +++ b/README.md @@ -5,177 +5,82 @@ Article [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2631917.svg)](https: [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Docker pulls](https://img.shields.io/docker/pulls/mundialis/actinia-core.svg)](https://hub.docker.com/r/mundialis/actinia-core) -**[Actinia](https://actinia.mundialis.de/)** is an open source REST API for scalable, distributed, high performance -processing of geographical data that mainly uses [GRASS GIS](https://grass.osgeo.org/) for computational tasks. - -It provides a REST API to 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 ephemeral databases. The computational results of ephemeral processing -are available via object storage as GeoTIFF files. - -## API documentation - - - -The full API documentation is available [here](https://redocly.github.io/redoc/?url=https://actinia.mundialis.de/latest/swagger.json&nocors) - -## actinia command execution - actinia shell - -There is also an option to interactively control actinia. For details, -see [here](https://github.com/actinia-org/ace). - -## Installation - -Required system packages: - -- alpine: `apk add python3 py3-pip` - As not all python packages are pre-build for alpine, they need to be build during installation. For this some system packages are required: - `apk add python3 py3-pip python3-dev gcc musl-dev linux-headers build-base gdal gdal-tools gdal-dev proj proj-util proj-dev geos-dev py3-numpy-dev` -- ubuntu: `apt install -y python3 python3-pip` - -And then install from pypi: +## Project Overview +Actinia is an open-source REST API for scalable, distributed, high-performance processing of geographical data that mainly uses GRASS GIS for computational tasks. + +**Key Features:** +- REST API for processing satellite images, time-series data, and vector data. +- Access and manipulate GRASS GIS database via HTTP GET, PUT, POST, and DELETE requests. +- Process cloud-based data, including Landsat 4-8 and Sentinel-2 scenes. +- Output results as GeoTIFF files in object storage. + +**Links:** +- [Software DOI](https://doi.org/10.5281/zenodo.5879231) +- [Article DOI](https://doi.org/10.5281/zenodo.2631917) +- [API Documentation](https://redocly.github.io/redoc/?url=https://actinia.mundialis.de/latest/swagger.json&nocors) + +## Prerequisites +To use Actinia, ensure you have the following installed: +- Alpine Linux: `apk add python3 py3-pip` +- Ubuntu: `apt install -y python3 python3-pip` + +Additional system packages required for Alpine: +``` +apk add python3-dev gcc musl-dev linux-headers build-base gdal gdal-tools gdal-dev proj proj-util proj-dev geos-dev py3-numpy-dev +``` +## Installation Steps +### Option 1: Manual Installation +Install Actinia from PyPI: ```bash pip install actinia-core ``` -## Installation with Docker - -Docker images are available from https://hub.docker.com/r/mundialis/actinia-core - +### Option 2: Using Docker +Pull the Docker image: ```bash docker pull mundialis/actinia-core ``` +For custom deployments or local setups, refer to the `docker/` subfolder. -For own deployments or local dev-setup, see the `docker/` subfolder. +### Verification +To verify a successful installation, check API accessibility via the provided endpoints or the `swagger.json`. -Actinia is also available on [OSGeoLive](https://live.osgeo.org/en/overview/actinia_overview.html). +## API Documentation +The full API documentation is available [here](https://redocly.github.io/redoc/?url=https://actinia.mundialis.de/latest/swagger.json&nocors). ## Examples - -### Data management - -- List all locations that are available in the actinia persistent database: - +### Data Management +List all locations available in the persistent database: ```bash curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/locations" ``` -- List all mapsets in the location latlong_wgs84: - -```bash -curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/locations/latlong_wgs84/mapsets" -``` - -- List all space-time raster datasets (STRDS) in location latlong_wgs84 and mapset Sentinel_timeseries: - -```bash -curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/locations/latlong_wgs84/mapsets/modis_ndvi_global/strds" -``` - -- List all raster map layers of the STRDS: - -```bash -curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/locations/latlong_wgs84/mapsets/modis_ndvi_global/strds/ndvi_16_5600m/raster_layers" -``` - -### Landsat and Sentinel-2 NDVI computation - -- Compute the NDVI of the top of athmosphere (TOAR) corrected Landsat4 scene LC80440342016259LGN00: - -```bash -curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/landsat_process/LC80440342016259LGN00/TOAR/NDVI" -``` - -- NDVI computation of Sentinel-2A scene S2A_MSIL1C_20170212T104141_N0204_R008_T31TGJ_20170212T104138: +For more detailed examples, see the original API documentation. +### Landsat and Sentinel-2 NDVI Computation +Compute NDVI for a specific scene: ```bash -curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/sentinel2_process/ndvi/S2A_MSIL1C_20170212T104141_N0204_R008_T31TGJ_20170212T104138" +curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/landsat_process//TOAR/NDVI" ``` -The results of the asynchronous computations are available as GeoTIFF file in a cloud storage for download. - -### List of available endpoints - -To see a simple **list of endpoints** (and more), consult the "paths" section in the [API JSON](https://actinia.mundialis.de/api/v3/swagger.json); or, to list the available endpoints on command line, run - -```bash -# sudo npm install -g json -curl -u 'demouser:gu3st!pa55w0rd' -X GET https://actinia.mundialis.de/api/v3/swagger.json | json paths | json -ka -``` - -## Development - -### Use pre-commit - -It is highly recommended to install and use [pre-commit](https://pre-commit.com) -before submitting any new or modified code or any other content. The pre-commit -Git hooks set checks validity and executes automated formatting for -a range of file formats, including Python. Pre-commit installs -all necessary tools in a virtual environment upon first use. - -If you never used pre-commit before, you must start by installing it on your -system. You only do it once: - -```bash -python -m pip install pre-commit -``` - -Pre-commit must then be activated in the code repository. Change the directory -to the root folder and use the `install` command: - +### Development +#### Pre-Commit Hooks +Install [pre-commit](https://pre-commit.com) for automated code checks and formatting: ```bash +pip install pre-commit cd - -# once per repo pre-commit install ``` -Pre-commit will then be automatically triggered by the `git commit` command. If -it finds any problem it will abort the commit and try to solve it automatically. -In that case review the changes and run again `git add` and -`git commit`. - -It is also possible to run pre-commit manually, e.g: - -```bash -pre-commit run flake8 --all-files -pre-commit run black --all-files -# pre-commit run yamllint --all-files -# pre-commit run markdownlint --all-files -``` - -Or to target a specific set of files: - -```bash -pre-commit run --files src/* -``` - -The pre-commit hooks set is defined in -[.pre-commit-config.yaml](.pre-commit-config.yaml). - -It is possible to temporally disable the pre-commit hooks in the repo, e.g. while -working on older branches: - -```bash -pre-commit uninstall -``` - -And to reactivate pre-commit again: - +Run hooks manually: ```bash -git switch main -pre-commit install +pre-commit run --all-files ``` -## Thanks to all contributors ❤ +## External Documents +- [OSGeoLive Overview](https://live.osgeo.org/en/overview/actinia_overview.html) +## Contributors +Thanks to all contributors ❤ [![actinia-core contributors](https://contrib.rocks/image?repo=actinia-org/actinia-core "actinia-core contributors")](https://github.com/actinia-org/actinia-core/graphs/contributors) From 062168e5b5b0f525cc634aefdebd1193fe4fd33e Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Sun, 5 Jan 2025 16:12:41 +0100 Subject: [PATCH 2/2] merge some upstream changes back --- README.md | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 9364b11dd..231239553 100644 --- a/README.md +++ b/README.md @@ -7,24 +7,26 @@ Article [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2631917.svg)](https: ## Project Overview -Actinia is an open-source REST API for scalable, distributed, high-performance processing of geographical data that mainly uses GRASS GIS for computational tasks. +[Actinia](https://actinia.mundialis.de/) is an open-source REST API for scalable, distributed, high-performance processing of geographical data that mainly uses [GRASS GIS](https://grass.osgeo.org/) for computational tasks. **Key Features:** -- REST API for processing satellite images, time-series data, and vector data. +- REST API for processing satellite images, raster and vector data, including time-series. - Access and manipulate GRASS GIS database via HTTP GET, PUT, POST, and DELETE requests. -- Process cloud-based data, including Landsat 4-8 and Sentinel-2 scenes. -- Output results as GeoTIFF files in object storage. +- Process cloud-based data, including Landsat 4-9 and Sentinel-2 scenes. +- Output raster data results as GeoTIFF files as resources or in object storage. +- Output vector data results as GeoPackage files as resources or in object storage. **Links:** - [Software DOI](https://doi.org/10.5281/zenodo.5879231) - [Article DOI](https://doi.org/10.5281/zenodo.2631917) - [API Documentation](https://redocly.github.io/redoc/?url=https://actinia.mundialis.de/latest/swagger.json&nocors) +- [Discussion forum](https://github.com/orgs/actinia-org/discussions) ## Prerequisites -To use Actinia, ensure you have the following installed: +To use actinia, ensure you have the following installed: - Alpine Linux: `apk add python3 py3-pip` - Ubuntu: `apt install -y python3 python3-pip` @@ -39,7 +41,7 @@ apk add python3-dev gcc musl-dev linux-headers build-base gdal gdal-tools gdal-d ### Option 1: Manual Installation -Install Actinia from PyPI: +Install actinia from PyPI: ```bash pip install actinia-core @@ -73,13 +75,13 @@ The full API documentation is available [here](https://redocly.github.io/redoc/? curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/projects" ``` -- List all mapsets in the project latlong_wgs84: +- List all mapsets in the project `latlong_wgs84`: ```bash curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/projects/latlong_wgs84/mapsets" ``` -- List all space-time raster datasets (STRDS) in project latlong_wgs84 and mapset Sentinel_timeseries: +- List all space-time raster datasets (STRDS) in project `latlong_wgs84` and mapset `Sentinel_timeseries`: ```bash curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/projects/latlong_wgs84/mapsets/modis_ndvi_global/strds" @@ -93,20 +95,29 @@ curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/pr ### Landsat and Sentinel-2 NDVI computation -- Compute the NDVI of the top of athmosphere (TOAR) corrected Landsat4 scene LC80440342016259LGN00: +- Compute NDVI for a specific Landsat scene: ```bash -curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/landsat_process/LC80440342016259LGN00/TOAR/NDVI" +curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/landsat_process//TOAR/NDVI" +``` + +- Compute NDVI for a specific Sentinel-2A scene: + +```bash +curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/sentinel2_process/ndvi/" ``` -- NDVI computation of Sentinel-2A scene S2A_MSIL1C_20170212T104141_N0204_R008_T31TGJ_20170212T104138: +The results of the asynchronous computations are available as GeoTIFF file in a cloud storage for download. + +### List of available endpoints -### Landsat and Sentinel-2 NDVI Computation +To see a simple **list of endpoints** (and more), consult the "paths" section in the [API JSON](https://actinia.mundialis.de/api/v3/swagger.json). -Compute NDVI for a specific scene: +To list the available endpoints on command line, run ```bash -curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/landsat_process//TOAR/NDVI" +# sudo npm install -g json +curl -u 'demouser:gu3st!pa55w0rd' -X GET https://actinia.mundialis.de/api/v3/swagger.json | json paths | json -ka ``` ### Development @@ -117,6 +128,7 @@ Install [pre-commit](https://pre-commit.com) for automated code checks and forma ```bash pip install pre-commit + cd pre-commit install ``` @@ -129,9 +141,9 @@ pre-commit run --all-files ## External Documents -- [OSGeoLive Overview](https://live.osgeo.org/en/overview/actinia_overview.html) +- actinia is also available on [OSGeoLive](https://live.osgeo.org/en/overview/actinia_overview.html) ## Contributors -Thanks to all contributors ❤ -[![actinia-core contributors](https://contrib.rocks/image?repo=actinia-org/actinia-core "actinia-core contributors")](https://github.com/actinia-org/actinia-core/graphs/contributors) \ No newline at end of file +Thanks to all contributors ❤ +[![actinia-core contributors](https://contrib.rocks/image?repo=actinia-org/actinia-core "actinia-core contributors")](https://github.com/actinia-org/actinia-core/graphs/contributors)