Using Feature Filters

Feature filters are a powerful tool for controlling the contents of tiles based on the tile identifier (ie the x, y and z of the tile). For example, you can use a feature filter to only include local roads at tiles of higher zoom levels. A less common example might be to only show certain types of features in certain regions.

Feature filters are unnecessary for most visualization use cases, but are essential for complex use cases like building a base map or exerting a high degree of control over the contents of tiles across zoom levels.

The Feature Filter API

Feature filters are spark sql Column types that resolve to a boolean value. They are evaluated for each feature/tile combo where a True value means the feature is included in the tile and a False value means the feature is excluded. The columns that can be referenced in a feature filter are a superset of the columns in the features dataframe that is passed into the generate function. In addition to the columns provided as input, The following are available:

• tile: struct - contains the x, y and z of the tile this feature is in
  • x: int - the x coordinate of the tile
  • y: int - the y coordinate of the tile
  • z: int - the z coordinate, or zoom, of the tile
• length: double - the length of the unclipped feature in terms of the tile's units. If the feature is the length of the tile, this will be 1. Clipping of the feature does not come into play in this value. For example, if a feature runs from the left edge of one tile to the right edge of the tile to the right, the value would be 2.
• area: double - the area of the unclipped feature in terms of the tile's units. If the feature is the area of the tile, this will be 1. Clipping of the feature does not come into play in this value. For example, if a feature is a square that completely covers 4 tiles, the area will be 4.

Example

In this example we will create a feature filter that excludes all local roads at zoom levels 10 and below, excludes all highways at zoom levels above 10 and excludes all buildings at zoom levels 11 and below.

from wherobots.vtiles import generate, GenerationConfig
import pyspark.sql.functions as f

generate(my_features_df, GenerationConfig(
    feature_filter= ~( # ~ means not, so exclude all the following cases
        ((f.col('tile.z') <= 10) & (f.col('road_type') == 'local_road')) | # exclude local roads at zoom levels 10 and below
        ((f.col('tile.z') > 10) & (f.col('road_type') == 'highway')) | # exclude highways at zoom levels above 10
        (f.col('tile.z') <= 11) & (f.col('layer') == 'buildings') # exclude buildings at zoom levels 11 and below
    )
))