From 2dc662ea2fe7abc1bdac19d584d8aecf9658bdb9 Mon Sep 17 00:00:00 2001 From: joanma747 Date: Sun, 30 Oct 2022 20:21:50 +0100 Subject: [PATCH] decorations req. class added in response to issue #97 --- core/standard/20-058.adoc | 2 + core/standard/clause_2_conformance.adoc | 12 +++++ core/standard/clause_7b_map_decorations.adoc | 52 +++++++++++++++++++ .../REQ_attribution-definition.adoc | 27 ++++++++++ .../decorations/REQ_compass-definition.adoc | 27 ++++++++++ .../decorations/REQ_crs-grid-definition.adoc | 17 ++++++ .../decorations/REQ_graticule-definition.adoc | 17 ++++++ .../decorations/REQ_legend-definition.adoc | 27 ++++++++++ .../decorations/REQ_map-success.adoc | 6 +++ .../decorations/REQ_map-title-definition.adoc | 27 ++++++++++ .../decorations/REQ_scale-bar-definition.adoc | 27 ++++++++++ .../REQ_situation-map-definition.adoc | 27 ++++++++++ .../requirements_class_decorations.adoc | 8 +++ .../scaling/REQ_cell-size-definition.adoc | 1 - .../scaling/REQ_height-definition.adoc | 1 - .../requirements/scaling/REQ_map-success.adoc | 2 +- .../scaling/REQ_width-definition.adoc | 1 - 17 files changed, 277 insertions(+), 4 deletions(-) create mode 100644 core/standard/clause_7b_map_decorations.adoc create mode 100644 core/standard/requirements/decorations/REQ_attribution-definition.adoc create mode 100644 core/standard/requirements/decorations/REQ_compass-definition.adoc create mode 100644 core/standard/requirements/decorations/REQ_crs-grid-definition.adoc create mode 100644 core/standard/requirements/decorations/REQ_graticule-definition.adoc create mode 100644 core/standard/requirements/decorations/REQ_legend-definition.adoc create mode 100644 core/standard/requirements/decorations/REQ_map-success.adoc create mode 100644 core/standard/requirements/decorations/REQ_map-title-definition.adoc create mode 100644 core/standard/requirements/decorations/REQ_scale-bar-definition.adoc create mode 100644 core/standard/requirements/decorations/REQ_situation-map-definition.adoc create mode 100644 core/standard/requirements/requirements_class_decorations.adoc diff --git a/core/standard/20-058.adoc b/core/standard/20-058.adoc index 8512f7cf..e073c196 100644 --- a/core/standard/20-058.adoc +++ b/core/standard/20-058.adoc @@ -98,6 +98,8 @@ include::clause_7_map_core.adoc[] include::clause_7a_map_background.adoc[] +include::clause_7b_map_decorations.adoc[] + include::clause_8_map_tilesetsList.adoc[] include::clause_9_map_paramCollectionsSelection.adoc[] diff --git a/core/standard/clause_2_conformance.adoc b/core/standard/clause_2_conformance.adoc index 4b1bd567..e9b101fe 100644 --- a/core/standard/clause_2_conformance.adoc +++ b/core/standard/clause_2_conformance.adoc @@ -47,6 +47,18 @@ The _maps background_ conformance class allows requesting a particular backgroun |Map |`/map?bgcolor={bgcolor}&transparent={transparent},...` |=== +*<>* (http://www.opengis.net/spec/ogcapi-maps-1/1.0/req/decorations) + +The _maps decorations_ conformance class allows adding a title, a legend, a scale bar, a compass, a situation map, an attribution text a lat/long graticule, and a CRS grid directly on top of a map. + +[#table_resource_decorations,reftext='{table-caption} {counter:table-num}'] +.Overview of resource and common direct links that corresponds to the decorations +[cols="33,66",options="header"] +|=== +|Resource name |Example of possible paths +|Map |`/map?map-title={map-title}&legend={legend}&scale-bar={scale-bar}&compass={compass}&situation-map={situation-map}&graticule={graticule}&crs-grid={crs-grid}&attribution=attribution...` +|=== + *<>* (http://www.opengis.net/spec/ogcapi-maps-1/1.0/req/collections-selection) The _maps geodata selection_ conformance class allows to list specific geospatial data resources from which to retrieve maps. diff --git a/core/standard/clause_7b_map_decorations.adoc b/core/standard/clause_7b_map_decorations.adoc new file mode 100644 index 00000000..1a5aee51 --- /dev/null +++ b/core/standard/clause_7b_map_decorations.adoc @@ -0,0 +1,52 @@ +[[rc_decorations]] +== Requirement Class "Map Decorations" + +=== Overview + +[[background-overview]] + +include::requirements/requirements_class_decorations.adoc[] + +This requirement class describes parameters to add a title, a legend, a scale bar, a compass, a situation map, an attribution text or logo, a lat/long graticule, and a CRS grid to the map. + +NOTE: The work "element" or "parts" normally designates the previous enumerations. However "element" is used in many other contexts so the authors decided to call the "decorations" in this section. + +Many of these decorations can be better generated by the client that shows the map, so these parameters are reserved to create maps that are going to be used as static illustrations (e.g. as images in web pages). If the map is going to be presented alone as an illustration, these decorations could be make the map more informative and more "cartographic" (see for example https://reference.yourdictionary.com/resources/5-basic-parts-of-any-map.html). When a map is going to be presented overlaid with other maps these elements may interfere and collide, impeding the correct visualization or the result and are not recommended. + +=== Map operation + +The map core of this standard defines how to get a map. This requirements class specifies parameters to add some decorations on top of it + +==== Parameters for map decorations +The title, legend, scale-bar, compass, situation-map, attribution, graticule and crs-grid, parameters indicate if and where the decorations elements will be situated on top of the map. + +include::requirements/decorations/REQ_title-definition.adoc[] + +NOTE: The style and size of the text of the title is at complete discretion of the server + +include::requirements/decorations/REQ_legend-definition.adoc[] + +include::requirements/decorations/REQ_scale-bar-definition.adoc[] + +include::requirements/decorations/REQ_compass-definition.adoc[] + +NOTE: It is up to de server to decide how the compass can look like being some possibilities a full wind rose or a simple arrow to the north. + +include::requirements/decorations/REQ_situation-map-definition.adoc[] + +include::requirements/decorations/REQ_attribution-definition.adoc[] + +NOTE: The attribution may be represented as a text naming the responsible party of the data represented in the map or a logo of the responsible party organzation. + +REQ_include::requirements/decorations/graticule-definition.adoc[] + +NOTE: A graticule is a network of lines on a map that delineate the geographic expressed as lines of equal latitude or longitude (a.k.a. meridians and parallels). A graticule added to a map in a lat/long CRS (such as CRS:84) will appear as a set of vertical and horizontal strait lines. In other CRSs, meridians a parallels may result in curbed lines. + +include::requirements/decorations/REQ_crs-grid-definition.adoc[] + +NOTE: A CRS grid is a network of lines on a map that delineate the CRS coordinates expressed as lines of equal X or Y. A CRS grid added results in a set of vertical and horizontal strait lines. + +==== Response +A successful GET response is described in the core class (http://www.opengis.net/spec/ogcapi-maps-1/1.0/conf/core) + +include::requirements/decorations/REQ_map-success.adoc[] diff --git a/core/standard/requirements/decorations/REQ_attribution-definition.adoc b/core/standard/requirements/decorations/REQ_attribution-definition.adoc new file mode 100644 index 00000000..378d9a25 --- /dev/null +++ b/core/standard/requirements/decorations/REQ_attribution-definition.adoc @@ -0,0 +1,27 @@ +[[req_decorations_attribution-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/attribution-definition* +^|A |The map operation SHALL support an optional parameter `attribution` with the characteristics defined in the OpenAPI Specification 3.0 fragment +[source,YAML] +---- + name: attribution + in: query + description: Add a attribution into the map + style: form + schema: + type: string + enum: + - none + - topLeft + - topCenter + - topRight + - middleLeft + - middleRight + - bottomLeft + - bottomCenter + - bottomRight + default: none +---- +^|B |The absence of the parameter `attribution` or the value `none` SHALL be interpreted as "no attribution in the map". Other values SHALL be interpreted as the position where the attribution should appear +|=== diff --git a/core/standard/requirements/decorations/REQ_compass-definition.adoc b/core/standard/requirements/decorations/REQ_compass-definition.adoc new file mode 100644 index 00000000..4785a346 --- /dev/null +++ b/core/standard/requirements/decorations/REQ_compass-definition.adoc @@ -0,0 +1,27 @@ +[[req_decorations_compass-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/compass-definition* +^|A |The map operation SHALL support an optional parameter `compass` with the characteristics defined in the OpenAPI Specification 3.0 fragment +[source,YAML] +---- + name: compass + in: query + description: Add a compass into the map + style: form + schema: + type: string + enum: + - none + - topLeft + - topCenter + - topRight + - middleLeft + - middleRight + - bottomLeft + - bottomCenter + - bottomRight + default: none +---- +^|B |The absence of the parameter `compass` or the value `none` SHALL be interpreted as "no compass in the map". Other values SHALL be interpreted as the position where the compass should appear +|=== diff --git a/core/standard/requirements/decorations/REQ_crs-grid-definition.adoc b/core/standard/requirements/decorations/REQ_crs-grid-definition.adoc new file mode 100644 index 00000000..d47273d3 --- /dev/null +++ b/core/standard/requirements/decorations/REQ_crs-grid-definition.adoc @@ -0,0 +1,17 @@ +[[req_decorations_crs-grid-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/crs-grid-definition* +^|A |The map operation SHALL support an optional parameter `crs-grid` with the characteristics defined in the OpenAPI Specification 3.0 fragment +[source,YAML] +---- + name: crs-grid + in: query + description: Add a crs-grid into the map + style: form + schema: + type: boolean + default: false +---- +^|B |The absence of the parameter `crs-grid` or the value `false` SHALL be interpreted as "no CRS grid in the map". +|=== diff --git a/core/standard/requirements/decorations/REQ_graticule-definition.adoc b/core/standard/requirements/decorations/REQ_graticule-definition.adoc new file mode 100644 index 00000000..cf348130 --- /dev/null +++ b/core/standard/requirements/decorations/REQ_graticule-definition.adoc @@ -0,0 +1,17 @@ +[[req_decorations_graticule-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/graticule-definition* +^|A |The map operation SHALL support an optional parameter `graticule` with the characteristics defined in the OpenAPI Specification 3.0 fragment +[source,YAML] +---- + name: graticule + in: query + description: Add a graticule into the map + style: form + schema: + type: boolean + default: false +---- +^|B |The absence of the parameter `graticule` or the value `false` SHALL be interpreted as "no graticule in the map". +|=== diff --git a/core/standard/requirements/decorations/REQ_legend-definition.adoc b/core/standard/requirements/decorations/REQ_legend-definition.adoc new file mode 100644 index 00000000..9409eef3 --- /dev/null +++ b/core/standard/requirements/decorations/REQ_legend-definition.adoc @@ -0,0 +1,27 @@ +[[req_decorations_legend-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/legend-definition* +^|A |The map operation SHALL support an optional parameter `legend` with the characteristics defined in the OpenAPI Specification 3.0 fragment +[source,YAML] +---- + name: legend + in: query + description: Add a legend into the map + style: form + schema: + type: string + enum: + - none + - topLeft + - topCenter + - topRight + - middleLeft + - middleRight + - bottomLeft + - bottomCenter + - bottomRight + default: none +---- +^|B |The absence of the parameter `legend` or the value `none` SHALL be interpreted as "no legend in the map". Other values SHALL be interpreted as the position where the legend should appear +|=== diff --git a/core/standard/requirements/decorations/REQ_map-success.adoc b/core/standard/requirements/decorations/REQ_map-success.adoc new file mode 100644 index 00000000..89df6c9d --- /dev/null +++ b/core/standard/requirements/decorations/REQ_map-success.adoc @@ -0,0 +1,6 @@ +[[req_decorations_map-success]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/map-success* +^|A |In the case of raster image media type (e.g. image/jpeg or image/png) the number of columns and rows SHALL be exactly the ones specified in the `width` and `height` parameters respectively. +|=== diff --git a/core/standard/requirements/decorations/REQ_map-title-definition.adoc b/core/standard/requirements/decorations/REQ_map-title-definition.adoc new file mode 100644 index 00000000..cf0b9af6 --- /dev/null +++ b/core/standard/requirements/decorations/REQ_map-title-definition.adoc @@ -0,0 +1,27 @@ +[[req_decorations_map-title-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/map-title-definition* +^|A |The map operation SHALL support an optional parameter `map-title` with the characteristics defined in the OpenAPI Specification 3.0 fragment +[source,YAML] +---- + name: map-title + in: query + description: a title into the map + style: form + schema: + type: string + enum: + - none + - topLeft + - topCenter + - topRight + - middleLeft + - middleRight + - bottomLeft + - bottomCenter + - bottomRight + default: none +---- +^|B |The absence of the parameter `map-title` or the value `none` SHALL be interpreted as "no title in the map". Other values SHALL be interpreted as the position where the title should appear +|=== diff --git a/core/standard/requirements/decorations/REQ_scale-bar-definition.adoc b/core/standard/requirements/decorations/REQ_scale-bar-definition.adoc new file mode 100644 index 00000000..cd74cf39 --- /dev/null +++ b/core/standard/requirements/decorations/REQ_scale-bar-definition.adoc @@ -0,0 +1,27 @@ +[[req_decorations_scale-bar-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/scale-bar-definition* +^|A |The map operation SHALL support an optional parameter `scale-bar` with the characteristics defined in the OpenAPI Specification 3.0 fragment +[source,YAML] +---- + name: scale-bar + in: query + description: Add a scale bar into the map + style: form + schema: + type: string + enum: + - none + - topLeft + - topCenter + - topRight + - middleLeft + - middleRight + - bottomLeft + - bottomCenter + - bottomRight + default: none +---- +^|B |The absence of the parameter `scale-bar` or the value `none` SHALL be interpreted as "no scale bar in the map". Other values SHALL be interpreted as the position where the scale bar should appear +|=== diff --git a/core/standard/requirements/decorations/REQ_situation-map-definition.adoc b/core/standard/requirements/decorations/REQ_situation-map-definition.adoc new file mode 100644 index 00000000..21ae8006 --- /dev/null +++ b/core/standard/requirements/decorations/REQ_situation-map-definition.adoc @@ -0,0 +1,27 @@ +[[req_decorations_situation-map-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/decorations/situation-map-definition* +^|A |The map operation SHALL support an optional parameter `situation-map` with the characteristics defined in the OpenAPI Specification 3.0 fragment +[source,YAML] +---- + name: situation-map + in: query + description: Add a situation-map into the map + style: form + schema: + type: string + enum: + - none + - topLeft + - topCenter + - topRight + - middleLeft + - middleRight + - bottomLeft + - bottomCenter + - bottomRight + default: none +---- +^|B |The absence of the parameter `situation-map` or the value `none` SHALL be interpreted as "no situation map is required in the map". Other values SHALL be interpreted as the position where the situation map should appear +|=== diff --git a/core/standard/requirements/requirements_class_decorations.adoc b/core/standard/requirements/requirements_class_decorations.adoc new file mode 100644 index 00000000..901f5a20 --- /dev/null +++ b/core/standard/requirements/requirements_class_decorations.adoc @@ -0,0 +1,8 @@ +[[rc_maps-decorations]] +[cols="1,4",width="90%"] +|=== +2+|*Requirements Class Decorations* +2+|http://www.opengis.net/spec/ogcapi-maps-1/1.0/req/decorations +|Target type |Web API +|Dependency |http://www.opengis.net/spec/ogcapi-maps-1/1.0/req/core +|=== diff --git a/core/standard/requirements/scaling/REQ_cell-size-definition.adoc b/core/standard/requirements/scaling/REQ_cell-size-definition.adoc index c2fb8146..43f5d659 100644 --- a/core/standard/requirements/scaling/REQ_cell-size-definition.adoc +++ b/core/standard/requirements/scaling/REQ_cell-size-definition.adoc @@ -12,7 +12,6 @@ cell size of the viewport to present the response in millimeters. required: false style: form - explode: false schema: type: number ---- diff --git a/core/standard/requirements/scaling/REQ_height-definition.adoc b/core/standard/requirements/scaling/REQ_height-definition.adoc index e8cebcf9..aac6794a 100644 --- a/core/standard/requirements/scaling/REQ_height-definition.adoc +++ b/core/standard/requirements/scaling/REQ_height-definition.adoc @@ -12,7 +12,6 @@ Height of the viewport to present the response in pixel units (the map subset). required: false style: form - explode: false schema: type: number ---- diff --git a/core/standard/requirements/scaling/REQ_map-success.adoc b/core/standard/requirements/scaling/REQ_map-success.adoc index c462be48..e6b4ce4a 100644 --- a/core/standard/requirements/scaling/REQ_map-success.adoc +++ b/core/standard/requirements/scaling/REQ_map-success.adoc @@ -2,5 +2,5 @@ [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/scaling/map-success* -^|A |In the case of raster image media type (e.g. image/jpeg or image/png) the number of columns and rows SHALL be exactly the ones specified in the `width` and `height` parameters respectively. +^|A |The map SHALL include the decorations requested and in the requested position. |=== diff --git a/core/standard/requirements/scaling/REQ_width-definition.adoc b/core/standard/requirements/scaling/REQ_width-definition.adoc index 5486f8e7..757a2cab 100644 --- a/core/standard/requirements/scaling/REQ_width-definition.adoc +++ b/core/standard/requirements/scaling/REQ_width-definition.adoc @@ -12,7 +12,6 @@ Width of the viewport to present the response in pixel units (the map subset). required: false style: form - explode: false schema: type: number ----