OGC Vector Tiles Pilot 2: Vector Tiles Filtering Language Engineering Report

The main benefits for transitioning from raster tiles to vector tiles has been the possibility of flexible map styling and the reduction of storage space required for maps, the latter allowing for maps being stored on devices with lower storage capacity as well as requiring lower bandwidth communications for transmission. In some cases, maps represented with vector tiles can be 20 to 30 times smaller than the same maps represented by raster tiles. This reduction enables the possibility of storing large sets of maps (i.e.,tile sets) into secure and lightweight removable media devices.

As described in Figure 1, a tile set repository (such as GeoPackage, Static Cache, or Compact Cache V2) is being used by a humanitarian relief convoy in the middle of the desert and with limited to no connectivity, supported by a group of interconnected systems working and communicating with each other. The repositories are generated at Command Post Computing Environments (CPCE) and comprise tile sets, styles, maps and routes served by National-level Services and Enterprise-level Services, which communicate with each other throughout OGC API Styles, API Tiles, API Images and API Routes.

The intention of working with vector tile sets is to transition from classic raster maps into using up-to-date and small-sized vector maps which allow for different styles to be applied as needed. An end user would easily transition from a Day Tpographic styling during daytime operations, to Night Topographic during night time, or even a hybrid satellite imagery/vector overlay styling.

Tile content filtering, as described in this ER, allows preparing a tile set specifically targeted to the mission, focusing on pertinent information, further reducing the final size of the package being downloaded on the mobile units, as well as limiting potential confusion.

All questions regarding this document should be directed to the editor or the contributors:

Contacts

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

The OpenGIS Filter Encoding 2.0 Encoding Standard (FE) describes an Extensible Markup Language (XML) and Key-Value Pair (KVP) encoding of a system neutral syntax for expressing projections, selection and sorting clauses collectively called a query expression.

The FE Standard includes both a conceptual filtering model as well as one encoding in Extensible Markup Language (XML). The FE language supports:

The FE detailed conceptual model is distributed across the entire specification document. This ER contains a simple overview diagram of FE in the conceptual model chapter in this ER.

The FE XML encoding is best suited for use in XML documents sent in HTTP POST requests. Usage in GET requests, as a query parameter, is also possible, but limited in application by the verboseness of the language, the URL encoding obfuscating most of its structure, and the practical length limits of a URL.

The HTTP binding of the Catalog Services standard (OGC 12-168r6), also referred to as the Catalogue Services for the Web (CSW) standard (OGC 12-176r7), supports multiple query languages by means of a CONSTRAINTLANGUAGE parameter in GetRecords requests.

The Catalog Services Standard supports the usage of OGC Filter Encoding, but also defines the Common Query Language (CQL). CQL is a text based query language with "a syntax similar to the SQL Where Clause", extended to support both temporal and spatial filters.

CSW advertises CQL as the primary means to filter records. Below is an example used against the AnyText property, which in CSW allows for full text searches:

However, the use of CQL as specified in CSW has several limitations:

The implementation of OGC Catalog Services has also pioneered two concepts that are now relevant to OGC API - Features, queryables and returnables.

Queryable properties are "field-like objects" that can be used to build filters, and "may differ from the response data elements". In other words, queryables are property names, but do not necessarily match the names of the returned properties, and may not appear in the data schema at all (if any schema is present). One example of a queryable without a direct match with returned data is AnyText, which is defined as a "target for full-text search of character data types in a catalogue". Another interesting example is "Abstract". This is a property that can be found among the results, but whose name may vary depending on the record format. For example, in Dublin Core records "Abstract" is named description, while in ISO records "Abstract" matches the nested property /gmd:MD_Metadata/gmd:identificationInfo/gmd:MD_DataI dentification/gmd:abstract.

On the other hand Returnable properties are property names found in the response. Some of them have a match with a corresponding queryable (e.g., title), while others do not. If this is the case, those properties cannot be used in filters (e.g, publisher, contributor).

The GeoServer open source project was the first reference implementation of the OGC Web Feature Service (WFS) standard.

