From 870b5183b035cb41f6e945fc5f59220b3d4a555a Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 18 May 2022 10:43:34 +0200 Subject: [PATCH] Add GeoTiff guidelines for the Web Editor --- README.md | 8 +++++++- docs/geotiff.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 docs/geotiff.md diff --git a/README.md b/README.md index 2a5ca0147..5d306df67 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ You can also build the files yourself and deploy them to any web host: 3. Open a command line window and go to the directory which contains the cloned/downloaded web editor files. 4. Configure the web editor by editing `config.js`, `vue.config.js` and `theme.scss` to suit your needs. 6. Install the dependencies by executing `npm install` on the command line -7. +7. For... * Development: Run the development server by executing `npm start`. * Deployment: Build the project by executing `npm run build`. Afterwards upload the content of the `dist` folder to your server. @@ -81,3 +81,9 @@ To test a certain commit, simply pull the according tag (available from 2021-09- docker pull mundialis/openeo-web-editor:sha-4636d41 ``` The Dockerimage is maintained by mundialis. + +## Implementation guide for back-ends + +Here we collection information for back-end implementors that want to improve the experience with the Web Editor by fine-tuning their implementation. + +* [GeoTiff / COG support](docs/geotiff.md) \ No newline at end of file diff --git a/docs/geotiff.md b/docs/geotiff.md new file mode 100644 index 000000000..625abb82c --- /dev/null +++ b/docs/geotiff.md @@ -0,0 +1,34 @@ +# (Cloud-Optimized) GeoTiffs in the Web Editor + +What is required by back-ends to give users an ideal experience with GeoTiff imagery in the Web Editor? + +1. All GeoTiffs must be valid GeoTiffs (including all required metadata) and should be valid cloud-optimized (COGs). If the files are not exported as COGs, the Editor needs to read the whole GeoTiff file at once which will usually fail with larger files (> 10 MB). +2. Range requests must be supported by the server to allow reading COGs. +3. [CORS](https://api.openeo.org/draft/index.html#section/Cross-Origin-Resource-Sharing-(CORS)/CORS-headers) must be sent by the server providing the files, especially you need to allow `Range` headers in `Access-Control-Expose-Headers` additionally. +4. COGs should provide overviews in the files whenever the files get larger than 1 or 2 MB in size. The overview tiles should have a size of at least 128x128 pixels and at maximum 512x512 pixels. +5. The GeoTiff must be readable by [geotiff.js](https://geotiffjs.github.io/geotiff.js/), especially the data type and the compression must be supported. +6. The GeoTiff metadata in the file should contain: + 1. The no-data value in [`TIFFTAG_GDAL_NODATA`](https://gdal.org/drivers/raster/gtiff.html#nodata-value), if applicable + 2. A projection, via the ["geo keys"](http://geotiff.maptools.org/spec/geotiff2.4.html) `ProjectedCSTypeGeoKey` or `GeographicTypeGeoKey` (otherwise provide at least a unit in `ProjLinearUnitsGeoKey` or `GeogAngularUnitsGeoKey`) + 3. GDAL metadata should be provided in the tag [`TIFFTAG_GDAL_METADATA`](https://gdal.org/drivers/raster/gtiff.html#metadata) per band: + 1. Minimum and Maximum values (tags: `STATISTICS_MINIMUM` and `STATISTICS_MAXIMUM`) + 2. A band name (tag: `DESCRIPTION`) + 5. The [`PhotometricInterpretation`](https://www.awaresystems.be/imaging/tiff/tifftags/photometricinterpretation.html) of the image should be set to `1` (BlackIsZero) if an RGB interpretation is not clear. If RGB is set as interpretation (`2`) and you have more than 3 samples per pixel ([`SamplesPerPixel`](https://www.awaresystems.be/imaging/tiff/tifftags/samplesperpixel.html)), the [`ExtraSamples`](https://www.awaresystems.be/imaging/tiff/tifftags/extrasamples.html) should be set. + 6. [`ColorMap`](https://www.awaresystems.be/imaging/tiff/tifftags/colormap.html)s are supported. +7. For batch jobs, the STAC metadata is recommended to contain per asset: + 1. The no-data value either in `file:nodata` (deprecated) or in `nodata` in `raster:bands` + 2. The `minimum` and `maximum` values per band in the `statistics` object in `raster:bands` + 3. A band `name` either in `raster:bands` (unspecified) or `eo:bands` + 4. The projection in `proj:epsg` (recommended), `proj:wkt2` (not well suported by OpenLayers) or `proj:proj4` (deprecated by STAC) + 5. The `type` must be set to the corresponding media type (see below) +8. For synchronous execution, the `Content-Type` in the header of the response must be set to the corresponding media type (see below) + +Links to the corresponding STAC extensions: +- [eo](https://github.com/stac-extensions/eo) +- [file](https://github.com/stac-extensions/file/tree/v1.0.0) (v1.0.0, latest is v2.1.0 but doesn't support nodata any more) +- [proj](https://github.com/stac-extensions/projection) +- [raster](https://github.com/stac-extensions/raster) + +Media Types: +- COGs (`image/tiff; application=geotiff; cloud-optimized=true`) +- GeoTiffs (`image/tiff; application=geotiff`) \ No newline at end of file