From 63732587431e714f039957fb2ae95ca9b2e13ca8 Mon Sep 17 00:00:00 2001 From: Jerome St-Louis Date: Tue, 13 Feb 2024 12:08:58 -0500 Subject: [PATCH] 9-scaling: (#180) Added `width` and `height` parameters --- standard/clause_9_scaling.adoc | 2 +- .../openapi/ogcapi-coverages-1.bundled.json | 22 +++++++++++++++++++ .../parameters/coverages-core/height.yaml | 9 ++++++++ .../parameters/coverages-core/width.yaml | 9 ++++++++ .../paths/coverages-core/pCoverage.yaml | 2 ++ .../requirements_class_coverage_scaling.adoc | 15 ++++++++++++- 6 files changed, 57 insertions(+), 2 deletions(-) create mode 100644 standard/openapi/parameters/coverages-core/height.yaml create mode 100644 standard/openapi/parameters/coverages-core/width.yaml diff --git a/standard/clause_9_scaling.adoc b/standard/clause_9_scaling.adoc index b66625c..ef0e5db 100644 --- a/standard/clause_9_scaling.adoc +++ b/standard/clause_9_scaling.adoc @@ -3,7 +3,7 @@ === Overview -The "Scaling" Requirements Class defines the `scale-factor`, `scale-axes` and `scale-size` parameters for retrieving coverage data at a specific resolution. +The "Scaling" Requirements Class defines the `scale-factor`, `scale-axes`, `scale-size`, `width` and `height` parameters for retrieving coverage data at a specific resolution. === Scaling Examples diff --git a/standard/openapi/ogcapi-coverages-1.bundled.json b/standard/openapi/ogcapi-coverages-1.bundled.json index 9c6c543..761864b 100644 --- a/standard/openapi/ogcapi-coverages-1.bundled.json +++ b/standard/openapi/ogcapi-coverages-1.bundled.json @@ -274,6 +274,28 @@ { "$ref": "#/components/parameters/scale-size" }, + { + "name": "width", + "in": "query", + "description": "Number of cells across the coverage dimension corresponding to the spatial dimension represented horizontally on a map, such as longitude or easting.", + "required": false, + "style": "form", + "explode": false, + "schema": { + "type": "integer" + } + }, + { + "name": "height", + "in": "query", + "description": "Number of cells across the coverage dimension corresponding to the spatial dimension represented vertically on a 2D map, such as latitude or northing.", + "required": false, + "style": "form", + "explode": false, + "schema": { + "type": "integer" + } + }, { "$ref": "#/components/parameters/subset-crs" }, diff --git a/standard/openapi/parameters/coverages-core/height.yaml b/standard/openapi/parameters/coverages-core/height.yaml new file mode 100644 index 0000000..ac80608 --- /dev/null +++ b/standard/openapi/parameters/coverages-core/height.yaml @@ -0,0 +1,9 @@ +name: height +in: query +description: >- + Number of cells across the coverage dimension corresponding to the spatial dimension represented vertically on a 2D map, such as latitude or northing. +required: false +style: form +explode: false +schema: + type: integer diff --git a/standard/openapi/parameters/coverages-core/width.yaml b/standard/openapi/parameters/coverages-core/width.yaml new file mode 100644 index 0000000..ef2bd9e --- /dev/null +++ b/standard/openapi/parameters/coverages-core/width.yaml @@ -0,0 +1,9 @@ +name: width +in: query +description: >- + Number of cells across the coverage dimension corresponding to the spatial dimension represented horizontally on a map, such as longitude or easting. +required: false +style: form +explode: false +schema: + type: integer diff --git a/standard/openapi/paths/coverages-core/pCoverage.yaml b/standard/openapi/paths/coverages-core/pCoverage.yaml index 5b2aaf9..7434c2f 100644 --- a/standard/openapi/paths/coverages-core/pCoverage.yaml +++ b/standard/openapi/paths/coverages-core/pCoverage.yaml @@ -16,6 +16,8 @@ get: - $ref: '../../parameters/coverages-core/scale-factor.yaml' - $ref: '../../parameters/coverages-core/scale-axes.yaml' - $ref: '../../parameters/coverages-core/scale-size.yaml' + - $ref: '../../parameters/coverages-core/width.yaml' + - $ref: '../../parameters/coverages-core/height.yaml' - $ref: '../../parameters/common-crs/subset-crs.yaml' - $ref: '../../parameters/common-crs/bbox-crs.yaml' - $ref: '../../parameters/common-crs/crs.yaml' diff --git a/standard/requirements/requirements_class_coverage_scaling.adoc b/standard/requirements/requirements_class_coverage_scaling.adoc index 3dbbf1c..895561b 100644 --- a/standard/requirements/requirements_class_coverage_scaling.adoc +++ b/standard/requirements/requirements_class_coverage_scaling.adoc @@ -67,14 +67,27 @@ ^|D |When `scale-size` is used together with subsetting, the requested number of samples SHALL be mapped to the subset dimensions specified, even if those dimensions fall partially outside the extent of the coverage. |=== +==== Parameter `width` and `height` + +[[req_coverage_scaling-width_and_height]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/coverage-scaling/width-and-height* +^|A |For coverages with a spatial dimension corresponding to the horizontal spatial axis as reprsented on a 2D map, such as longitude or easting, the operation SHALL support a parameter `width` for the coverage resource taking an integer parameter corresponding to the number of cells that should be returned along that axis.: +^|B |For coverages with a spatial dimension corresponding to the vertical spatial axis as reprsented on a 2D map, such as latitude or northing, the operation SHALL support a parameter `height` for the coverage resource taking an integer parameter corresponding to the number of cells that should be returned along that axis.: +^|C |The returned coverage SHALL contain exactly the specified number of sample values along each axis which is specified by provided scaling parameters, the original number of sample values for unspecified axes, and any defined server limits. +^|D |When `width` and/or `height` is used together with subsetting, the requested number of samples SHALL be mapped to the subset dimensions specified, even if those dimensions fall partially outside the extent of the coverage. +|=== + ==== Downsampling permission [[per_coverage_scaling-permission]] [width="90%",cols="2,6a"] |=== ^|*Permission {counter:per-id}* |*/per/coverage-scaling/downsampling* -^|A |In the case where a response to a request without a `scale-factor`, `scale-axes` or `scale-size` parameters would be larger than an advertised server limit, an implementation +^|A |In the case where a response to a request without a `scale-factor`, `scale-axes`, `scale-size`, `width`, or `height` parameters would be larger than an advertised server limit, an implementation MAY automatically downsample the coverage to a suitable resolution instead of returning a 4xx client error. +^|B |In the case where a `scale-size`, `scale-axes`, `width` or `height` does not explicitly specify dimensions for all axes of the coverage, an implementation MAY automatically proportionately adjust one or more unspecified dimensions. |=== NOTE: A client retrieving a coverage from an implementation advertising support for this "Scaling" requirements class should explicitly use `scale-factor=1` if it wants to ensure