Users of the WFS standard reported difficulties in using the OGC Filter Encoding standard for filtering. This was partly due to the complexity of the language, and partly due to limits in its usage within HTTP GET requests, in particular:

This limited the ability to share data references as simple links.

The GeoServer project adopted, in 2007, a CQL_FILTER query parameter for both WFS GetFeature and Web Map Service (WMS) GetMap:

The following examples show a WFS 1.1 GetFeature request, returning features where the LAND_KM property value is between 100000 and 150000. The first uses FE XML, while the second encodes the filter in CQL instead:

Eventually some limitations of the first CQL version became apparent, so in 2010 Extended CQL (ECQL) was created by the GeoTools and GeoServer communities, to bring the language closer to the OGC Filter capabilities. In particular, ECQL supports, in addition to CQL:

The CQL_FILTER parameter has supported both CQL and ECQL syntaxes since then.

A remaining significant limitation of (E)CQL, in GeoServer, is that it can only be used in a GET request, and has no support in XML POST requests.

Participants in the Testbed 14 Complex Features Handling thread performed an extensive analysis of filtering languages [1]. Of particular interest is the ER chapter on API building blocks for queries.

That chapter contains an analysis of filtering languages following different approaches:

Notable observations from that work include:

CQL has been considered suitable for usage in future extensions of the OGC API - Features but, due to its numerous limitations, but not without further work.

For CQL, the notion of a queryable was first used in combination with a data retrieving service. As with CSW, a queryable is a property that can be queried, but it is not necessarily tied to the schema of the dataset. A queryable could indeed be a visible property of the data. A queryable could also be referring to a nested element via a simple name, or referring to a summary property, such as AnyText, without the property actually being present in the result. The concept was further explored in OGC Testbed 15, where a dedicated OGC API - Features extension was proposed.

Participants in the OGC Testbed 15 Open Portrayal thread investigated and prototyped a new Application Programming Interface (API) for styles publishing, discovery and editing. Results of this activity are documented in the OGC Testbed-15: Styles API Engineering Report.

When a client edits styles, knowing which attributes can be used for collection filtering is important. This was handled by the queryables OGC API - Features extension draft. Queryables are normally a subset of all possible attributes, and in general, may not even show up among the results of a items query. The returned attributes are referred to as "presentables" or "returnables", instead.

Quoting the Testbed 15 ER, each collection exposes a list of Queryable objects, each characterized by:

As they provide a list of property names the filter can use, queryables are a natural fit for a filtering extension.

In November 2019 OGC organized the STAC and OGC API - Features and Catalogues Sprint. The sprint hosted numerous groups, one of them focused on experimenting a possible "OGC API - Features - Part 3: Common Query Language" extension.

The CQL language was considered first in conceptual terms, with a definition of the operators and expressions that could be used in an encoding. Then, three possible encodings were prototyped:

The following table compares the various approaches:

The following shows an example of filtering based on properties of a satellite image, and spatial location, in the three encodings:

In addition to working with the filtering language, the sprint considered the cost of filter language implementation, from the filtering operators point of view. The CQL model contains a rich set of comparison, spatial, temporal and logic operators. Implementing the full set can be both expensive, and depending on the application, perhaps un-necessary.

Based on the OGC Filter Encoding 2.0 specification, and the OGC APIs, two options were considered:

The conformance classes approach allows a compact representation of the supported filters. This is at the expense of fine grain tuning the supported operator set. Classes can be naturally derived from the existing operator subdivision, that is, logical, comparison, spatial, and temporal. However, in practical applications, subsets of operators tend to go across classes. For example, a minimal subset covering basic filtering needs could include all comparisons and logical operators, along with bbox and during basic spatial and temporal filtering. The uncommon and advanced operators can be found within the spatial and temporal categories, but the common ones are found in all categories.

On the other hand, the capabilities document allows for a tailored operator selection but at the expense of listing all supported operators. Annex C contains an example of a full queryables document, as prototyped in GeoServer during the code sprint.

Combining the best aspects of the two approaches above is also possible: declaring a conformance class when all operators in it are supported, and explicitly enumerating the ones for incomplete classes.

