From 6d719a9297bd494635995f7dae42794f58d09bdb Mon Sep 17 00:00:00 2001 From: tebben Date: Tue, 13 Aug 2024 13:36:21 +0200 Subject: [PATCH] updated README.md --- README.md | 126 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 77 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 307e783..5d85829 100644 --- a/README.md +++ b/README.md @@ -51,14 +51,13 @@ ghcr.io/sogelink-research/ctod:latest ### V1.0 (In progress) -- Refactoring - Cleanup viewer code - Update Wiki ### Future work (V1.1) - Mosaic dataset priority -- Profiling to see where can gain some performance +- Profiling to see where we can gain some performance - Support multiple workers - Extension support: Metadata, Watermask @@ -73,7 +72,7 @@ The following options can be set by supplying args to app.py or setting the envi |--logging-level|CTOD_LOGGING_LEVEL|debug, info, warning, error, critical|info| |--port|CTOD_PORT|Port to run the service on|5000| |--unsafe|CTOD_UNSAFE|Load unsafe tiles (not enough COG overviews or too many datasets in 1 tile), can result in huge and or stuck requests|| -|--no-dynamic|CTOD_NO_DYNAMIC|Disable the dynamic endpoint, only datasets from the config can be used when set|| +|--no-dynamic|CTOD_NO_DYNAMIC|Disable the dynamic endpoint, only datasets configured in the config can be used|| ## Run CTOD @@ -107,34 +106,27 @@ To enable caching, supply --tile-cache-path `path` with the start command. poetry run start --tile-cache-path ./ctod_cache ``` +## --no-dynamic + +The idea is that an user can use every COG that the CTOD service can access with the parameters the user wants, this can expose a problem when CTOD is available on the internet. A random user can use your CTOD instance to generate his own .terrain tiles or even mess up a cache by supplying weird grid sized. + +To prevent a user to use any cog with any parameter the endpoints are split up into `/tiles/dynamic/..` and `/tiles/{dataset}/..`. The dynamic endpoint accepts parameters and is flexible to use where the `/tiles/{dataset}` endpoint can only be [configured](#dataset-configuration) with a config file and ignores parameters. + +The dynamic endpoint can be disabled by supplying the option `--no-dynamic` to CTOD or set the environment variable `CTOD_NO_DYNAMIC` to `TRUE`. This way only configured datasets can be used with set parameters. + ## Endpoints -Endpoint documentation for your running CTOD service can also be found under `/doc` and `/redoc` +Endpoint documentation for your running CTOD service can also be found under `/doc`. ### Endpoint: `/` -Returns a sample Cesium viewer, all values can be changed using the control panel, default settings can be overwritten on startup of the viewer with the below parameters, see the example aswell. +Shows the available datasets and a link to open a preview viewer using the dataset. #### Request - **Method:** GET - **URL:** `http://localhost:5000` -#### Parameters - -- **minZoom** : The mininimum zoomlevel, When set CTOD returns empty tiles for zoom < minZoom, Default (1) -- **maxZoom** : Maximum zoom level that will be requested by the client, Default (18) -- **resamplingMethod** : Resampling method for COG: 'nearest', 'bilinear', 'cubic', 'cubic_spline', 'lanczos', 'average', 'mode', 'gauss', 'rms'. Default (None) -- **cog** : Path or URL to COG file. -- **skipCache** : Set to true to prevent loading tiles from the cache if cache is enabled in CTOD. Default (False) -- **meshingMethod**: Meshing method to use: grid, martini, delatin, Default (grid) - -#### Example - -```sh -http://localhost:5000?minZoom=1&maxZoom=18&cog=./ctod/files/test_cog.tif -``` - ### Endpoint: `/docs` The CTOD OpenAPI documentation with Swagger UI @@ -144,68 +136,79 @@ The CTOD OpenAPI documentation with Swagger UI - **Method:** GET - **URL:** `http://localhost:5000/docs` -#### Example +### Endpoint: `/tiles/dynamic/layer.json` -```sh -http://localhost:5000/docs -``` +Dynamically generates a layer.json based on the COG. The supplied parameters will be picked up by Cesium when using this url for the CesiumTerrainProvider and passed down to the .terrain requests. -### Endpoint: `/redoc` +#### Request + +- **Method:** GET +- **URL:** `http://localhost:5000/tiles/dynamic/layer.json` + +#### Parameters -The CTOD OpenAPI documentation with ReDoc UI +See [Parameters](#parameters) #### Example ```sh -http://localhost:5000/redoc +http://localhost:5000/tiles/dynamic/layer.json?maxZoom=18&cog=./ctod/files/test_cog.tif ``` +### Endpoint: `/tiles/{dataset}/layer.json` + +Dynamically generates a layer.json for a configured dataset, replace {dataset} with a dataset configured in `datasets.json`, all supplied url parameters will be ignored. + #### Request - **Method:** GET -- **URL:** `http://localhost:5000/redoc` +- **URL:** `http://localhost:5000/tiles/{dataset}/layer.json` -### Endpoint: `/tiles/dynamic/layer.json` +#### Example + +```sh +http://localhost:5000/tiles/demo/layer.json +``` -Dynamically generates a layer.json based on the COG. +### Endpoint: `/tiles/dynamic/{z}/{x}/{y}.terrain` + +Get a quantized mesh for tile index z, x, y. Set the minZoom value to retrieve empty tiles for zoom levels lower than minZoom. maxZoom is handled in the generated layer.json. #### Request - **Method:** GET -- **URL:** `http://localhost:5000/tiles/layer.json` +- **URL:** `http://localhost:5000/tiles/dynamic/{z}/{x}/{y}.terrain` #### Parameters -- **cog**: Path or URL to COG file. -- **maxZoom** : The max zoomlevel for the terrain. Default (18) -- **minZoom** : The min zoomlevel for the terrain. Default (0) -- **resamplingMethod** : Resampling method for COG: 'nearest', 'bilinear', 'cubic', 'cubic_spline', 'lanczos', 'average', 'mode', 'gauss', 'rms'. Default 'none' -- **skipCache** : Set to true to prevent loading tiles from the cache. Default (False) -- **meshingMethod**: The Meshing method to use: 'grid', 'martini', 'delatin' -- **defaultGridSize**: The default grid size (amount of rows/cols) to use if there is no specific zoomGridSizes defined for a requested tile, Default (20) -- **zoomGridSizes**: Per level defined grid size, when requested zoom for tile not specified use defaultGridSize. Default when defaultGridSize and zoomGridSizes not set (`{"15": 25, "16": 25, "17": 30, "18": 35, "19": 35, "20": 35, "21": 35, "22": 35}`) -- **defaultMaxError**: The default max triangulation error in meters to use, Default (4) -- **zoomMaxErrors**: Per level defined max error, when requested zoom for tile is not specified use defaultMaxError. Default when defaultMaxError and zoomMaxError not set (`{"15": 8, "16": 5, "17": 3, "18": 2, "19": 1, "20": 0.5, "21": 0.3, "22": 0.1}`) +See [Parameters](#parameters) #### Example ```sh -http://localhost:5000/tiles/layer.json?maxZoom=18&cog=./ctod/files/test_cog.tif +http://localhost:5000/tiles/dynamic/17/134972/21614.terrain?minZoom=1&cog=./ctod/files/test_cog.tif ``` -### Endpoint: `/tiles/dynamic/{z}/{x}/{y}.terrain` +### Endpoint: `/tiles/{dataset}/{z}/{x}/{y}.terrain` -Get a quantized mesh for tile index z, x, y. Set the minZoom value to retrieve empty tiles for zoom levels lower than minZoom. maxZoom is handled in the generated layer.json. +Get a quantized mesh for tile index z, x, y. Replace {dataset} with a dataset configured in `datasets.json`, all supplied url parameters will be ignored. #### Request - **Method:** GET -- **URL:** `http://localhost:5000/tiles/dynamic/{z}/{x}/{y}.terrain` +- **URL:** `http://localhost:5000/tiles/{dataset}/{z}/{x}/{y}.terrain` -#### Parameters +#### Example + +```sh +http://localhost:5000/tiles/demo/17/134972/21614.terrain +``` + +### Parameters - **cog**: Path or URL to COG file. - **minZoom** : The min zoomlevel for the terrain. Default (0) +- **maxZoom** : The max zoomlevel for the terrain. Default (18) - **noData** : The value to use for NoData in COG. Default (0) - **resamplingMethod** : Resampling method for COG: 'nearest', 'bilinear', 'cubic', 'cubic_spline', 'lanczos', 'average', 'mode', 'gauss', 'rms'. Default 'none' - **skipCache** : Set to true to prevent loading tiles from the cache. Default (False) @@ -221,10 +224,35 @@ Get a quantized mesh for tile index z, x, y. Set the minZoom value to retrieve e - **defaultMaxError**: The default max triangulation error in meters to use, Default (4) - **zoomMaxErrors**: Per level defined max error, when requested zoom for tile is not specified use defaultMaxError. Default when defaultMaxError and zoomMaxError not set (`{"15": 8, "16": 5, "17": 3, "18": 2, "19": 1, "20": 0.5, "21": 0.3, "22": 0.1}`) -#### Example -```sh -http://localhost:5000/tiles/dynamic/17/134972/21614.terrain?minZoom=1&cog=./ctod/files/test_cog.tif +## Dataset configuration + +It may be usefull to preconfigure a dataset in a config file, this makes the url cleaner and a user cannot override settings which can result in different configured tiles in the cache. When the option `--no-dynamic` is supplied to CTOD only datasets from the config can be used and the dynamic datasets are disabled. + +By default CTOD tries to look for the dataset config at `./config/datasets.json`, this can be overwritten with `--dataset-config-path` or environment variable `CTOD_DATASET_CONFIG_PATH`. When the config could not be found or has an error CTOD continues and logs an error. + +The exact same parameters as described in the topic [parameters](#parameters) can be used in the `.json` file for a dataset. + +### Example config + +```json +{ + "datasets": [ + { + "name": "demo", + "options": { + "cog": "./ctod/files/test_cog.tif", + "minZoom": 13, + "maxZoom": 17, + "noData": 0, + "meshingMethod": "grid", + "skipCache": false, + "zoomGridSizes": {"13": 5, "14": 10, "15": 15, "16": 20, "17": 25, "18": 30, "19": 35} + } + }, + ... + ] +} ``` ## More info