Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarification on multiple bounding boxes in an extent #520

Merged
merged 7 commits into from
Apr 27, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions core/openapi/schemas/extent.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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 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
properties:
spatial:
Expand All @@ -12,9 +18,14 @@ 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 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
minItems: 1
items:
Expand Down Expand Up @@ -83,17 +94,23 @@ 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 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
minItems: 1
items:
description: |-
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
Expand Down
38 changes: 37 additions & 1 deletion core/standard/clause_7_core.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -408,10 +408,46 @@ 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).

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).

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 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 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.

[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]
]
}
}
----
=================

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[]

[[schema_collection]]
Expand Down
9 changes: 9 additions & 0 deletions core/standard/requirements/core/REQ_fc-md-extent-multi.adoc
Original file line number Diff line number Diff line change
@@ -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` 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.
|===