Merge pull request #65 from pblottiere/prepare_v100

Prepare v1.0.0
pblottiere · Jul 31, 2024 · 36c38cf · 36c38cf
2 parents 9b2cb2b + f8c8c9d
commit 36c38cf
Show file tree

Hide file tree

Showing 17 changed files with 259 additions and 119 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,56 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [1.0.0] - 2024-07-31
+
+### Added
+
+- Add qsa-plugin, qsa-cli and doc: https://github.com/pblottiere/QSA/pull/8
+- Add raster layer support: https://github.com/pblottiere/QSA/pull/9
+- Add a CHANGELOG file: https://github.com/pblottiere/QSA/pull/10
+- Add basic badges in README: https://github.com/pblottiere/QSA/pull/11
+- Add qsa-cli stats command: https://github.com/pblottiere/QSA/pull/13
+- Add PostgreSQL support for storing QGIS projects: https://github.com/pblottiere/QSA/pull/15
+- Add doc for raster layer in sandbox: https://github.com/pblottiere/QSA/pull/16
+- Add basic support for raster style: https://github.com/pblottiere/QSA/pull/17
+- Add support for min/max settings in raster style: https://github.com/pblottiere/QSA/pull/18
+- CRS is now optional when adding a layer: https://github.com/pblottiere/QSA/pull/19
+- Manage optional CRS when MapProxy is enabled: https://github.com/pblottiere/QSA/pull/20
+- Optimize raster cache config: https://github.com/pblottiere/QSA/pull/21
+- Add PostGIS support for vector layers: https://github.com/pblottiere/QSA/pull/22
+- Add option to build overview if necessary: https://github.com/pblottiere/QSA/pull/24
+- Add QSA_LOGLEVEL environment variable: https://github.com/pblottiere/QSA/pull/27
+- Add check on epsg code validity: https://github.com/pblottiere/QSA/pull/29
+- Optimize MapProxy clear cache: https://github.com/pblottiere/QSA/pull/31
+- Homogenize gray band properties with red/green/blue: https://github.com/pblottiere/QSA/pull/32
+- Optimize min/max statistics computation: https://github.com/pblottiere/QSA/pull/34
+- Update QSA app to be used with a proper WSGI HTTP production server: https://github.com/pblottiere/QSA/pull/38
+- Add singleband pseudocolor renderer: https://github.com/pblottiere/QSA/pull/39
+- Use QGIS 3.38 in sandbox: https://github.com/pblottiere/QSA/pull/41
+- Add support for WMS TIME parameter: https://github.com/pblottiere/QSA/pull/42
+- Add gradient stops for singlebandpseudocolor renderer: https://github.com/pblottiere/QSA/pull/43
+- Adapt docs how to run tests: https://github.com/pblottiere/QSA/pull/49
+- Add /api/processing/raster/calculator entrypoint: https://github.com/pblottiere/QSA/pull/45
+- Add /api/processing/raster/histogram: https://github.com/pblottiere/QSA/pull/52
+- Activate legend in MapProxy configuration: https://github.com/pblottiere/QSA/pull/53
+- CI: add unit test without Postgres dependency: https://github.com/pblottiere/QSA/pull/50
+- Add MapProxy s3 cache support: https://github.com/pblottiere/QSA/pull/55
+- Move histogram computation in dedicated process: https://github.com/pblottiere/QSA/pull/56
+- Build 'dev' container image on push to 'main' branch: https://github.com/pblottiere/QSA/pull/61
+- Optimize project opening: https://github.com/pblottiere/QSA/pull/58
+- Add global try/except for requests: https://github.com/pblottiere/QSA/pull/62
+- Add badge for CI: https://github.com/pblottiere/QSA/pull/63
+
+### Fixed
+
+- Fix projects in cache in qsa-plugin: https://github.com/pblottiere/QSA/pull/12
+- Fix docs: https://github.com/pblottiere/QSA/pull/14
+- Deactivate multithreading: https://github.com/pblottiere/QSA/pull/23
+- Fix get style for raster (and homogenize vector style): https://github.com/pblottiere/QSA/pull/25
+- Remove log in staticmethod: https://github.com/pblottiere/QSA/pull/30
+- Remove useless print in tests: https://github.com/pblottiere/QSA/pull/54
+
+
 ## [0.0.2] - 2024-02-15
 
 ### Added