The following diagram provides a draft of the filter conceptual model, the elements and their relationship to the other significant elements, available when using a filter in a service or GeoPackage implementation.

In particular, an implementation of the model refers to:

The collection in turn exposes a set of queryables, property names and types that can be used to build a filter, and to verify its formal correctness.

The filter refers to the common building blocks. In summary:

Refer to 09-026r2, OGC® Filter Encoding 2.0 Encoding Standard – With Corrigendum for a detailed definition of each expression and filter.

The OGC API - Features Standards Working Group (SWG) is currently exploring a filtering extension and are evaluating a number of possible encodings. Two encodings are currently being considered for use in the filtering extension:

The JSON encoding is recognized to be most useful to express filters in a larger JSON document, while the CQL based syntax is considered more useful for direct human entry and usage in URLs.

Within the limits of VTP2, the CQL language was chosen for prototyping purposes, as CQL is currently better defined, and better supports the target usage within tile resource URLS.

The CQL language is a text-based language that reads like a SQL 'Where' clause expression, as it is regarded as easy to read and to enter directly, without support by a user interface. On the other hand, due to the text nature, CQL is more complex to handle software-wise, as a full parser needs to be written to handle it. By comparison, the two JSON structures mentioned above, can be parsed using a JSON parser, and would construct an object structure that is similar to a parse tree, ready for use and evaluation.

Usage of CQL outside of the confines of Catalog Services has been pioneered by GeoServer community. GeoServer is an open source project which began using an extended version of the CQL language in both the WFS and WMS protocols:

In both cases the user can add a &CQL_FILTER=<filter expression> query parameter in the request, and get back filtered results.

Compared to the Catalog CQL, the proposed filtering extension of OGC API - Features provided some improvements:

A copy of the current BNF version can be found in Annex A.

The following table shows a few examples of text CQL filters:

Some considerations:

The VTP2 implementations exercised the following subset of operators:

The selection of the operators has been driven by the following principles:

The list of valid properties, and their type, must be available for clients to build filters.

As indicated in Chapter 6, the Testbed 15 Styles’s Engineering Report extended the OGC API - Features with a concept of Queryables, a resource enumerating all attributes available for filtering.

The VTP2 participants used the same extension to advertise collection queryables, both in the OGC API - Features, and in the OGC API - Tiles (for those implementing a stand-alone Tile API, as opposed to a tiles building block in the Features API).

The VTP2 participants considered two filtering cases:

The first use case, filtering a single layer tile, is well-supported by the existing work, in particular, the OGC API - Features CQL extension, as well as the Queryables extension, with the following workflow:

The second use case presents some extra complexities, in particular:

Regarding queryables discovery, the issue is easily solved in an OGC API - Features providing multi-layer tiles at the root level /tiles resource. In this case, the client can list the collections to be retrieved, and thus, lookup the queryables on a collection by collection basis. A stand-alone Tiles API poses a challenge, as collections are opaque and can contain anything, including having a single collection delivering directly multi-layer tiles (see the GeoSolutions implementation in this regard). The queryables document, as a flat list of attributes, is insufficient for this case, and should be turned into a list of named layers, each having their own queryables.

The second issue, providing multiple filters, does not have a solution in the existing CQL language. GeoServer Extended CQL supports a notion of "filter list", used to provide multiple filters in WMS GetMap requests. The grammar uses the semicolon to separate filters, as the comma is already used in the IN operator.

Another possibility would be to repeat the "filter" and "filter-lang" parameters, one instance per filtered collection, in the URL.

Regardless of the solution adopted, most base maps use a large number of layers, for example, an openstreemap.org like map typically uses over 20 layers. Trying to filter on this would require placing over 20 filters in the request, quickly exhausting the practical length of a URL.

For these reasons, with the exception of the Ecere Tiles API, the VTP2 participants limited filtering to single layer collections, while filtering multi-layer collections with CQL is left as future exercise.

Ecere implemented support for compact multi-layer filtering expressions based on the selectors and expressions syntax from the Cascading Map Style Sheets (CMSS) styling language (see Section 11.5).

