Update docs

Readme to be cut down when ready

Author: ConnectedSystems

README.md

@@ -2,6 +2,8 @@
 
 API for supporting reef suitability assessments.
 
+[![Documentation](https://img.shields.io/badge/docs-dev-blue)](https://open-aims.github.io/ReefModEngine.jl/dev/)
+
 ## Setup
 
 Initialize the project the usual way:
@@ -27,6 +29,28 @@ TILE_SIZE = "256"  # Optional, tile block size to use (defaults to 256)
 
 By convention, this file is named `.config.toml` (note the leading `.`).
 
+## JWT Auth configuration
+
+The API can be additionally configured to expect a valid JWT in the `Authorization: Bearer <token>` header format.
+
+Add the following to `.config.toml`:
+
+```toml
+[jwt_auth]
+# Enable JWT auth : bool true/false
+JWT_ENABLED = true
+# Which iss to validate for the JWTs?
+JWT_ISS = "https://issuer.com"
+# WKT JWKS endpoint where public key can be retrieved
+WKT_ENDPOINT = "https://https://issuer.com/api/.well-known/jwks.json"
+```
+
+Pay attention to the issuer and wkt endpoints. The first should exactly match the expected JWT issuer claim. The second should be web-resolvable and return a WKT JSON which provides the public key.
+
+### Auth TODOs
+
+- ensure health check route is not authorised
+
 ## Quickstart
 
 ```julia
@@ -87,28 +111,6 @@ Note that the server now caches the initially loaded spatial data in between ser
 launches to reduce downtime. It will be necessary to restart the Julia session to reload
 spatial data.
 
-## JWT Auth configuration
-
-The API can be configured to expect a valid JWT in the `Authorization: Bearer <token>` header format.
-
-Add the following to your `.config.toml`:
-
-```toml
-[jwt_auth]
-# Enable JWT auth : bool true/false
-JWT_ENABLED = true
-# Which iss to validate for the JWTs?
-JWT_ISS = "https://issuer.com"
-# WKT JWKS endpoint where public key can be retrieved
-WKT_ENDPOINT = "https://https://issuer.com/api/.well-known/jwks.json"
-```
-
-Pay attention to the issuer and wkt endpoints. The first should exactly match the expected JWT issuer claim. The second should be web-resolvable and return a WKT JSON which provides the public key.
-
-### Auth TODOs
-
-- ensure health check route is not authorised
-
 ## Performance notes
 
 The config setting `COG_THREADS` controls how many threads should be requested when writing
@@ -159,37 +161,37 @@ When running the below commands, it is assumed you have `data` available locally
 
 ### To build from src files using Docker
 
-```
+```bash
 docker build . --target reefguide-src -t reefguide
 ```
 
 ### To build from src files using Docker Compose
 
-```
+```bash
 docker compose up --build reefguide-src
 ```
 
 ### To run with mounted files (launch server) using Docker
 
-```
+```bash
 docker run -p 8000:8000 -v ./data:/data/reefguide reefguide
 ```
 
 ### To run with mounted files (launch server) using Docker Compose
 
-```
+```bash
 docker compose up reefguide-src
 ```
 
 ### To run with mounted files (interactive shell) using Docker
 
 This will start a Julia shell where `ReefGuideAPI` is compiled and ready for use e.g.
 
-```
+```julia
 using ReefGuideAPI
 ReefGuideAPI.start_server("/data/reefguide/config.toml")
 ```
 
-```
+```julia
 docker run --rm --interactive --entrypoint="julia" --tty -v ./data:/data/reefguide reefguide
 ```

docs/src/getting_started.md

@@ -11,8 +11,6 @@ Initialize the project the usual way:
 A TOML file should be defined indicating location of the MPA dataset.
 These are currently the files/data created in Step/Script 1a in https://github.com/open-AIMS/GBR-reef-guidance-assessment
 
-Other settings configure the server
-
 ```toml
 [prepped_data]
 PREPPED_DATA_DIR = "C:/some_path_to_data/MPA/"
@@ -31,6 +29,28 @@ By convention, this file is named `.config.toml` (note the leading `.`).
 
 :::
 
+## JWT Auth configuration
+
+The API can be additionally configured to expect a valid JWT in the `Authorization: Bearer <token>` header format.
+
+Add the following to `.config.toml`:
+
+```toml
+[jwt_auth]
+# Enable JWT auth : bool true/false
+JWT_ENABLED = true
+# Which iss to validate for the JWTs?
+JWT_ISS = "https://issuer.com"
+# WKT JWKS endpoint where public key can be retrieved
+WKT_ENDPOINT = "https://https://issuer.com/api/.well-known/jwks.json"
+```
+
+Pay attention to the issuer and wkt endpoints. The first should exactly match the expected JWT issuer claim. The second should be web-resolvable and return a WKT JSON which provides the public key.
+
+### Auth TODOs
+
+- ensure health check route is not authorised
+
 ## Quickstart
 
 ```julia
@@ -110,27 +130,33 @@ Note that the server now caches the initially loaded spatial data in between ser
 launches to reduce downtime. It will be necessary to restart the Julia session to reload
 spatial data.
 
-## JWT Auth configuration
+## Performance notes
 
-The API can be configured to expect a valid JWT in the `Authorization: Bearer <token>`
-header format.
+The config setting `COG_THREADS` controls how many threads should be requested when writing
+out COGs. Ideally this will be set to at least 2 (preferably 4).
+Higher values do seem to reduce write times but with diminishing returns (tested up to 8).
+Locally, write times with four threads configured range from 10 to 15 seconds.
 
-Add the following to your `.config.toml`:
+## Reef edge alignment for site searching
 
-```toml
-[jwt_auth]
-# Enable JWT auth : bool true/false
-JWT_ENABLED = true
-# Which iss to validate for the JWTs?
-JWT_ISS = "https://issuer.com"
-# WKT JWKS endpoint where public key can be retrieved
-WKT_ENDPOINT = "https://https://issuer.com/api/.well-known/jwks.json"
-```
+`identify_potential_sites_edges()` can be used to identify potential sites that only align with
+the nearest reef edge (or specified rotations away from this angle).
+This method works by identifying the closest edge of reef polygon geometries that have been
+converted into lines.
 
-Pay attention to the issuer and wkt endpoints. The first should exactly match the expected
-JWT issuer claim. The second should be web-resolvable and return a WKT JSON which provides
-the public key.
+The following processing is required before use:
 
-### Auth TODOs
+- Reef polygons should be simplified (`GO.simplify()`) and buffered to avoid matching possibly inaccurate reef edges.
+- Simplified reef polygons should be provided as vertex-vertex lines with `polygon_to_lines()`.
+- Require raster of target pixels to search, and their indices (currently a vector of `CartesianIndices` for identifying search pixels). Use `findall(bool_search_raster)` to return pixel indices.
+- Raster of search pixels should be masked by reef polygons or simplified reef polygons.
+- The target region name should be specified in GBRMPA format.
+  - E.g. "Townsville/Whitsunday Management Area" rather than "Townsville-Whitsunday".
+
+### Parquet assessment additional setup
 
-- ensure health check route is not authorised
+- A parquet GeoDataFrame must be loaded and filtered for unsuitable pixels based on user criteria thresholds using a Dict and `within_thresholds()`.
+- `lon` and `lat` columns (FLoat64) must be added to the GeoDataFrame.
+  - E.g. `valid_pixels.lon = first.(GI.coordinates.(valid_pixels.geometry))`
+  The column used for masking should be the same as the column specified as geometry_col in
+  `identify_potential_sites_edges` (default = `:geometry`).