Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cleaning documentation in actinia_core/docs/docs #213

Merged
merged 8 commits into from
Aug 13, 2021
Merged

cleaning documentation in actinia_core/docs/docs #213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
cd4a7bc
cleaning documentation, removing minor mistakes
juleshaas May 28, 2021
d6e159e
remove empty line in table
juleshaas May 28, 2021
1f1fa74
minor changes
juleshaas May 28, 2021
7344c87
minor changes
juleshaas May 28, 2021
8c9ce4d
Merge branch 'main' of github.com:mundialis/actinia_core into actinia…
juleshaas May 28, 2021
08d021c
little adjustments and additions to tutorials
juleshaas May 28, 2021
b3cfeff
adaptions in tutorials
juleshaas May 28, 2021
3034bf3
format overview table
juleshaas Aug 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 30 additions & 77 deletions docs/docs/actinia_concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -76,71 +75,23 @@ 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
superadmin

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 | | | create, | p | |
| unlimited | | | modify | ersistent | |
| | | | and | databases | |
| | | | delete | that were | |
| | | | mapsets | granted | |
| | | | in user | by a | |
| | | | specific | su | |
| | | | d | peradmin, | |
| | | | atabases | defined | |
| | | | , | in redis | |
| | | | defined | | |
| | | | 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:

Expand All @@ -158,50 +109,52 @@ 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.

**Summary**

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
names must be unique.
- A user group can only access a single database with any
number of locations

**Footnotes**

[^1]: <https://www.openapis.org/>

[^2]: <https://swagger.io>
Expand Down
5 changes: 3 additions & 2 deletions docs/docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,16 @@ 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
ephemeral databases. The computational results of ephemeral processing
are available via object storage as GeoTIFF files.

The full API documentation is available here:
<https://actinia.mundialis.de/api_docs/>

<https://actinia.mundialis.de/api_docs/>

::: {.toctree maxdepth="2"}
Introduction \<introduction\> Introduction \<actinia\_concepts\>
Expand Down
8 changes: 4 additions & 4 deletions docs/docs/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -20,15 +20,15 @@ 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?
-------------

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
Expand Down
14 changes: 7 additions & 7 deletions docs/docs/tutorial_data_access.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,25 @@ 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
----------------------------

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
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
----------------------------------------------------------

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
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -796,6 +794,8 @@ section of the JSON response:
}
```

**Footnotes**

[^1]: <https://en.wikipedia.org/wiki/CURL>

[^2]: <https://www.getpostman.com/apps>
Expand Down
18 changes: 14 additions & 4 deletions docs/docs/tutorial_landsat_ndvi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,19 @@ Landsat NDVI computation
========================

Actinia provides several API calls to compute satellite specific
parameters.
parameters:

<https://actinia.mundialis.de/api_docs/#tag-Satellite-Image-Algorithms>

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
Expand All @@ -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"
```
Expand Down Expand Up @@ -43,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
Expand Down
Loading