Through the Vector Tiles Attributes Extension (see the Summary ER), a GeoPackage may contain an attributes table for each vector tiles layer. Using this approach provides two benefits:

Depending on the underlying architecture of the vector tiles server, this approach may impose significant additional processing during GeoPackage creation. In some architectures, the vector tiles are created in advance. In naive GeoPackage creation (ignoring filtering considerations), those vector tiles can simply be copied directly into the GeoPackage. However, in this scenario the vector tiles would have to be modified to remove the attributes. This would significantly increase the processing time required to produce the GeoPackage. An architecture where vector tiles are produced on-the-fly would not be subject to this performance impact.

The approach described in the previous section provides significant benefits for scenarios where features need to be filtered by their attributes and spatial extents. However, it is not possible or practical to isolate which tiles to open to find the geometries for the features that satisfy a particular query.

An R-tree spatial index, storing the overall extent of whole (untiled) features, can be used in conjunction with the attributes table to handle arbitrarily large geospatial extents. Such an index can speed up queries by focusing on the features present in a specific area, only performing more costly attributes comparison for those features within the bounding box of a query. That same stored extent can also be used to easily identify where specific features are located, e.g. to center the view on a particular feature, potentially after having identified that feature by an attributes-based query.

The GeoPackage Related Tables Extension can be used to establish a many-to-many mapping between features and the tiles containing those features. Once this is done, the query can be performed to identify a result set (based on feature IDs) and the mapping table can be queried to identify the tile or tiles that contain the geometries for those features. In some scenarios, this will improve the performance of filtering operations.

The following examples are practical queries performed on a GeoPackage produced by Ecere of the Daraa / OpenStreetMap Topographic DataStore for the pilot, with vector data tiled according to the World Mercator WGS84 Tile Matrix Set, and using the Attributes Table extension, the Tiles/Features Mapping Table extension, as well as a 32-bit integer R-tree spatial index (storing the extent of features as decimal degrees multiplied by a factor of 10⁷, maintaining the same precision as OpenStreetMap).

Querying features and attributes

In this first example query, the client does not care about either the detailed geometry or the tiles of the features but does care about features within a specific geographic region. The client wishes to list the GeoPackage feature IDs, as well as the values for four of the attribute fields (UFI, F_CODE, FCSUBTYPE and ZI005_FNA) matching the following conditions:

An inner join is used between the attributes table and the R-tree spatial index, whose id fields correspond.

Output (list of features):

Identifying tiles containing certain features

In this second example query, the client wishes to preserve the above conditions (only roads with name information, within that same bounding box), but rather than retrieving the attributes values, all the tiles (specifically of zoom level 16, in this case) containing those features should be listed. Because this GeoPackage includes a Tiles / Features Mapping table, that table can be joined with both the Attributes table (through its related_id) as well as with the Tiles table (through its base_id). Note that the tiles returned by this query cover the entirety of the unclipped features which happen to intersect the bounding box of interest — not only the tiles which themselves intersect the bounding box.

Output (list of tiles):

Identifying tiles without a mapping table

Even without a Tiles / Features Mapping table, a client could still easily determine a list of tiles from the extent of the feature(s) as stored in the R-tree spatial index. For a large feature, often only the tiles in view are of interest, in which case the client could also calculate the intersection of the feature’s extent with the view’s extent to identify those tiles. It could then proceed to enumerate the full list (complete box) of tiles within that extent, in a similar way to how the limits of a tile matrix are calculated for a dataset’s extent. The advantage of the Mapping table is to altogether skip tiles in which the features of interest may not be present at all, therefore avoiding to decode tiles not containing these. This would most likely only benefit large features spread non-uniformly across a vast geospatial extent, and come at the cost of additional storage, which should be taken into consideration. The benefit would also not apply to scenarios where all tiles within a geographic area of interest should be decoded anyways (e.g. the simple visualization use case).

In this third example query, it is assumed that a Tiles / Features Mapping table is not available, and therefore the output of the query is an extent which will be programmatically converted to tile coordinates.

Output (extent of the unclipped features):

The extent returned in this case is larger and fully contains the extent of interest in the request. Converting the geographic extent to WorldMercatorWGS84Quad level 16 tile coordinates gives (26518, 39337)-(26520, 39339).