diff --git a/docs/src/README.md b/docs/src/README.md
@@ -26,5 +26,4 @@ Roadmap:
 * Add more documentation
 * Add PostgreSQL support to store QGIS styles and QSA internals data
 * Publish `qsa-cli` on PyPI
-* Publish a `qsa-api` Docker image on DockerHub
 * Publish `qsa-plugin` on QGIS plugin repository
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -2,7 +2,11 @@
 - [QSA REST API](qsa-api/README.md)
   - [Installation](qsa-api/installation.md)
   - [Configuration](qsa-api/configuration.md)
-  - [Endpoints](qsa-api/endpoints.md)
+  - [Endpoints](qsa-api/endpoints/README.md)
+    - [/api/symbology](qsa-api/endpoints/symbology.md)
+    - [/api/projects](qsa-api/endpoints/projects.md)
+    - [/api/processing](qsa-api/endpoints/processing.md)
+    - [/api/instances](qsa-api/endpoints/instances.md)
 - [QSA plugin](qsa-plugin/README.md)
   - [Installation](qsa-plugin/installation.md)
   - [Configuration](qsa-plugin/configuration.md)
@@ -14,9 +18,12 @@
 - [Sandbox](sandbox/README.md)
   - [Introspection](sandbox/inspect.md)
   - [Projects](sandbox/projects.md)
-  - [Vector layers](sandbox/vector/layers.md)
-  - [Vector styles](sandbox/vector/styles.md)
-  - [Raster layers](sandbox/raster/layers.md)
-  - [Raster styles](sandbox/raster/styles.md)
+  - [Vector](sandbox/vector/README.md)
+    - [Layers](sandbox/vector/layers.md)
+    - [Styles](sandbox/vector/styles.md)
+  - [Raster](sandbox/raster/README.md)
+    - [Layers](sandbox/raster/layers.md)
+    - [Styles](sandbox/raster/styles.md)
+    - [Processing](sandbox/raster/processing.md)
 - [Developers](DEVELOPERS.md)
 - [Funders](FUNDERS.md)
diff --git a/docs/src/qsa-api/configuration.md b/docs/src/qsa-api/configuration.md
@@ -14,13 +14,19 @@ QSA web server can be configured thanks to the next environment variables:
 | No         | `QSA_MAPPROXY_CACHE_S3_DIR`            | S3 cache directory for MapProxy. Default to `/mapproxy/cache`                    |
 
 
+<div class="warning">
+MapProxy
+
+Time dimension caching is not supported with S3 backend storage.
+</div>
+
+
 ## PostgreSQL support {#postgresql-support}
 
 When PostgreSQL support is enabled to store QGIS projects thanks to the
 `QSA_QGISSERVER_PROJECTS_PSQL_SERVICE` environment variable, the directory
 `QSA_QGISSERVER_PROJECTS_DIR` is only used to store the QSA SQLite database as
