Geometry Simplification extension

[cportele]

Discussed during the 2021-11 Sprint:

• Use a query parameter scale-denominator with a numeric value as a hint for the server that the data in the response is intended to be displayed on a map at the scale 1:{scale-denominator}. There is no default value for the parameter.
  • We decided to use the scale denominator (and not resolution), because this is also what is used in other OGC API resources, e.g. for styles and tile sets.
  • For some users or clients, the use of a zoom level as used in the WebMercatorQuad tile matrix set might be more natural. We could discuss, whether we want to support this as an additional, alternative parameter.
  • Maybe also include members minScaleDenominator and maxScaleDenominator (used in the Tile Set Metadata) in the Collection resource to inform clients about the scale range.
• The server may also use the scale information, if provided, to filter the features eligible for inclusion in the response. For example, a server may return only city features with a certain population or road features of a certain road type at a smaller scale.
• The details how the API simplifies the geometry or filters features based on the scale information is left to the implementation.
• We also discussed an option where clients could specify a style (e.g. use paths like /collections/{collectionId}/styles/{styleId}/items) and the server would use the feature filtering rules that are part of the style, but decided against this approach:
  • While feature filtering is part of feature styles, it is only part of it and the main purpose of a style is to specify how features are rendered. In addition, servers would need to understand how to extract the feature filtering rules from a style and parse them. In general, feature resources should not have a dependency on style resources (rather the other way round).
  • This is an advanced use case, but we should focus in this extension on the main use case: Enable servers to return content optimized for use at a certain scale where clients should not need to understand the data in order to submit such requests.
  • The API building blocks of OGC API Features already provide mechanisms for filter expressions specified by the client, so there would be significant overlap with such a capability based on styles.
• The selected approach is similar to the Tiles resources where it is determined by the server which features are included in a tile at a certain zoom level.
• One topic that needs more discussion is clipping geometries to some bounding box (we plan to continue this discussion during the sprint):
  • Should the clipping only happen, if a scale denominator is provided or should it be independent of it? Are there common use cases for rectangular clipping of data outside of a mapping context.
  • Should clipping always happen, if there is both a scale-denominator and a bbox parameter or would clients need to control clipping separately?
  • If clipping is desired, would one always clip the data to the bounding box used for filtering (i.e. the same values as in the bbox query parameter) or could it be a different area?

[jerstlouis]

On filtering:

Just a note that I still believe /collections/{collectionId}/styles/{styleId}/items (or equivalent request) is a valid use case similar to the main proposal where the API decides how it simplifies the geometry or filters features based on the scale information, but offering multiple options to clients organized by style instead of a single default.

But it's fine to avoid specifying this in Features, and even in the Styles, as long as it can be a vendor extension can achieve this (even if it has to be something like style-filter=night, or at some other end-point).

Styles are intended for rendering, but filtering is a big part of it, so it's a very convenient way to ask the server "give me the features that I need to render this style client-side at this zoom level". This is actually very easy for servers to support if they also happen to support server-side rendering and the Styles API. Myself and @pomakis implemented this use case so far for vector tiles.

An advantage for a simple client that uses a library to render styles for example is that it does not need to parse and understand the style in order to translate it to e.g. CQL to build the request with a filter, it can rely on the server and the rendering library both understanding it.

On simplification: About a potential zoom-level (or tile-matrix) parameter, our implementation right now also supports specifying the particular tile-matrix-set that it corresponds to (defaults to GNOSISGlobalGrid at the moment, but could default to WebMercatorQuad instead). Would be fine to leave that as a vendor extension as well and assume e.g. WebMercatorQuad.

On clipping:

Should the clipping only happen, if a scale denominator is provided or should it be independent of it? Are there common use cases for rectangular clipping of data outside of a mapping context.

I really think it should be independent of it. I assume the default scale denominator (without specifying one) would be the most detailed representation that the server is willing to return for the request (to clarify). When zoomed way in on features, the client may omit the the clipping box when it does not want any simplification to be performed, and want to clip for the view's extent.

Clipping is also a mechanism to page features with heavy geometry to retrieve it all as tiles of data at the highest resolution (e.g. building CDB 1x1 degrees GeoCells).

Should clipping always happen, if there is both a scale-denominator and a bbox parameter or would clients need to control clipping separately?

I don't think it should, because a client may wish to simply filter features from a bbox, still wishing to be able to pan to see the whole thing, but request it at a lower resolution than what is available from the API. It could easily confound clients that such parameters behave completely differently based on how they are combined.

If clipping is desired, would one always clip the data to the bounding box used for filtering (i.e. the same values as in the bbox query parameter) or could it be a different area?

It could be a different area. We discussed two use cases in particular:

• Generating Mapbox Vector Tiles for which you would want to filter with bbox on the tile's extent, but clip on a slightly larger bbox to preserve the border required to avoid artificial tile edges visual artifacts
• Request some extra padding for the geometry to keep presenting while panning and waiting for a response to a new clipped request.

[jerstlouis]

scale-denominator support on our server: https://maps.ecere.com/ogcapi/collections/NaturalEarth:cultural:ne_10m_admin_0_countries/items?f=json&limit=1000&scale-denominator=150000000&properties=name,geometry
vs. https://maps.ecere.com/ogcapi/collections/NaturalEarth:cultural:ne_10m_admin_0_countries/items?f=json&limit=1000&scale-denominator=50000000&properties=name,geometry (also added resolution / cell-size / max-allowable-offset as equivalent to the previous proposal functionality)