Here is the full list of tiles using those bounding tile coordinates, assuming the whole unclipped features are desired:

Output (list of tiles):

It can be seen that the Mapping table request in this scenario would save the client from decoding 3 out of 9 tiles (33%), which might be significant.

If the client is instead interested in the clipped portion rather than the unclipped features (i.e. only the tiles which themselves intersect the bounding box of interest), then the intersection of the returned extent with the requested extent should be used. This might have justified avoiding the query altogether and directly converting the area of interest to a list of tiles, depending on the circumstances. Converting this intersected extent (which here is the same as the original requested bounding box) to WorldMercatorWGS84Quad level 16 tile coordinates gives (26520, 39337)-(26520, 39339).

The full list of tiles for the portion of the features of interest intersecting the area of interest is:

Output (list of tiles):

In this case, only 3 tiles are needed, and a query using the Mapping table does not eliminate any tile from the full box of tiles covered by the extent, since all tiles of the bounding box contain those features (no saving).

GeoSolutions worked on extending their implementation of the OGC API - Features standard to match the requirements of the VTP2 initiative. Specifically, the following changes were implemented to support filtering and tiles:

The CQL filtering support has been added directly into the "gs-ogcapi-features" GeoServer plugin, while the tiles building block has been implemented as new plugin, "gs-ogciapi-tiled-features", which can be added on top of the base "gs-ogcapi-features" one.

When the Tiled Features plugin is added, the landing page of the service reports the tile matrix set endpoint, as well as advertising tiling resources in the API definition. The following figures show the GeoServer OGC API - Features landing page and API, both extended with new elements from the OGC API - Tile building blocks.

Tiles are provided in any vector format supported by the internal machinery. During VTP2 that meant MVT, GeoJSON and TopoJSON, new formats can be added as desired through a plug-in programming interface.

Queryables support has been added in all collections. The following is an excerpt from the queryables of the syria_vtp:building_s collection (only a few attributes are shown to keep the example short):

http://vtp2.geo-solutions.it/geoserver/ogc/features/collections/vtp:TransportationGroundCrv/queryables?f=json

Support for the filter and filter-lang query parameters has been added both to the items and the tiles resources.

An example of a filtered items request follows:

https://vtp2.geo-solutions.it/geoserver/ogc/features/collections/vtp:TransportationGroundCrv/items?f=json&filter=(%22RIN_ROI%22%20%3D%20%273%27)%20AND%20(BBOX(geom,36.140,32.595,36.142,32.658))&filter-lang=cql-text

The same example above, reformatted and URL decoded for readability, can be split into:

An example of a single collection filtered tiles request follows:

https://vtp2.geo-solutions.it/geoserver/ogc/features/collections/vtp:TransportationGroundCrv/tiles/WebMercatorQuad/14/6618/9833?f=application/vnd.mapbox-vector-tile&filter=(%22RIN_ROI%22%20=%20%273%27)&filter-lang=cql-text

The same example above, reformatted and URL decoded for readability, can be split into:

Regarding caching, it is worth noting that a layer needs to have a caching configuration in order to expose tiled access, as tiling is internally managed by GeoWebCache. It is however not required to make filtered tiles cacheable, if not enabled, then the filtered tiles are computed on-the-fly. If enabled, internal GeoWebCache is going to treat the filter as a "CQL_FITLER" query parameter, to make caches reusable across services. Mapbox vector tiles are indeed already provided as part of the WMTS and WMS services.

In particular, MVT tiles construction is driven by styles, using filters and scale dependencies to decide which features to include at a given zoom level. As a general rule, anything that needs styles to be generated is treated as a WMS output format, and is then exposed into WMTS via GeoWebCache tiling and caching engine.

Various filtering visual examples are available in the GeoSolutions D104 client section.

The open source tegola software implemented the OGC API - Features CQL extension draft, along with collection level queryables support.

GeoSolutions worked on a filtering extension for the existing GeoServer OGC API - Tiles. During the VTP2 activity, the implementations of OGC API - Tiles have been extended to advertise queryables for vector collections, as shown in the following screenshot.

Then, the "data tiles" endpoint has been extended to allow filtering by means of the filter and filter-lang parameters (the map tiles resource has been extended as well, but it’s out of scope for VTP2).

At the time of writing, the only allowed value for filter-lang is cql-text.

The implementation of cql-text is based on GeoServer Extended CQL, providing a full set of filtering operators, as well as a comprehensive list of filter functions covering basic math, string and date handling, as well as geometry manipulation.

A sample filtered tile request follows, reformatted and URL decoded for readability:

Various tile filtering visual examples are available in the GeoSolutions D104 client section.

Ecere developed capabilities for server-side filtering in its GNOSIS Map Server, and exposed it in both the OGC API - Features and OGC API - Tiles implementations. The implementation included support for comparison of attribute values, geometry intersection with a bounding box, as well as logical and arithmetic operations. The current implementation supports expressions as defined in CMSS, the native styling language of GNOSIS tools. Support is planned for the CQL filtering language, but a parser for it could not be implemented during the pilot. Filtering CMSS was made available instead.

The CMSS styling language was first proposed as an encoding for a styling conceptual model in OGC Testbed 14, and documented in the Portrayal, and CityGML and Augmented Reality (http://docs.opengeospatial.org/per/18-025.html#_expressions) Engineering Reports. CMSS expressions serve both for selectors, deciding whether to apply symbology rules, and for styling property values within symbolizers. Just like with selectors, the expressions used for filtering resolve to a single boolean value, if the value is true then the feature is included in the results.

The syntax for CMSS expressions is mostly compatible with the eC programming language, a superset of the C language adding support for object orientation, as well as with ECON (eC Object Notation). Like the bitwise C operator, the symbol | represents an OR logical operation, while & represents AND. However, textual 'or' and 'and' are also supported. Negation is represented by the ! operator, and inequality by !=.

Ecere provided a client able to visualize tiled vector features served by OGC API - Tiles, based on its GNOSIS Cartographer application. The client can apply styles, whether loaded locally, created using the visual style editing interface, or accessed via the Styles API. Features were automatically filtered based on the style in use, however filtering was still applied on the client side. As discussed in the server section, a filter can automatically be determined from a style, by considering its selectors and visualization properties such as opacity and visibility. The client could either reference a style, or POST a style to the service to specifically ask for pre-filtered geometry and attributes based on that style. Alternatively, the client could itself have determined a filter suitable for the style in use, and submit such filter in its service requests. That capability was planned but was not yet implemented during the pilot. A disadvantage of requesting pre-filtered tiles, rather than doing the filtering on the client side, is that the client would need to discard tiles and retrieve a different version when changing between styles.

Ecere produced a number of GeoPackages for the pilot, as well as a client capable of visualizing GeoPackages produced by other participants. These GeoPackages produced using Ecere’s GNOSIS Cartographer tool made use of the "Attributes Tables" extension, which is also supported by the visualization client. This extension is useful for performing filtering when the client accesses the tile data (e.g. accessing fewer encoded tile blobs based on SQL queries). This optimization was not yet implemented in the client during the pilot. The attributes table extension also greatly reduced the size of GeoPackages compared to embedding attributes within the tiles themselves, and provided fast access to querying or updating the attribute information for a given feature. A filter could also be applied when generating a GeoPackage to minimize its size, but this capability has not yet been implemented either. See the GeoPackage section for more details, and an explanation of the SQL queries pictured below.

Skymantics selected Unity to develop a map client with augmented reality capabilities. This software was combined with Mapbox SDK and Mapbox Studio to provide a framework for map utilization.

The deliverable implemented for the vector tile client was a web application built with MapStore, an open source web-based Geographic Information System (GIS) framework.

The following components show a complete filtering workflow:

The filter created by the Filter Builder component was a CQL filter directly included in the tiles request, as query parameter. The client thus expected to get server-side filtered tiles.

The Transportation Ground Curve layer was used to test TIEs.

Below are some screenshots of filters applied to different services using the same layers.

This section collects the findings of the Pilot activity.