From cd4a7bc7690b789136924b554f463d878aac8955 Mon Sep 17 00:00:00 2001 From: Julia Haas Date: Fri, 28 May 2021 11:21:57 +0200 Subject: [PATCH 1/7] cleaning documentation, removing minor mistakes --- docs/docs/actinia_concepts.md | 49 ++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/docs/actinia_concepts.md b/docs/docs/actinia_concepts.md index 5f680b0dc..b4b4d4dff 100644 --- a/docs/docs/actinia_concepts.md +++ b/docs/docs/actinia_concepts.md @@ -18,7 +18,7 @@ spectacle tool can be used: ```bash # Download the latest swagger definition from the actinia service - wget https://actinia.mundialis.de/api/latest/swagger.json -O /tmp/actinia.json + wget https://actinia.mundialis.de/latest/swagger.json -O /tmp/actinia.json # Run spectacle docker image to generate the HTML documentation docker run -v /tmp:/tmp -t sourcey/spectacle spectacle /tmp/actinia.json -t /tmp @@ -30,30 +30,29 @@ spectacle tool can be used: The petstore swagger UI creator[^3] can be used to show all available REST API calls and all response models in a convenient way. -**Footnotes** User, user-roles and user-groups -------------------------------- -Actinia use the concept of users, user-roles and user-groups to manage +Actinia uses the concept of users, user-roles and user-groups to manage the access to the actinia databases and API calls. A single user has -always a specific user role and can be member of a single user-group. +always a specific user role and can be member of one single user-group. The following user-roles are supported: 1. - superadmin + superadmin: - : - Can create, modify and delete users with all user-roles + - Can create, modify and delete users with all user-roles - Has access to all API calls and read/write access to all databases 2. - admin + admin: - : - Can create, modify and delete locations in a user specific + - Can create, modify and delete locations in a user specific database - Can access all API calls - Can create, modify and delete users with the maximum @@ -63,11 +62,11 @@ The following user-roles are supported: 3. - user + user: - : - Can run computational tasks in ephemeral and user specific + - Can run computational tasks in ephemeral and user specific databases - - Can create create, modify and delete mapsets in user + - Can create, modify and delete mapsets in user specific databases - Has limited acces to API calls - Can not create, modify or delete users @@ -76,9 +75,9 @@ The following user-roles are supported: 4. - guest + guest: - : - Has very limited access to API calls + - Has very limited access to API calls - Can not create, modify or delete mapsets - Can not create, modify or delete users - Has access to persistent databases that were granted by a @@ -106,8 +105,8 @@ Overview table: | | | uperadmin | | | | +-----------+-----------+-----------+----------+-----------+-----------+ | location/ | y | y | can | has | - | -| mapset | | | create | access to | | -| access is | | | create, | p | | +| mapset | | | create, | access to | | +| access is | | | | p | | | unlimited | | | modify | ersistent | | | | | | and | databases | | | | | | delete | that were | | @@ -158,13 +157,13 @@ The Actinia databases Actinia manages GRASS GIS locations in its *persistent database*. User are not permitted to modify data in the actinia persistent database, but can access all data read-only for processing and visualization. Data in -the persistent database can only accessed via HTTP GET API calls. +the persistent database can only be accessed via HTTP GET API calls. The user can either process data in an *ephemeral databases*, that will be removed after the processing is finished, or in a *user specific database*. A user specific database is persistent, only visible to users of the same user-group and can contain any data the user has -imported.The user can read-access all data from the persistent database +imported. The user can read-access all data from the persistent database while running analysis in the ephemeral database or user specific database. @@ -172,29 +171,29 @@ database. 1. - Persistent database + Persistent database: - : - Read only database with locations and mapsets that can be + - Read only database with locations and mapsets that can be used as processing environment and data source - Data can only be accessed using HTTP GET API calls 2. - Ephemeral database + Ephemeral database: - : - All processing is performed in ephemeral databases for + - All processing is performed in ephemeral databases for performance and security reasons - Ephemeral databases are created for all API calls and removed after the processing is finished - - Ephemeral databases use persistent database as processing + - Ephemeral databases use persistent databases as processing environments to access required data from mapsets in persistent locations 3. - User specific databases + User specific databases: - : - Persistent databases that can be created and modified by a + - Persistent databases that can be created and modified by a specific user group - The base for a location in a user specific database can be a location from a persistent database, however mapsets @@ -202,6 +201,8 @@ database. - A user group can only access a single database with any number of locations +**Footnotes** + [^1]: [^2]: From d6e159eed6fdc740dc0eb2d9ab8a24745e44a94f Mon Sep 17 00:00:00 2001 From: Julia Haas Date: Fri, 28 May 2021 12:03:11 +0200 Subject: [PATCH 2/7] remove empty line in table --- docs/docs/actinia_concepts.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/docs/actinia_concepts.md b/docs/docs/actinia_concepts.md index b4b4d4dff..59bcbe38a 100644 --- a/docs/docs/actinia_concepts.md +++ b/docs/docs/actinia_concepts.md @@ -106,18 +106,18 @@ Overview table: +-----------+-----------+-----------+----------+-----------+-----------+ | location/ | y | y | can | has | - | | mapset | | | create, | access to | | -| access is | | | | p | | -| unlimited | | | modify | ersistent | | -| | | | and | databases | | -| | | | delete | that were | | -| | | | mapsets | granted | | -| | | | in user | by a | | -| | | | specific | su | | -| | | | d | peradmin, | | -| | | | atabases | defined | | -| | | | , | in redis | | -| | | | defined | | | +| access is | | | modify | p | | +| unlimited | | | and | ersistent | | +| | | | delete | databases | | +| | | | mapsets | that were | | +| | | | in user | granted | | +| | | | specific | by a | | +| | | | d | su | | +| | | | atabases | peradmin, | | +| | | | , | defined | | +| | | | defined | in redis | | | | | | in redis | | | +| | | | | | | +-----------+-----------+-----------+----------+-----------+-----------+ | module | y | y | can run | has very | - | | access is | | | c | limited | | From 1f1fa744f25212b6e7acff0b44202201b95dfda6 Mon Sep 17 00:00:00 2001 From: Julia Haas Date: Fri, 28 May 2021 12:14:52 +0200 Subject: [PATCH 3/7] minor changes --- docs/docs/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/index.md b/docs/docs/index.md index c7ab11d5d..86ae6a9be 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -10,7 +10,7 @@ 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 +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 @@ -18,7 +18,8 @@ ephemeral databases. The computational results of ephemeral processing are available via object storage as GeoTIFF files. The full API documentation is available here: - + + ::: {.toctree maxdepth="2"} Introduction \ Introduction \ From 7344c873861cc5bdf864493aa7890054cfa94b73 Mon Sep 17 00:00:00 2001 From: Julia Haas Date: Fri, 28 May 2021 13:54:53 +0200 Subject: [PATCH 4/7] minor changes --- docs/docs/introduction.md | 8 ++++---- docs/docs/tutorial_data_access.md | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 63a1d887f..538f1898c 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -3,12 +3,12 @@ Introduction Actinia is a REST service to process geographical data that can be managed by the GRASS GIS software system. The software is designed to -expose a GRASS GIS database and many GRASS GIS[^1] processing tool as +expose a GRASS GIS database and many GRASS GIS[^1] processing tools as REST service[^2]. Hence, access to GRASS resources like raster maps, space-time raster datasets, processing and analysis modules are available via URL. In addition Actinia allows the processing of cloud based data, for example all Landsat 4-8 scenes as well as all -Sentinel-2A scenes in an ephemeral databases. The computational results +Sentinel-2A scenes in an ephemeral database. The computational results of ephemeral processing are available via object storage as GeoTIFF files. @@ -20,7 +20,7 @@ computation, spatio-temporal statistical analysis and many more. To use actinia the user must have an understanding of the GRASS GIS concept[^3] of location, mapsets, raster maps, space-time datasets and modules. The URLs that provide access to the GRASS database reflect -these concepts. Hence, the location, the mapset, the required raster map +these concepts. Hence, the location, the mapset and the required raster map are part of the URL to access the service. What is REST? @@ -28,7 +28,7 @@ What is REST? The Representational state transfer (REST)[^4] is an architectural style based on HTTP[^5] that uses GET[^6], DELETE[^7], POST[^8] and PUT[^9] -methods to manipulate and receive resource with stateless operations. +methods to manipulate and receive resources with stateless operations. While GET requests can be send easily from a browser, POST, PUT or DELETE request can not. To access the full potential of actinia you will diff --git a/docs/docs/tutorial_data_access.md b/docs/docs/tutorial_data_access.md index b073a66e9..24687f42b 100644 --- a/docs/docs/tutorial_data_access.md +++ b/docs/docs/tutorial_data_access.md @@ -12,7 +12,6 @@ line tool **curl**[^1]. **Curl** should be available on many Linux systems. However, tools like *postman*[^2] allow a more comfortable way to access actinia. -**Footnotes** Using curl for HTTP requests ---------------------------- @@ -20,7 +19,7 @@ Using curl for HTTP requests We will use the Unix shell and curl to access the REST API. First open a shell of choice (we use bash here) and setup the login information, the IP address and the port on which the actinia service is running, so you -can simply change the IP and Port if your server uses a different +can simply change the IP and port if your server uses a different address: ```bash @@ -31,7 +30,7 @@ export AUTH='-u superadmin:abcdefgh' Access to locations and mapsets in the persistent database ---------------------------------------------------------- -The following API call lists all available locations in the Actinia +The following API call lists all available locations in the actinia persistent database: ```bash @@ -511,12 +510,11 @@ Access to raster time-series in the persistent database ------------------------------------------------------- Actinia supports the analysis of time-series data based on the temporal -framework of GRASS GIS[^3],[^4]. A time-series datatype is located in +framework of GRASS GIS[^3], [^4]. A time-series datatype is located in location *ECAD* with mapsets *PERMANENT*. The time-series datatype is called space-time raster dataset (strds) and represents a time-stamped series of yearly temperature and precipitation data for Europe. -**Footnotes** We list all strds with the following API call: @@ -796,6 +794,8 @@ section of the JSON response: } ``` +**Footnotes** + [^1]: [^2]: From 08d021c74ad86cc64f3820e9b80cec53b0a3090b Mon Sep 17 00:00:00 2001 From: Julia Haas Date: Fri, 28 May 2021 16:42:09 +0200 Subject: [PATCH 5/7] little adjustments and additions to tutorials --- docs/docs/tutorial_landsat_ndvi.md | 12 +++++++++++- docs/docs/tutorial_process_chain.md | 15 +++++++++------ docs/docs/tutorial_sentinel2_ndvi.md | 7 ++++--- 3 files changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/docs/tutorial_landsat_ndvi.md b/docs/docs/tutorial_landsat_ndvi.md index df6652dd0..887d84df7 100644 --- a/docs/docs/tutorial_landsat_ndvi.md +++ b/docs/docs/tutorial_landsat_ndvi.md @@ -2,10 +2,19 @@ Landsat NDVI computation ======================== Actinia provides several API calls to compute satellite specific -parameters. +parameters: + We will use the Unix shell and curl to access the REST API. First open a shell of choice (we use bash here) and setup the login information, the IP address and the port on which the actinia service is running, so you can simply change the IP and port if your server uses a different + address: + + ```bash + export ACTINIA_URL=https://actinia.mundialis.de/latest + export AUTH='-u demouser:gu3st!pa55w0rd' + # other user credentials can be provided in the same way + ``` + The NDVI is an important parameter that is derived from multi-spectral satellite images. The following asynchronous API call computes the NDVI of the Landsat8 scene **LC80440342016259LGN00** with TOAR top of @@ -14,6 +23,7 @@ scene downloading, reprojection, atmospheric correction, statistical analysis and preview rendering in a single call using a self describing url. + ```bash curl ${AUTH} -X POST -i "${ACTINIA_URL}/landsat_process/LC80440342016259LGN00/TOAR/NDVI" ``` diff --git a/docs/docs/tutorial_process_chain.md b/docs/docs/tutorial_process_chain.md index 07e6bb2e1..62a8ab821 100644 --- a/docs/docs/tutorial_process_chain.md +++ b/docs/docs/tutorial_process_chain.md @@ -5,7 +5,7 @@ The actinia process chain ------------------------- Actinia provides the **process chain** approach to specify import, -processing and export of geo-data using the actinia GRASS GIS processing +processing and export of geodata using the actinia GRASS GIS processing system. The process chain must be formulated in JSON. The processing is always performed in an ephemeral database. The computational environment is based on locations in the persistent database. If required, the @@ -20,11 +20,13 @@ storage, outside the actinia environment. Within a process chain we have read only access to all raster maps of the persistent database location that is used as computational environment. -A process chain is a list of GRASS GIS modules[^1] that will executed in +A process chain is a list of GRASS GIS modules[^1] that will be executed in serial, based on the order of the list. GRASS GIS modules are specified -as process definitions[^2] that includes the name of the command, the +as process definitions[^2] that include the name of the command, the inputs[^3] and outputs[^4], including import and export definitions as -well as the module flags. The following example defines a single process +well as the module flags. + +The following example defines a single process that runs the GRASS GIS module *r.slope.aspect*[^5] to compute the *slope* for the raster map layer *elev\_ned\_30m* that is located in the mapset[^6] *PERMANENT*. The output of the module is named @@ -108,7 +110,6 @@ export as GeoTiff files. } ``` -**Footnotes** **Output parsing** @@ -604,7 +605,7 @@ Sentinel-2A NDVI process chain We create a process chain that computes the NDVI from a Sentinel-2A scene based on the bands 8 and 4 with the GRASS GIS module r.mapcalc. We use the latitude/longitude location **latlong\_wgs84** as processing -environment. and the computational region of sentinel band B04 for the +environment and the computational region of sentinel band B04 for the NDVI processing. Then we calculate univariate statistics for the Sentinel-2A scene. The computed NDVI raster layer will be exported as geotiff file that can be accessed via an URL. @@ -1346,6 +1347,8 @@ The finished response should look like this: } ``` +**Footnotes** + [^1]: [^2]: diff --git a/docs/docs/tutorial_sentinel2_ndvi.md b/docs/docs/tutorial_sentinel2_ndvi.md index af6f47ff1..844485fee 100644 --- a/docs/docs/tutorial_sentinel2_ndvi.md +++ b/docs/docs/tutorial_sentinel2_ndvi.md @@ -1,4 +1,5 @@ -Sentinel-2 NDVI computation =========================== +Sentinel-2 NDVI computation +=========================== The following asynchronous API call computes the NDVI of the Sentinel-2 scene @@ -39,7 +40,7 @@ finished response: ``` Poll the status of the asynchronous API call by polling the status URL. -Be aware that the resource id will change for different NDVI API calls. +Be aware that you have to change the status url as the resource id will change for different NDVI API calls. ```bash curl ${AUTH} -X GET -i http://actinia.mundialis.de/api/v1/resources/superadmin/resource_id-6b849585-576f-40b5-a514-34a7cf1f97ce @@ -641,7 +642,7 @@ as well as univariate statistics of the computed NDVI scene. } ``` -The following URL\'s point to the resulting PNG preview image and the +The following URLs point to the resulting PNG preview image and the NDVI GeoTiff file: From b3cfeff818c8b802a162ac5d6b81e42a7dd27930 Mon Sep 17 00:00:00 2001 From: Julia Haas Date: Fri, 28 May 2021 17:12:24 +0200 Subject: [PATCH 6/7] adaptions in tutorials --- docs/docs/tutorial_data_access.md | 4 ++-- docs/docs/tutorial_landsat_ndvi.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/tutorial_data_access.md b/docs/docs/tutorial_data_access.md index 24687f42b..9c8d9a49c 100644 --- a/docs/docs/tutorial_data_access.md +++ b/docs/docs/tutorial_data_access.md @@ -24,9 +24,9 @@ address: ```bash export ACTINIA_URL=https://actinia.mundialis.de/latest -export AUTH='-u superadmin:abcdefgh' +export AUTH='-u demouser:gu3st!pa55w0rd' +# other user credentials can be provided in the same way ``` - Access to locations and mapsets in the persistent database ---------------------------------------------------------- diff --git a/docs/docs/tutorial_landsat_ndvi.md b/docs/docs/tutorial_landsat_ndvi.md index 887d84df7..6251888e3 100644 --- a/docs/docs/tutorial_landsat_ndvi.md +++ b/docs/docs/tutorial_landsat_ndvi.md @@ -53,18 +53,18 @@ processing result. "timestamp": 1527677539.5457737, "urls": { "resources": [], - "status": "http://actinia.mundialis.de/api/v1/resources/superadmin/resource_id-a12d80c1-539a-45b9-a78c-ee4014f50d03" + "status": "https://actinia.mundialis.de/api/v1/resources/superadmin/resource_id-a12d80c1-539a-45b9-a78c-ee4014f50d03" }, "user_id": "superadmin" } ``` Request the status of the asynchronous API call by polling the status -URL. Be aware that the resource id will change for different NDVI API +URL. Be aware that you have to use your status url as the resource id will change for different NDVI API calls. ```bash - curl ${AUTH} -X GET -i "http://actinia.mundialis.de/api/v1/resources/superadmin/resource_id-a12d80c1-539a-45b9-a78c-ee4014f50d03" + curl -L ${AUTH} -X GET -i "https://actinia.mundialis.de/api/v1/resources/superadmin/resource_id-a12d80c1-539a-45b9-a78c-ee4014f50d03" ``` The final result will contain a complete processing list as well as From 3034bf35c65031b9620e118ab26a2ebe52badd26 Mon Sep 17 00:00:00 2001 From: Julia Haas Date: Thu, 12 Aug 2021 16:57:38 +0200 Subject: [PATCH 7/7] format overview table --- docs/docs/actinia_concepts.md | 62 ++++------------------------------- 1 file changed, 7 insertions(+), 55 deletions(-) diff --git a/docs/docs/actinia_concepts.md b/docs/docs/actinia_concepts.md index 59bcbe38a..d55cf20bc 100644 --- a/docs/docs/actinia_concepts.md +++ b/docs/docs/actinia_concepts.md @@ -85,61 +85,13 @@ The following user-roles are supported: Overview table: -+-----------+-----------+-----------+----------+-----------+-----------+ -| task | s | admin | user | guest | notes | -| | uperadmin | | | | | -+===========+===========+===========+==========+===========+===========+ -| amount | y | y | limited, | limited, | - | -| raster | | | selected | selected | | -| cells is | | | via | via redis | | -| unlimited | | | redis | | | -+-----------+-----------+-----------+----------+-----------+-----------+ -| database | y | only to | limited, | limited, | - | -| access is | | p | defined | defined | | -| unlimited | | ersistent | in redis | in redis | | -| | | databases | | | | -| | | that were | | | | -| | | granted | | | | -| | | by a | | | | -| | | s | | | | -| | | uperadmin | | | | -+-----------+-----------+-----------+----------+-----------+-----------+ -| location/ | y | y | can | has | - | -| mapset | | | create, | access to | | -| access is | | | modify | p | | -| unlimited | | | and | ersistent | | -| | | | delete | databases | | -| | | | mapsets | that were | | -| | | | in user | granted | | -| | | | specific | by a | | -| | | | d | su | | -| | | | atabases | peradmin, | | -| | | | , | defined | | -| | | | defined | in redis | | -| | | | in redis | | | -| | | | | | | -+-----------+-----------+-----------+----------+-----------+-----------+ -| module | y | y | can run | has very | - | -| access is | | | c | limited | | -| unlimited | | | omputati | access to | | -| | | | onal | API calls | | -| | | | tasks in | | | -| | | | e | | | -| | | | phemeral | | | -| | | | and user | | | -| | | | specific | | | -| | | | d | | | -| | | | atabases | | | -+-----------+-----------+-----------+----------+-----------+-----------+ -| get, | y | users | n | n | Only | -| create, | | with the | | | normal | -| delete a | | maximum | | | users | -| single | | user-role | | | (r | -| user | | user of | | | ole=user) | -| | | the same | | | can be | -| | | user | | | created | -| | | group | | | | -+-----------+-----------+-----------+----------+-----------+-----------+ +| task | superadmin | admin | user | guest |notes | +|------|------------|-------|------|-------|------| +| amount raster cells is unlimited | y | y | limited, selected via redis | limited, selected via redis | - | +| database access is unlimited | y | only to persistent databases that were granted by a superadmin | limited, defined in redis | limited, defined in redis | - | +| location/mapset access is unlimited | y | y | can create, modify and delete mapsets in user specific databases, defined in redis | has access to persistent databases that were granted by a superadmin, defined in redis | - | +|module access is unlimited | y | y | can run computational tasks in ephemeral and user specific databases | has very limited access to API calls | - | +| get, create, delete a single user | y | users with the maximum user-role user of the same user group | n | n | Only normal users (role=user can be created) | In the file actinia.cfg, limits and more can be defined: