Clarification on multiple bounding boxes in an extent

[cportele]

See #518 for the background of this pull request.

The spatial and temporal extents support multiple bounding boxes (bbox array) and time intervals (interval array). This was intended as an extension point for the future and Features Core recommends to use only one item in both arrays.

This pull request adds a new requirement to clarify the content of these arrays in cases with multiple bboxes/intervals: the first bbox/interval would always describe the complete spatial/temporal extent and the other ones will be the more precise extent description. The goal is to support both clients only interested in a single bbox/interval and those that can handle more.

An example: 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.

{
  "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] 
    ]
  }
}

This change is intended as a clarification. While this pull request adds a new requirement, the proposed change should not break any existing implementation or deployment, because currently all deployments that we were aware of in the SWG discussion on 2021-03-15 are all using a single bbox / interval only. I looked at a number of deployments and did not find one that uses more than one item in the arrays.

If that is the case, which we need to verify, this is probably the time to make the change since the clarified wording supports both clients that only want to overall extent and those that can handle extents with multiple areas / time intervals, while the current wording may lead to interoperability issues as described in #518.

If it turns out that there are already deployments that are not consistent with the proposed requirement, we should keep the clarification, but downgrade it to a recommendation.

The STAC Collection spec would also need to be updated with the clarification.

[m-mohr]

In STAC we allowed multiple extents being used in 0.9.0 (see PR radiantearth/stac-spec#856). This got also inherited into the openEO specification then, which would also need to change.

STAC allowed it for a use-case by @davidraleigh so there's at least one server-side implementation, but I haven't seen many more so far.

On the client-side at least STAC Browser and openEO tooling implement that the extents are all shown on a map. The clarification would lead to a strange visualization with the overall bounding box overlapping the "sub bounding boxes". Not ideal, but I guess that is also not a deal-breaker.

[cportele]

Thanks very much @m-mohr for the research and the feedback on the current use of the extents, very helpful.

If there is any feedback from the STAC/openEO community, if such a change would be helpful guidance for clients going forward, that would be of interest, too. If that is not the case, I would say that the SWG should look at this again and see, if we can come up with a solution that addresses the concerns from both STAC and OGC API Common.

[m-mohr]

Not yet, we still have to discuss the issue. I hopefully have some more details about it End of March (after vacation).

[cholmes]

@cportele - sorry for the slow response. We'll huddle with the STAC community. My take is that we're at a time where it's possible for us to entertain a change, as we are just before 1.0.0, but we've been trying to be not rock the boat much at all during the release candidate process. But this does feel like a pretty minor clarification, and one that seems beneficial.

Post 1.0 I think we're locked in and I don't think it'd be good to change, as our Collection is based on the OGC Collection, and want them to stay in lock-step and wouldn't want a behavior change.

But @m-mohr is our main implementor for affected tools, working on both OpenEO and STAC Browser, so I defer to him. I can try to reach out and check with David R.

[RogerLott]

This is an observation that is not directly related to the question of multiple bounding boxes, but associated to the comment above.

In the example given above by @cportele there seems to be a typo in the westBoundLongitude of the main bbox which, assuming the values for the three component boxes are correct, I think should be
[-178.334698, 18.910361, -66.9513812, 71.365162]

But it begs the question as to how do you construct an embracing box around multiple boxes. When the antimeridian is crossed, just taking the minimum and maximum longitude values is insufficient.

ISO 19115 requires bbox longitudes to be in the range -180 <= longitude <= +180 degrees. There is a general question of treatment of boxes that cross the antimeridian. (This may be a separate issue)
A suggested interpretation is: "start from lower bound longitude λ₁, then move [eastwards] through increasing longitude values until we reach λ₂". This assumes that longitude is positive eastwards. In the −180° =< λ =< +180° range, if λ1 < λ2 then the bbox does not cross the 180° meridian, if λ1 > λ2 then the bbox crosses the 180° meridian.
Has that been standardised anywhere?

[m-mohr]

@cportele openEO is happy to adopt the change, but we are also concerned about the antimeridian issue.

I can also implement it for the STAC tools I'm maintaining, but not sure about the other tools. @cholmes was going to ask for it...

[rcoup]

@RogerLott AFAIK west/east is always the definition, not min/max: https://github.com/opengeospatial/ogcapi-features/blob/master/core/standard/clause_7_core.adoc#user-content-parameter-bbox

[RogerLott]

@rcoup - for bounding box, yes, east/west. ISO 19115-1 uses westBoundLongitude, eastBoundLongitude, southBoundLatitude and northBoundLatitude; API - Features shortens these to westBoundLon, eastBoundLon, southBoundLat and northBoundLat. (I am not sure that ave two different strings helps standardization, but that is a seperate issue).
My suggestion for minimum/maximum applies to envelope, not bbox, and is eneral so can accomodate circumstances when there is no east or west and is multidimensional. lowerBound[Corner] and upperbound would achieve the same.

[cportele]

@RogerLott - sorry, I missed your original comment, but thanks to the discussion I have now seen it.

In the example given above by @cportele there seems to be a typo in the westBoundLongitude of the main bbox which, assuming the values for the three component boxes are correct, I think should be [-178.334698, 18.910361, -66.9513812, 71.365162]

I don't think so. 172.461667 is west of -178.334698.

But it begs the question as to how do you construct an embracing box around multiple boxes. When the antimeridian is crossed, just taking the minimum and maximum longitude values is insufficient.

If the component boxes do not have overlapping longitude values, there can be multiple ways how to define the embracing box. If I have a dataset with data in Japan, Germany and Chile, which one do I use:

• west-bound longitude of Japan to east-bound longitude of Germany
• west-bound longitude of Chile to east-bound longitude of Japan
• west-bound longitude of Germany to east-bound longitude of Chile

All options are a single bbox that contains the three country bboxes. Do we want to prescribe which one must be used? Which one, the one with the smallest area? I think we should leave that decision to the provider.

In the US example there is no option as the three boxes have overlapping longitudes.

The anti-meridian is crossed, if the west-bound longitude is larger than the east-bound longitude. This is stated in the text above example 5.

Or am I missing something?

[cportele]

API - Features shortens these to westBoundLon, eastBoundLon, southBoundLat and northBoundLat.

@RogerLott - Where are these tokens used in OGC API - Features? I don't remember them.

[cportele]

@m-mohr - Thanks for the response 👍 . Could you clarify the concern with respect to the antimeridian? It seems that I am ignoring something, but I do not understand what the issue is.

[RogerLott]

@cportele said "172.461667 is west of -178.334698". Are you sure about that? -178 seems to me to be less than +172.

"In the US example there is no option as the three boxes have overlapping longitudes". I would suggest that in the US example the fact that the individual boxes ovrrlap is irrelevant. If you are describing the 50 states of the US then your north-up box needs to be centred on the US regardless of longitude, and then you take the left edge of the leftmost box as west and the right edge of the righmost box as east. To me that seems the only logical option - because you are describing one entity having three parts.

But take Russia including the enclave of Kaliningrad. One entity, two boxes. Kaliningrad longitude is approximately +19.2 to +23.4. Russia proper from +26.5 through +179.9 across the antimeridian to -169. The minimum is -169, maximum +26.5. To describe a bounding box for one entity, Russia, as from -169 in the west across Canada, Greenland and the Atlantic to 26.5 in the east would (in my view) be perverse, and more importantly it would fail to meet the API Common requirement to includes a coordinate that is part of the (spatial) geometry of the resource. Russia's extent is from +19.2 in the west across Siberia to -169 in the east.

Three boxes related only by being in the same dataset - Chile, Germany, Japan - does not have the same logic of there being one entity with multiple parts. Now we have three separate entities. It does not really matter how your overall box is described, but if you are using 19115-1's bounding box with its prescribed longitude range of -180 to +180 then logic suggests you take the western longitude of the western entity (Chile) as west and the eastern longitude of the eastern entity (Japan) as east. This does not cross the antimeridian and there is no issue.

So I suggest that the logic is to put a north-up box around a dataset with the norhern edge centred on the dataset. then find the left-most and right-most longitudes from this. The critical issue is to be dataset-specific in constructing this box, in the first instance ignoring longitudes, then get the longitude values. I don't think you can correctly construct an overall box simply by examining the values of component boxes.

[rcoup]

-178 seems to me to be less than +172.

uh huh, but "smaller number" is different from "west", and "larger number" is different from "east". It's a sphere, you can head either east or west to get from one point to another... so we can't use minimum and maximum longitude values (except possibly as a tie-breaker).

Minimum area is probably the most deterministic approach to calculate it IMO.

For your Russia example:

• +19.2° → +23.4° = 4.2° wide
• +26.5° → -169° = 164.5° wide

Leading to bbox options:

• A) +19.2° → -169° = 188.2° wide
• B) +26.5° → +23.4° = 356.9° wide
• A < B so A is preferred

Do we want to prescribe which one must be used? Which one, the one with the smallest area? I think we should leave that decision to the provider.

Recommend but not prescribe the smallest area approach?

[cportele]

@rcoup

Recommend but not prescribe the smallest area approach?

That would work for me. I will wait a bit to see, if there are objections or concerns to this. If not, I will add this to the PR.

@RogerLott

I am beginning to think that we may be talking about different things.

I would suggest that in the US example the fact that the individual boxes overlap is irrelevant.
...
To me that seems the only logical option - because you are describing one entity having three parts.
...
Three boxes related only by being in the same dataset - Chile, Germany, Japan - does not have the same logic of there being one entity with multiple parts.
...
I don't think you can correctly construct an overall box simply by examining the values of component boxes.

I do not understand what "entity" means in this context. This pull request is about the spatial extent of a feature collection, where the current requirement is that each feature must be inside the bounding boxes describing the spatial extent. In the US example the features in the collection could be the states or any other set of features that are located in the US. The Chile/Germany/Japan example was not about three features but about some hypothetical collection of features where all features are located in one of the three countries.

A bounding box in WGS 84 longitude/latitude consists of four numbers, the west-bound longitude, the south-bound latitude, the east-bound longitude and the north-bound latitude. In most cases the sequence is minimum longitude, minimum latitude, maximum longitude and maximum latitude, but when the box spans the antimeridian the first number (west) is larger than the third number (east), since longitudes are in the [-180, 180] range.

All of this is already documented in the current standard.

The clarification that this pull request adds in /req/core/fc-md-extent-multi is just that

• each feature in the collection must be inside the extent described by the first bounding box, and
• each feature in the collection must be inside the extent described by one of the other bounding boxe (if there is more than one bounding box in the array).

The details how the component boxes or the overall box are generated is up to the provider (if configured manually) or the software tool (if derived automatically). As long as the requirement above is met, it is a valid bounding box.

We can discuss adding recommendations like the one discussed with @rcoup above, if there is consensus that this adds value, but I currently do not see that there is value in adding additional requirements how to construct the bounding box array.

[cportele]

Meeting 2021-04-12:

• Wait for the STAC feedback before merging this PR.
• @cportele to include the recommendation about the box with the smallest area
• @cportele to check with @RogerLott, if the open questions have been clarified
• @cportele to add a paragraph to clarify that the box is not the "rough" ISO 19115-1 envelope and a bbox will typically be the exact minimal bbox containing all features.

[m-mohr]

@cportele We just had the STAC call and I can report that we are fine to introduce the proposed change into the STAC specification. We still need to find a concise way to describe it without copying all the requirements directly though.

[cportele]

Awesome, thanks @m-mohr. I will also have a look, if I see a way to improve the wording.

[m-mohr]

@cportele I'm not sure it needs improvements to wording (that was not my point), it just better fits the STAC specification if we can summarize the requirements in one or two sentences (having in mind extents are required in STAC and also require at least one array element, which makes the overall specification easier to write for STAC). Either you can propose something or we'll come up with something and ask you to verify we captured it correctly.

[cportele]

👍 I will give it a try.

[m-mohr]

@cportele I like the description you added. I'll use the following part in STAC and openEO then.

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.

[m-mohr]

@cportele I'm looking at the https://github.com/opengeospatial/ogcapi-features/blob/master/core/openapi/schemas/extent.yaml right now and I think the OpenAPI spec should also reflect the changes. Here's a proposal (I'll add it like this to openEO and STAC API):

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:
    description: |-
      The spatial extent of the features in the collection.
    type: object
    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.
          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:
          description: |-
            Each bounding box is provided as four or six numbers, depending on
            whether the coordinate reference system includes a vertical axis
            (height or depth):

            * Lower left corner, coordinate axis 1
            * Lower left corner, coordinate axis 2
            * Minimum value, coordinate axis 3 (optional)
            * Upper right corner, coordinate axis 1
            * Upper right corner, coordinate axis 2
            * Maximum value, coordinate axis 3 (optional)

            If the value consists of four numbers, the coordinate reference system is
            WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84)
            unless a different coordinate reference system is specified in a parameter `bbox-crs`.

            If the value consists of six numbers, the coordinate reference system is
            WGS 84 longitude/latitude/height (http://www.opengis.net/def/crs/OGC/0/CRS84h)
            unless a different coordinate reference system is specified in a parameter `bbox-crs`.

            For WGS 84 longitude/latitude the values are in most cases the sequence of
            minimum longitude, minimum latitude, maximum longitude and maximum latitude.
            However, in cases where the box spans the antimeridian the first value
            (west-most box edge) is larger than the third value (east-most box edge).

            If the vertical axis is included, the third and the sixth number are
            the bottom and the top of the 3-dimensional bounding box.

            If a feature has multiple spatial geometry properties, it is the decision of the
            server whether only a single spatial geometry property is used to determine
            the extent or all relevant geometries.
          type: array
          oneOf:
          - minItems: 4
            maxItems: 4
          - minItems: 6
            maxItems: 6
          items:
            type: number
          example:
            - -180
            - -90
            - 180
            - 90
      crs:
        description: |-
          Coordinate reference system of the coordinates in the spatial extent
          (property `bbox`). The default reference system is WGS 84 longitude/latitude.
          In the Core the only other supported coordinate reference system is
          WGS 84 longitude/latitude/height for coordinates with height.
          Extensions may support additional coordinate reference systems and add
          additional enum values.
        type: string
        enum:
          - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'
          - 'http://www.opengis.net/def/crs/OGC/0/CRS84h'
        default: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'
  temporal:
    description: |-
      The temporal extent of the features in the collection.
    type: object
    properties:
      interval:
        description: |-
          One or more time intervals that describe the temporal extent of the dataset.
          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:
          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
          items:
            type: string
            format: date-time
            nullable: true
          example:
            - '2011-11-11T12:22:11Z'
            - null
      trs:
        description: |-
          Coordinate reference system of the coordinates in the temporal extent
          (property `interval`). The default reference system is the Gregorian calendar.
          In the Core this is the only supported temporal coordinate reference system.
          Extensions may support additional temporal coordinate reference systems and add
          additional enum values.
        type: string
        enum:
          - 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian'
        default: 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian'

Note: It also moves "The value null is supported and indicates an open time interval." one level down as it is defined in the lower-level schema and seems to logically make more sense there.

[cportele]

👍 Thanks @m-mohr. That makes sense, I have added this as another commit.

[m-mohr]

@cportele Should we go ahead and merge the STAC PRs (i.e. is this PR surely to be merged) or should we wait (timeline?)?

[cportele]

@m-mohr - The plan is to have a motion to merge this PR in the next meeting of the SWG, which is in April 26. If you can wait, I would suggest to wait until then, or does this create an issue for STAC? Thanks!

[pvretano]

@cportele @m-mohr for whatever it is worth, I looked over the proposed changes and they look good to me; I like this PR. I would not be opposed to merging ahead of time to accommodate STAC's timeline. If anything comes up in the April 26th meeting we can create another issue and perhaps another PR to address.
... OR ... I could send out a message today to the SWG asking members to review the PR and see if anyone has an objection to merging in the next few days.

[m-mohr]

@cportele @pvretano Thanks for the details. We just merged it to the STAC spec and will release it as RC3 probably on Tuesday and we just hope the best that it gets through. If it doesn't get merged, then we'll just issue another RC, I guess. So don't worry, it's not required from our side to do anything before 26th of April.

[cportele]

Meeting 2021-04-26: SWG agrees to merge the PR after the change. @cportele will continue the discussion with @RogerLott and if any additional issue is determined we will create a new issue as a result.