zoom-level still there and defaulting to GNOSISGlobalGrid unless also saying e.g. &tilematrixset=WebMercatorQuad (GGG level 0 = WMQ level 2)

Interesting note: The first feature (American Samoa) has a null geometry at 1:150,000,000 but non-null at 1:50,000,000.

Clipping support currently showcasing different clipping [10,30,170,80] and bounding [40,40,140,50] box combinations:

both:

https://maps.ecere.com/ogcapi/collections/NaturalEarth:cultural:ne_10m_admin_0_countries/items?f=json&limit=1000&scale-denominator=150000000&properties=name,geometry&clip-box=10,30,170,80&bbox=40,40,140,50

vs. clip-box only:

https://maps.ecere.com/ogcapi/collections/NaturalEarth:cultural:ne_10m_admin_0_countries/items?f=json&limit=1000&scale-denominator=150000000&properties=name,geometry&clip-box=10,30,170,80

vs. bbox only:

https://maps.ecere.com/ogcapi/collections/NaturalEarth:cultural:ne_10m_admin_0_countries/items?f=json&limit=1000&scale-denominator=150000000&properties=name,geometry&bbox=40,40,140,50

Note that we also support a distinct clipbox-crs query parameter for Part 2. We also support subset=Lat(30:80),Lon(10:170) (with a matching subset-crs) as an alternative to clip-box, which provides a consistent way to subset (clip) data across Coverages / Features / Maps / Tiles (for extra dimensions like time).

I have also enabled filtering based on the styles, e.g.:

https://maps.ecere.com/ogcapi/collections/osm:dc:roads/styles/default/items?f=json&limit=10000&scale-denominator=1000000

https://maps.ecere.com/ogcapi/collections/osm:dc:roads/styles/default/items?f=json&limit=10000&scale-denominator=500000

[tinoks]

Why not ../items?f=json&simplify=0.001. Referring to a Douglas-Pecker tolerance. Then the result will be reproducible and based on CRS.

Else it is entirely up to the developer of the backend server, what they think is visual pleasing for the scale?

[cportele]

We have also updated our demo server with support for scale-denominator, max-allowable-offset (the Douglas-Peucker epsilon), and zoom-level (the WebMercatorQuad zoom level).

Some links with just geometric simplification:

• https://demo.ldproxy.net/cshapes/collections/boundary/items?limit=100&datetime=2015-01-01&zoom-level=0
• https://demo.ldproxy.net/cshapes/collections/boundary/items?limit=100&datetime=2015-01-01&scale-denominator=500000000
• https://demo.ldproxy.net/cshapes/collections/boundary/items?limit=100&datetime=2015-01-01&max-allowable-offset=0.1

With filtering (nothing up to zoom level 4, motorways up to zoom level 7, also national roads up to 8, also state roads up to 9, also district roads up to 10, also ramps at 10+):

• https://demo.ldproxy.net/strassen/collections/abschnitteaeste/items?limit=1000&zoom-level=4
• https://demo.ldproxy.net/strassen/collections/abschnitteaeste/items?limit=1000&zoom-level=8
• increase the zoom-level to get more features (or use scale-denominator or max-allowable-offset)

Else it is entirely up to the developer of the backend server, what they think is visual pleasing for the scale?

Yes, like with vector tiles where it is up to the server which features to include in tiles at various levels and how.

The other argument is that the choice of the algorithm is up to the server, it does not have to be Douglas-Peucker. And for filtering the content, a scale / resolution / zoom-level ranges seem more appropriate.

[ghobona]

A reminder that the Clause 6.1.1 of the current 2DTMS Standard says "The scale denominator is defined here with respect to a 'standardized rendering pixel size' of 0.28 mm × 0.28 mm (millimeters)."

So OGC API - Features should ideally adopt the same definition.

[jerstlouis]

@ghobona As we discussed today, there should be no need for pixel size to come into play for this definition, since the scale denominator is expressed in terms of physical-to-physical distance, i.e. the size on which a map will be printed or displayed vs. the size of the vector features in the real world.

Viewers displaying the vector features on a computer screen or tablet MAY make the decision to use a standardized pixel size when rendering the map to the display rather than make use of the actual display device's resolution (DPI) or pixel size, and they SHOULD use the target pixel dimensions when simplifying geometry to render maps or map tiles from those features to be transmitted as a raster format with a specific resolution, but that would already be covered by those separate standards. Perhaps some clarifications along these lines would be useful, but I don't think that needs to be part of any requirement.

[benoitdm-oslandia]

Hi @cportele,

you said:

We have also updated our demo server with support for scale-denominator, max-allowable-offset (the Douglas-Peucker epsilon), and zoom-level (the WebMercatorQuad zoom level).

But scale-denominator and zoom-level are not defined in the document. Are they needed or are they optional?

In this document you mention for the max-allowable-offset parameter:

The value is in the units of the response coordinate reference system.

Do you mean, when the client send a GET request, the unit of the max-allowable-offset should match the Content-crs header of the request?

[maxcollombin]

Hello,

I'd just like to draw your attention to this excellent presentation by @MathiasGroebe at FOSS4G 2023: Cartographic generalization with Open Source

On slide 6 of his presentation, he describes the main Generalization operators and algorithms.

Although Douglas-Peucker has already been mentioned in this discussion, it could be great to add the following references to the extension:

• Simplification: Visvalingam-Whyatt
• Smoothing: Chaikin Smoothing
• Aggregation/Clustering: K-Means, DBSCAN
• Collapse: Centroid

as well as others not necessarily listed in @MathiasGroebe' presentation.