-well as QGIS QML styles. In the future, the QSA database and QGIS styles will
-also be stored in PostgreSQL when enabled.
+well as QGIS QML styles.
 
 The PostgreSQL support relies on a `service` defined in a [PostgreSQL connection
 service file](https://www.postgresql.org/docs/current/libpq-pgservice.html).
@@ -38,3 +44,10 @@ password=
 
 A query string parameter can be used to specify a `schema` through the QSA API
 (`public` is used by default).
+
+<div class="warning">
+Roadmap
+
+In the future, the QSA database and QGIS styles will also be stored in
+PostgreSQL when enabled.
+</div>
diff --git a/docs/src/qsa-api/endpoints/README.md b/docs/src/qsa-api/endpoints/README.md
@@ -0,0 +1,19 @@
+# QSA REST API : endpoints
+
+The QSA REST API provides several endpoints:
+
+* [/api/symbology](symbology.md)
+* [/api/projects](projects.md)
+* [/api/instances](instances.md)
+* [/api/processing](processing.md)
+
+### PostgreSQL schema
+
+When PostgreSQL support is enabled, a query string parameter `schema` may be
+used to specify the schema in which the QGIS project is stored in the database
+(`public` is used by default).
+
+```` shell
+# call a specific endpoint using projects stored in PostgreSQL schema named `myschema`
+$ curl "http://localhost/api/xxx/yyy?schema=myschema"
+````
diff --git a/docs/src/qsa-api/endpoints/instances.md b/docs/src/qsa-api/endpoints/instances.md
@@ -0,0 +1,12 @@
+# QSA REST API : /api/instances
+
+
+When `qsa-plugin` is installed, an `/api/instances` endpoint is available to
+retrieve information about QGIS Server underlying instances.
+
+| Method  |                      URL                      |         Description                        |
+|---------|-----------------------------------------------|--------------------------------------------|
+| GET     | `/api/instances`                              | List online QGIS Server instances          |
+| GET     | `/api/instances/{instance}`                   | List QGIS Server instance metadata         |
+| GET     | `/api/instances/{instance}/logs`              | Return logs of QGIS Server instance        |
+| GET     | `/api/instances/{instance}/stats`             | Return stats of QGIS Server instance       |
diff --git a/docs/src/qsa-api/endpoints/processing.md b/docs/src/qsa-api/endpoints/processing.md
@@ -0,0 +1,31 @@
+# QSA REST API : /api/processing
+
+The QSA REST API provides some basic processing methods to create on-the-fly
+rasters or get histogram for raster layers.
+
+| Method  |                      URL                              |         Description                                                  |
+|---------|-------------------------------------------------------|----------------------------------------------------------------------|
+| POST    | `/api/processing/raster/histogram/{project}/{layer}`  | Return an histogram in JSON                                          |
+| POST    | `/api/processing/raster/calculator/{project}`         | Create a raster based on an `expression` and an `output` filename    |
+
+
+Examples:
+
+``` shell
+# create a new layer based on a QGIS expression
+$ curl "http://localhost/api/projects/" \
+     -X POST \
+     -H 'Content-Type: application/json' \
+     -d '{
+        "expression":"layer@1 + 10",
+        "output":"/vsis3/my-storage/result.tif"
+     }'
+```
+
+
+<div class="warning">
+Processing
+
+These are basic processing methods but one could argue that WPS or OGC API
+Processes should be used instead.
+</div>
diff --git a/docs/src/qsa-api/endpoints.md → docs/src/qsa-api/endpoints/projects.md b/docs/src/qsa-api/endpoints.md → docs/src/qsa-api/endpoints/projects.md
@@ -1,15 +1,4 @@
-# QSA REST API : endpoints
-
-## PostgreSQL schema
-
-When PostgreSQL support is enabled, a query string parameter `schema` may be
-used to specify the schema in which the QGIS project is stored in the database
-(`public` is used by default).
-
-```` shell
-# call a specific endpoint using projects stored in PostgreSQL schema named `myschema`
-$ curl "http://localhost/api/xxx/yyy?schema=myschema"
-````
+# QSA REST API : /api/projects
 
 ## Project
 
@@ -61,90 +50,37 @@ empty.
 | GET     | `/api/projects/{project}/layers/{layer}`         | List layer's metadata                                                                                                                              |
 | GET     | `/api/projects/{project}/layers/{layer}/map`     | WMS `GetMap` result with default parameters                                                                                                        |
 | GET     | `/api/projects/{project}/layers/{layer}/map/url` | WMS `GetMap` URL with default parameters                                                                                                           |
-| POST    | `/api/projects/{project}/layers`                 | Add layer to project with `type` (`vector` or `raster`), `name`, `datasource`, `overview` (build overview for rasters on S3) and `crs` (optional)  |
+| POST    | `/api/projects/{project}/layers`                 | Add layer to project. See [Layer definition](#layer-definition) for more information.                                                              |
 | POST    | `/api/projects/{project}/layers/{layer}/style`   | Add/Update layer's style with `name` (style name) and `current` (`true` or `false`)                                                                |
 | DELETE  | `/api/projects/{project}/layers/{layer}`         | Remove layer from project                                                                                                                          |
 
+#### Layer definition {#layer-definition}
+
+A layer can be added to a project thanks to the next parameters:
+
+- `type` : `raster` or `vector`
+- `name` : the layer's name
+- `datasource` : the link to the datasource according to the storage backend
+    - filesystem : `/tmp/raster.tif`
+    - AWS S3 : `/vsis3/bucket/raster.tif`
+    - PostGIS : `service=qsa table=\"public\".\"lines\" (geom)`
+- `overview` (optional) : automatically build overviews for raster layers stored in S3 buckets
+- `crs` (optional) : CRS (automatically detected by default)
+
 Example:
 
 ```` shell
-# Add a FlatGeobuf vector layer in project `my_project`
+# Add a FlatGeobuf vector layer stored on S3 bucket in project `my_project`
 $ curl "http://localhost/api/projects/my_project/layers" \
   -X POST \
   -H 'Content-Type: application/json' \
   -d '{
-    "crs": 4326,
     "name":"my_layer",
     "type":"vector",
     "datasource":"/vsis3/my-storage/vector/my_layer.fgb",
   }'
 ````
 
-## Symbology
-
-Vector layers rendering can be configured with several kinds of symbols
-according to the geometry type. The [symbol selector](https://docs.qgis.org/3.34/en/docs/user_manual/style_library/symbol_selector.html)
-in QGIS is very dense but for now, only Marker, Line and Fill simple symbols
-are supported. The `/api/symbology` endpoint allows to dynamically retrieve the
-corresponding parameters depending on QGIS Server version.
-
-| Method  |                      URL                                                  |         Description                          |
-|---------|---------------------------------------------------------------------------|----------------------------------------------|
-| GET     | `/api/symbology/vector/point/single_symbol/marker/properties`             | Marker simple symbol properties              |
-| GET     | `/api/symbology/vector/line/single_symbol/line/properties`                | Line simple symbol properties                |
-| GET     | `/api/symbology/vector/polygon/single_symbol/fill/properties`             | Polygon simple symbol properties             |
-| GET     | `/api/symbology/vector/rendering/properties`                              | Vector layer rendering properties            |
-| GET     | `/api/symbology/raster/singlebandgray/properties`                         | Single band gray properties                  |
-| GET     | `/api/symbology/raster/multibandcolor/properties`                         | Multi band color properties                  |
-| GET     | `/api/symbology/raster/singlebandpseudocolor/properties`                  | Single band pseudocolor properties           |
-| GET     | `/api/symbology/raster/singlebandpseudocolor/ramp/{name}/properties`      | Single band pseudocolor ramp properties      |
-| GET     | `/api/symbology/raster/rendering/properties`                              | Raster layer rendering properties            |
-
-Examples:
-
-```` shell
-# Return single symbol properties for polygon layers
-$ curl "http://localhost:5000/api/symbology/vector/polygon/single_symbol/fill/properties" | jq
-{
-  "border_width_map_unit_scale": "3x:0,0,0,0,0,0",
-  "color": "0,0,255,255",
-  "joinstyle": "bevel",
-  "offset": "0,0",
-  "offset_map_unit_scale": "3x:0,0,0,0,0,0",
-  "offset_unit": "MM",
-  "outline_color": "35,35,35,255",
-  "outline_style": "solid (no, solid, dash, dot, dash dot, dash dot dot)",
-  "outline_width": "0.26",
-  "outline_width_unit": "MM",
-  "style": "solid"
-}
-
-# Return multi band gray properties for raster layers
-$ curl "http://localhost:5000/api/symbology/raster/multibandcolor/properties" | jq
-{
-  "blue": {
-    "band": 3,
-    "min": 0.0,
-    "max": 1.0
-  },
-  "green": {
-    "band": 2,
-    "min": 0.0,
-    "max": 1.0
-  },
-  "red": {
-    "band": 1,
-    "min": 0.0,
-    "max": 1.0
-  }
-  "contrast_enhancement": {
-    "algorithm": "StretchToMinimumMaximum (StretchToMinimumMaximum, NoEnhancement)",
-    "limits_min_max": "MinMax (MinMax, UserDefined)"
-  }
-}
-````
-
-
 ## Style
 
 A QSA style may be used through the `STYLE` OGC web services parameter to
@@ -239,24 +175,3 @@ $ curl "http://localhost:5000/api/projects/my_project/styles" \
     }
   }'
 ````
-
-
-## Processing
-
-| Method  |                      URL                              |         Description                                                  |
-|---------|-------------------------------------------------------|----------------------------------------------------------------------|
-| POST    | `/api/processing/raster/histogram/{project}/{layer}`  | Return an histogram in JSON                                          |
-| POST    | `/api/processing/raster/calculator/{project}`         | Create a raster based on an `expression` and an `output` filename    |
-
-
-## Instances
-
-When `qsa-plugin` is installed, an `/api/instances` endpoint is available to
-retrieve information about QGIS Server underlying instances.
-
-| Method  |                      URL                      |         Description                        |
-|---------|-----------------------------------------------|--------------------------------------------|
-| GET     | `/api/instances`                              | List online QGIS Server instances          |
-| GET     | `/api/instances/{instance}`                   | List QGIS Server instance metadata         |
-| GET     | `/api/instances/{instance}/logs`              | Return logs of QGIS Server instance        |
-| GET     | `/api/instances/{instance}/stats`             | Return stats of QGIS Server instance       |