From 68e90103d0846dd25d1a3b690bb2f3edbb91a409 Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Tue, 16 Mar 2021 20:28:42 +0100 Subject: [PATCH 1/7] clarification on multiple bounding boxes in an extent --- core/standard/clause_7_core.adoc | 32 ++++++++++++++++++- .../core/REQ_fc-md-extent-multi.adoc | 9 ++++++ 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 core/standard/requirements/core/REQ_fc-md-extent-multi.adoc diff --git a/core/standard/clause_7_core.adoc b/core/standard/clause_7_core.adoc index 4d5d23c1..d85ea794 100644 --- a/core/standard/clause_7_core.adoc +++ b/core/standard/clause_7_core.adoc @@ -408,10 +408,40 @@ include::requirements/core/REQ_fc-md-items-links.adoc[] include::requirements/core/REQ_fc-md-extent.adoc[] -NOTE: The member `spatial` only needs to be provided in the `extent` object, if features in the feature collection have spatial properties. The same applies to `temporal` and features with temporal properties. For example, a feature collection where features have a spatial, but no temporal property will only provide the `spatial` member. +The member `spatial` only needs to be provided in the `extent` object, if features in the feature collection have spatial properties. The same applies to `temporal` and features with temporal properties. For example, a feature collection where features have a spatial, but no temporal property will only provide the `spatial` member. + +The spatial and temporal extents support multiple bounding boxes (`bbox` array) and time intervals (`interval` array). + +include::requirements/core/REQ_fc-md-extent-multi.adoc[] include::recomendations/core/REC_fc-md-extent-single.adoc[] +The last requirement and recommendation reflect that most clients will only be interested in a single extent, for example, to set the map view. They will only have to look at the first item in each array. + +At the same time, for some data and for some use cases, a more fine-grained description of the extent will be useful. In that case the first bounding box / time interval is simply the union of all the other bounding boxes / time intervals. + +[[example_4a]] +.Spatial extent with multiple bounding boxes +================= +The following extent represents the United States of America (excluding Territories). The first bounding box of the four bounding boxes is the union of the three other bounding boxes representing the 48 contiguous states, Alaska and Hawaii respectively. + +Note that the overall bounding box as well as the bounding box of Alaska crosses the anti-meridian. + +[source,JSON] +---- +{ + "spatial": { + "bbox": [ + [172.461667, 18.910361, -66.9513812, 71.365162], + [-124.7844079, 24.7433195, -66.9513812, 49.3457868], + [172.461667, 51.214183, -129.979511, 71.365162], + [-178.334698, 18.910361, -154.806773, 28.402123] + ] + } +} +---- +================= + include::recomendations/core/PER_fc-md-extent-extensions.adoc[] [[schema_collection]] diff --git a/core/standard/requirements/core/REQ_fc-md-extent-multi.adoc b/core/standard/requirements/core/REQ_fc-md-extent-multi.adoc new file mode 100644 index 00000000..50a699d5 --- /dev/null +++ b/core/standard/requirements/core/REQ_fc-md-extent-multi.adoc @@ -0,0 +1,9 @@ +[[req_core_fc-md-extent-multi]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/core/fc-md-extent-multi* +^|A |If the `extent` property includes a member `spatial`, each feature in the collection SHALL be inside the extent described by the first bounding box in the `bbox` array. +^|B |If the `extent` property includes a member `spatial`, each feature in the collection SHALL be inside the extent described by one of the other bounding boxes in the `bbox` array. +^|C |If the `extent` property includes a member `temporal`, each feature in the collection SHALL be inside the extent described by the first temporal interval in the `interval` array. +^|D |If the `extent` property includes a member `temporal`, each feature in the collection SHALL be inside the extent described by one of the other temporal intervals in the `interval` array. +|=== From 4be2023231c805cd3dfa7904ff4672ea3b23d843 Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Tue, 16 Mar 2021 20:31:20 +0100 Subject: [PATCH 2/7] amend text --- core/standard/clause_7_core.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/standard/clause_7_core.adoc b/core/standard/clause_7_core.adoc index d85ea794..b79cb4ce 100644 --- a/core/standard/clause_7_core.adoc +++ b/core/standard/clause_7_core.adoc @@ -416,9 +416,9 @@ include::requirements/core/REQ_fc-md-extent-multi.adoc[] include::recomendations/core/REC_fc-md-extent-single.adoc[] -The last requirement and recommendation reflect that most clients will only be interested in a single extent, for example, to set the map view. They will only have to look at the first item in each array. +The last requirement and recommendation reflect that most clients will only be interested in a single extent, for example, to set the map view or a time slider. They will only have to look at the first item in each array. -At the same time, for some data and for some use cases, a more fine-grained description of the extent will be useful. In that case the first bounding box / time interval is simply the union of all the other bounding boxes / time intervals. +At the same time, for some data and for some use cases, a more fine-grained description of the extent will be useful. In that case the first bounding box / time interval is simply the union of all the other bounding boxes / time intervals. Clients can then choose, if they want to use the simpler or the more detailed extent information. [[example_4a]] .Spatial extent with multiple bounding boxes From e1017e970289bf6379afc578d78aad8c50b1d5be Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Wed, 17 Mar 2021 03:39:54 +0100 Subject: [PATCH 3/7] amend text --- core/standard/requirements/core/REQ_fc-md-extent-multi.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/core/standard/requirements/core/REQ_fc-md-extent-multi.adoc b/core/standard/requirements/core/REQ_fc-md-extent-multi.adoc index 50a699d5..aceef275 100644 --- a/core/standard/requirements/core/REQ_fc-md-extent-multi.adoc +++ b/core/standard/requirements/core/REQ_fc-md-extent-multi.adoc @@ -3,7 +3,7 @@ |=== ^|*Requirement {counter:req-id}* |*/req/core/fc-md-extent-multi* ^|A |If the `extent` property includes a member `spatial`, each feature in the collection SHALL be inside the extent described by the first bounding box in the `bbox` array. -^|B |If the `extent` property includes a member `spatial`, each feature in the collection SHALL be inside the extent described by one of the other bounding boxes in the `bbox` array. -^|C |If the `extent` property includes a member `temporal`, each feature in the collection SHALL be inside the extent described by the first temporal interval in the `interval` array. -^|D |If the `extent` property includes a member `temporal`, each feature in the collection SHALL be inside the extent described by one of the other temporal intervals in the `interval` array. +^|B |If the `extent` property includes a member `spatial` and the `bbox` array has more than one item, each feature in the collection SHALL be inside the extent described by one of the other bounding boxes in the `bbox` array. +^|C |If the `extent` property includes a member `temporal`, each feature in the collection SHALL be inside the extent described by the first time interval in the `interval` array. +^|D |If the `extent` property includes a member `temporal` and the `interval` array has more than one item, each feature in the collection SHALL be inside the extent described by one of the other time intervals in the `interval` array. |=== From 87d8c5882777f1e07814d0189df72a3de2dcf3ef Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Wed, 14 Apr 2021 15:48:48 +0200 Subject: [PATCH 4/7] Update text based on the discussion --- core/standard/clause_7_core.adoc | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/core/standard/clause_7_core.adoc b/core/standard/clause_7_core.adoc index b79cb4ce..4d0f6d13 100644 --- a/core/standard/clause_7_core.adoc +++ b/core/standard/clause_7_core.adoc @@ -412,18 +412,22 @@ The member `spatial` only needs to be provided in the `extent` object, if featur The spatial and temporal extents support multiple bounding boxes (`bbox` array) and time intervals (`interval` array). +The first bounding box/time interval always describes the overall spatial/temporal extent of the data. All subsequent bounding boxes and time intervals can be used to provide a more precise description of the extent and identify clusters of data. Clients only interested in the overall extent will only access the first item in each array. + +The `bbox` and `interval` properties will typically be derived automatically from the feature data and be the exact minimal bounding box / time interval containing the features in the collection (or cluster). + include::requirements/core/REQ_fc-md-extent-multi.adoc[] include::recomendations/core/REC_fc-md-extent-single.adoc[] The last requirement and recommendation reflect that most clients will only be interested in a single extent, for example, to set the map view or a time slider. They will only have to look at the first item in each array. -At the same time, for some data and for some use cases, a more fine-grained description of the extent will be useful. In that case the first bounding box / time interval is simply the union of all the other bounding boxes / time intervals. Clients can then choose, if they want to use the simpler or the more detailed extent information. +At the same time, for some data and for some use cases, a more fine-grained description of the extent will be useful. In that case the first bounding box / time interval is a union of all the other bounding boxes / time intervals. Clients can then choose, if they want to use the simpler or the more detailed extent information. [[example_4a]] .Spatial extent with multiple bounding boxes ================= -The following extent represents the United States of America (excluding Territories). The first bounding box of the four bounding boxes is the union of the three other bounding boxes representing the 48 contiguous states, Alaska and Hawaii respectively. +The following extent can describe feature data in the United States of America (excluding Territories). The first bounding box of the four bounding boxes is the union of the three other bounding boxes representing the 48 contiguous states, Alaska and Hawaii respectively - from the west-bound longitude of Alaska to the east-bound longitude of the 48 contiguous states. Note that the overall bounding box as well as the bounding box of Alaska crosses the anti-meridian. @@ -442,6 +446,8 @@ Note that the overall bounding box as well as the bounding box of Alaska crosses ---- ================= +As can be seen in the example, there can be multiple ways how to construct the overall bounding box from its component bounding boxes since longitudes are cyclic (that is, -180° is equal to 180°). Another union of the component bounding boxes for the 48 contiguous states, Alaska and Hawaii would be `[-124.7844079, 18.910361, -129.979511, 71.365162]` - from the west-bound longitude of the 48 contiguous states to the east-bound longitude of Alaska. The typical approach in such cases is to select the option with the smallest area, as it was done in the example. + include::recomendations/core/PER_fc-md-extent-extensions.adoc[] [[schema_collection]] From 84967da7191126ba53dd6854227253112567c2a3 Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Wed, 14 Apr 2021 17:58:33 +0200 Subject: [PATCH 5/7] Update extent.yaml Thanks for the proposal, @m-mohr ! --- core/openapi/schemas/extent.yaml | 33 +++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/core/openapi/schemas/extent.yaml b/core/openapi/schemas/extent.yaml index 4d0af778..15eb38d9 100644 --- a/core/openapi/schemas/extent.yaml +++ b/core/openapi/schemas/extent.yaml @@ -2,6 +2,12 @@ description: |- The extent of the features in the collection. In the Core only spatial and temporal extents are specified. Extensions may add additional members to represent other extents, for example, thermal or pressure ranges. + + The first items in the arrays always describe the overall extent of + the data. All subsequent extents can be used to provide a more precise + description of the extent and identify clusters of data. + Clients only interested in the overall extent will only need to + access the first item in each array. type: object properties: spatial: @@ -12,9 +18,15 @@ properties: bbox: description: |- One or more bounding boxes that describe the spatial extent of the dataset. - In the Core only a single bounding box is supported. Extensions may support - additional areas. If multiple areas are provided, the union of the bounding - boxes describes the spatial extent. + In the Core only a single bounding box is supported. + + Extensions may support additional areas. + The first bounding box always describes the overall spatial + extent of the data. All subsequent bounding boxes can be + used to provide a more precise description of the extent and + identify clusters of data. + Clients only interested in the overall spatial extent will + only need to access the first item in each array. type: array minItems: 1 items: @@ -83,10 +95,15 @@ properties: interval: description: |- One or more time intervals that describe the temporal extent of the dataset. - The value `null` is supported and indicates an open time interval. - In the Core only a single time interval is supported. Extensions may support - multiple intervals. If multiple intervals are provided, the union of the - intervals describes the temporal extent. + In the Core only a single time interval is supported. + + Extensions may support multiple intervals. + The first time interval always describes the overall + temporal extent of the data. All subsequent time intervals + can be used to provide a more precise description of the + extent and identify clusters of data. + Clients only interested in the overall extent will only need + to access the first item in each array. type: array minItems: 1 items: @@ -94,6 +111,8 @@ properties: Begin and end times of the time interval. The timestamps are in the temporal coordinate reference system specified in `trs`. By default this is the Gregorian calendar. + + The value `null` is supported and indicates an open time interval. type: array minItems: 2 maxItems: 2 From 2c3a58b2834639ac83642c0eab706243f299051a Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Wed, 14 Apr 2021 21:20:06 +0200 Subject: [PATCH 6/7] update with proposed changes from STAC see https://github.com/radiantearth/stac-api-spec/pull/117 cc @m-mohr @philvarner --- core/openapi/schemas/extent.yaml | 20 +++++++++----------- core/standard/clause_7_core.adoc | 2 +- 2 files changed, 10 insertions(+), 12 deletions(-) diff --git a/core/openapi/schemas/extent.yaml b/core/openapi/schemas/extent.yaml index 15eb38d9..e515f6af 100644 --- a/core/openapi/schemas/extent.yaml +++ b/core/openapi/schemas/extent.yaml @@ -3,9 +3,9 @@ description: |- extents are specified. Extensions may add additional members to represent other extents, for example, thermal or pressure ranges. - The first items in the arrays always describe the overall extent of - the data. All subsequent extents can be used to provide a more precise - description of the extent and identify clusters of data. + The first item in the array describes the overall extent of + the data. All subsequent items describe more precise extents, + e.g., to identify clusters of data. Clients only interested in the overall extent will only need to access the first item in each array. type: object @@ -21,10 +21,9 @@ properties: In the Core only a single bounding box is supported. Extensions may support additional areas. - The first bounding box always describes the overall spatial - extent of the data. All subsequent bounding boxes can be - used to provide a more precise description of the extent and - identify clusters of data. + The first bounding box describes the overall spatial + extent of the data. All subsequent bounding boxes describe + more precise bounding boxes, e.g., to identify clusters of data. Clients only interested in the overall spatial extent will only need to access the first item in each array. type: array @@ -98,10 +97,9 @@ properties: In the Core only a single time interval is supported. Extensions may support multiple intervals. - The first time interval always describes the overall - temporal extent of the data. All subsequent time intervals - can be used to provide a more precise description of the - extent and identify clusters of data. + The first time interval describes the overall + temporal extent of the data. All subsequent time intervals describe + more precise time intervals, e.g., to identify clusters of data. Clients only interested in the overall extent will only need to access the first item in each array. type: array diff --git a/core/standard/clause_7_core.adoc b/core/standard/clause_7_core.adoc index 4d0f6d13..1144f6f1 100644 --- a/core/standard/clause_7_core.adoc +++ b/core/standard/clause_7_core.adoc @@ -412,7 +412,7 @@ The member `spatial` only needs to be provided in the `extent` object, if featur The spatial and temporal extents support multiple bounding boxes (`bbox` array) and time intervals (`interval` array). -The first bounding box/time interval always describes the overall spatial/temporal extent of the data. All subsequent bounding boxes and time intervals can be used to provide a more precise description of the extent and identify clusters of data. Clients only interested in the overall extent will only access the first item in each array. +The first bounding box/time interval describes the overall spatial/temporal extent of the data. All subsequent bounding boxes and time intervals describe more precise extents, e.g., to identify clusters of data. Clients only interested in the overall extent will only access the first item in each array. The `bbox` and `interval` properties will typically be derived automatically from the feature data and be the exact minimal bounding box / time interval containing the features in the collection (or cluster). From fe231b6ca89327bd220a7f733911a97ac4fa9c9f Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Tue, 27 Apr 2021 17:27:58 +0200 Subject: [PATCH 7/7] update sentence as suggested --- core/standard/clause_7_core.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/standard/clause_7_core.adoc b/core/standard/clause_7_core.adoc index 1144f6f1..f421d7d0 100644 --- a/core/standard/clause_7_core.adoc +++ b/core/standard/clause_7_core.adoc @@ -446,7 +446,7 @@ Note that the overall bounding box as well as the bounding box of Alaska crosses ---- ================= -As can be seen in the example, there can be multiple ways how to construct the overall bounding box from its component bounding boxes since longitudes are cyclic (that is, -180° is equal to 180°). Another union of the component bounding boxes for the 48 contiguous states, Alaska and Hawaii would be `[-124.7844079, 18.910361, -129.979511, 71.365162]` - from the west-bound longitude of the 48 contiguous states to the east-bound longitude of Alaska. The typical approach in such cases is to select the option with the smallest area, as it was done in the example. +As can be seen in the example, there can be multiple ways to construct the overall bounding box from its component bounding boxes since longitudes are cyclic (that is, -180° is equal to 180°). Another union of the component bounding boxes for the 48 contiguous states, Alaska and Hawaii would be `[-124.7844079, 18.910361, -129.979511, 71.365162]` - from the west-bound longitude of the 48 contiguous states to the east-bound longitude of Alaska. The typical approach in such cases is to select the option with the smallest area, as was done in the example. include::recomendations/core/PER_fc-md-extent-extensions.adoc[]