Vector Tiles (VTiles) Python API

Vector tiles (VTiles) are small pieces of map data that allow for efficient rendering at varying zoom levels. Unlike raster tiles which are pre-rendered images, vector tiles contain attributes and geometric data that facilitate dynamic styling of map features on the fly, offering more flexibility and interactivity. PMTiles is a cloud-native file format that is designed for holding an entire collection of tiles, in this case vector tiles. The PMTiles format allows individual tiles to be queried directly from cloud object storage like Amazon S3. By querying directly from cloud storage, you no longer need to set up and manage dedicated infrastructure, reducing your costs and time-to-tile-generation.

`GenerationConfig`

class GenerationConfig

Configuration for generating vector tiles.

Attributes

int

The lowest zoom for which to generate tiles

int

The highest zoom for which to generate tiles

int

The resolution of the tiles to generate

float

The buffer (as a fraction) to apply to the tiles. The margin on a 1000 resolution tile with a buffer of .1 would be 100

Optional[Column]

A predicate Column for filtering features, optional

Optional[Column]

A Column for manipulating the array of features within a tile, optional

Optional[Column]

A Column for manipulating feature geometries, optional

Optional[int]

The maximum number of features to include in each tile, optional

Optional[int]

The frequency at which to cache the dataset, optional. E.g 2 means every 2nd zoom level. Default is 2

Optional[StorageLevel]

The storage level to cache the dataset at. Default is DISK_ONLY

Optional[int]

The maximum size of the dataset from which to generate tiles, optional

Optional[int]

The number of partitions to use in tile generation. Default is 2x the number of worker cores

Optional[int]

The frequency (ie number of zoom levels) at which to repartition the dataset. Default behavior not to repartition a certain zooms. Repartitioning helps when the geometries are large relative to the tiles, for example processing a collection of countries to zoom 16

bool

Experimental, Unstable feature. Whether to replace polygons with a point in each tile the Polygon appears in. Default is false

`with_suggested_min_zoom()`

Sets the minZoom based on heuristics of the input dataframe.

Parameters

with_suggested_min_zoom(self, df: DataFrame) -> 'GenerationConfig'

DataFrame

required

The dataframe that will be used along with this Config to generate tiles.

Returns

A new GenerationConfig with the minZoom set based on heuristics of the input dataframe.

`with_suggested_max_zoom()`

Sets the maxZoom based on heuristics of the input dataframe.

with_suggested_max_zoom(self, df: DataFrame) -> 'GenerationConfig'

Parameters

DataFrame

required

The dataframe that will be used along with this Config to generate tiles.

Returns

A new GenerationConfig with the maxZoom set based on heuristics of the input dataframe.

`PMTilesCompressionType`

class PMTilesCompressionType(Enum)

Compress types supported by PMTiles format. Compression can be applied to both the tile data and internal structures such as directories in the PMTiles format.

Values

int

Unknown compression type

int

No compression

int

GZIP compression

int

Brotli compression

int

Zstandard compression

`PMTilesConfig`

class PMTilesConfig

Configuration for generating PMTiles.

Attributes

TileType

The type of tile to generate

CompressionType

The compression type of the tile data. This should match with the actual tile data

str

The metadata to include in the PMTiles. It should be a serialized JSON object

CompressionType

The compression type of internal structures in the PMTiles

bool

Whether the tiles are clustered. Currently only false is supported

float

The minimum longitude of the tileset

float

The minimum latitude of the tileset

float

The maximum longitude of the tileset

float

The maximum latitude of the tileset

int

The zoom level of the center of the tileset

float

The longitude of the center of the tileset

float

The latitude of the center of the tileset

`PMTilesConfigBuilder`

class PMTilesConfigBuilder

Builder for creating a PMTilesConfig.

Attributes

str

A name for the tileset

str

A description of the tileset

str

An attribution string for the tileset

str

A version string for the tileset

TilesetType

The type of tileset in this archive (baselayer or overlay)

List

The vector tile layer that are in the tiles

Dict

Extra metadata to include in the PMTiles header

TileType

The type of tiles in the archive

Polygon

The bounding box of the data in the tileset in lon/lat

Point

The central point of the tileset in lon/lat

CompressionType

The type of compression to apply to each tile’s binary

CompressionType

The type of compression to apply to internal structures in the archive

bool

Whether the tiles are clustered(ie ordered in the archive). Currently only false is supported

`PMTilesTileType`

class PMTilesTileType(Enum)

Tile types supported by PMTiles format. The tile type reflects the format of the tile data.

Values

int

Unknown tile type

int

Mapbox Vector Tiles format

int

PNG image format

int

JPEG image format

int

WebP image format

int

AVIF image format

`PMTilesTilesetType`

class PMTilesTilesetType(Enum)

The type of tile to generate.

Values

str

The tileset is designed to be rendered below other layers

str

The tileset is designed to be rendered above the base layer

`generate()`

Generates tiles from a set of features. The features must have a geometry column of the Geometry type and a layer column of string type represent what layer that feature belongs in. An optional Integer or Long column id can be included to persist an ID into the tiles. The features can be of any geometry type. The output dataset will have a tile column specifying the tile and a feature column containing clipped, simplified features that belong in that tile, projected into the [0..1] coordinate space of the tile for its x and y values. Geometries should be in the WGS84 coordinate reference system. Note that because slippy tiles are based on a Mercator projection, features with latitudes less than -85.0511 or greater than 85.0511 should not be processed. This is a limitation of slippy tile systems.

generate(dataframe: DataFrame, config: GenerationConfig) -> DataFrame

Parameters

DataFrame

required

The features to generate tiles from.

GenerationConfig

required

The configuration for generating tiles.

Returns

A DataFrame of tiles ready to be output as MVTs.

`write_pmtiles()`

Writes a DataFrame of tiles to a PMTiles file.

write_pmtiles(tiles_df: DataFrame, path: str, config: Optional[PMTilesConfig], features_df: Optional[DataFrame], storage_level: Optional[StorageLevel])

Parameters

DataFrame

required

The DataFrame of tiles to write

str

required

The path to write the PMTiles file to

Optional[PMTilesConfig]

The configuration for generating the PMTiles file. If None, the config will be generated from the features dataframe

Optional[DataFrame]

The DataFrame of features that the tiles were generated from. This is used to generate the config if one is not provided.

Optional[StorageLevel]

The storage level to cache the tiles DataFrame at. If None, the DataFrame will not be cached.

`generate_pmtiles()`

Generates and writes PMTiles from a DataFrame of features.

generate_pmtiles(dataframe: DataFrame, path: str, config: GenerationConfig, pmtiles_config: PMTilesConfig, storage_level: Optional[StorageLevel])

Parameters

DataFrame

required

The DataFrame of features to generate tiles from.

str

required

The path to write the PMTiles file to.

GenerationConfig

required

The configuration for generating tiles.

PMTilesConfig

required

The configuration for generating the PMTiles file.

Optional[StorageLevel]

The storage level to cache the tiles DataFrame at. If None, the DataFrame will not be cached.

Returns

The generated PMTiles.

`get_pmtiles_config_builder()`

Returns a PMTilesConfigBuilder for creating a PMTilesConfig.

get_pmtiles_config_builder() -> PMTilesConfigBuilder

Parameters

DataFrame

required

The DataFrame of features to generate tiles from.

str

required

The path to write the PMTiles file to.

GenerationConfig

required

The configuration for generating tiles. If None, a default config will be used.

PMTilesConfig

required

The configuration for generating the PMTiles file. If None, a default config will be used.

Optional[StorageLevel]

The storage level to cache the tiles DataFrame at. If None, the DataFrame will not be cached.

Returns

An empty PMTilesConfigBuilder.

`_add_layer()`

Adds a PMTiles layer to a leafmap Map.

_add_layer(_map, s3_uri: str, name: str, style: dict, overlay: bool, show: bool, zoom_to_layer: bool):
    pass

Parameters

The layers can be provided as a list of S3 URIs or dicts.

Any

required

The map object to which the layer will be added.

str

required

The S3 URI of the PMTiles file.

str

required

A descriptive name of the layer. Will default to the file name if not provided.

dict

required

The style of the layer. See https://leafmap.org/notebooks/82_pmtiles/

bool

required

Whether or not the layer should be an overlay or base layer.

bool

required

Whether or not the layer should be shown by default.

bool

required

Whether or not the map should zoom to the layer when it is added.

`build()`

Build the PMTilesConfig object. Call this after setting all the desired fields.

Returns

A PMTilesConfig object based on the values set in the builder

`from_features_data_frame()`

Sets the bounds, center, and layers based on the features in the DataFrame.

Parameters

DataFrame

required

The DataFrame containing the features used to generate the tiles that will go in the PMTiles

Returns

The builder object with the bounds, center, and layers set based on the features in the DataFrame.

`get_quick_config()`

Retrieves a default GenerationConfig for generating tiles.

get_quick_config() -> GenerationConfig

This configuration is optimized for quick tile generation. This is accomplished by generating lower zoom levels and higher resolutions, and limiting the number of features rendered to 100 million. Use with a renderer that supports over-zooming is recommended. Be aware that these are effectively on up to zoom 10 tiles, so their low resolution will be evident at higher zoom levels.

Returns

A default GenerationConfig for generating tiles.

`generate_quick_pmtiles()`

Generates PMTiles from a DataFrame of features using a quick configuration.

generate_quick_pmtiles(df: DataFrame, path: str, render: bool) -> leafmap.Map

Parameters

DataFrame

required

The DataFrame of features to generate tiles from.

str

required

The path to write the PMTiles file to.

bool

required

Whether to return a leafmap Map object showing the generated tiles.

Returns

A leafmap Map object showing the generated tiles if render is True.

`show_pmtiles()`

Shows a set of PMTiles layers on a leafmap Map.

show_pmtiles(layers: Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]], basemap: str) -> leafmap.Map

Parameters

Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]]

required

The layers to show. see overview for more information

str

required

The basemap to use. string. see https://leafmap.org/notebooks/31_search_basemaps/

Returns

A leafmap Map object showing the layers as configured.

`with_suggested_min_zoom()`

Sets the minZoom based on heuristics of the input dataframe.

with_suggested_min_zoom(self, df: DataFrame) -> 'GenerationConfig'

string

required

Parameter description

DataFrame

required

The dataframe that will be used along with this Config to generate tiles.

Returns

A new GenerationConfig with the minZoom set based on heuristics of the input dataframe.

`with_suggested_max_zoom()`

Sets the maxZoom based on heuristics of the input dataframe.

with_suggested_max_zoom(self, df: DataFrame) -> 'GenerationConfig'

Parameters

string

required

Parameter description

DataFrame

required

The dataframe that will be used along with this Config to generate tiles.

Returns

A new GenerationConfig with the maxZoom set based on heuristics of the input dataframe.

Usage Examples

from vtiles import *

# Example usage of _get_optional
result = _get_optional(value=example_value)

# Example usage of GenerationConfig
instance = GenerationConfig()

​GenerationConfig

​Attributes

​with_suggested_min_zoom()

​Parameters

​Returns

​with_suggested_max_zoom()

​Parameters

​Returns

​PMTilesCompressionType

​Values

​PMTilesConfig

​Attributes

​PMTilesConfigBuilder

​Attributes

​PMTilesTileType

​Values

​PMTilesTilesetType

​Values

​generate()

​Parameters

​Returns

​write_pmtiles()

​Parameters

​generate_pmtiles()

​Parameters

​Returns

​get_pmtiles_config_builder()

​Parameters

​Returns

​_add_layer()

​Parameters

​build()

​Returns

​from_features_data_frame()

​Parameters

​Returns

​get_quick_config()

​Returns

​generate_quick_pmtiles()

​Parameters

​Returns

​show_pmtiles()

​Parameters

​Returns

​with_suggested_min_zoom()

​Returns

​with_suggested_max_zoom()

​Parameters

​Returns

​Usage Examples

`GenerationConfig`

Attributes

`with_suggested_min_zoom()`

Parameters

Returns

`with_suggested_max_zoom()`

Parameters

Returns

`PMTilesCompressionType`

Values

`PMTilesConfig`

Attributes

`PMTilesConfigBuilder`

Attributes

`PMTilesTileType`

Values

`PMTilesTilesetType`

Values

`generate()`

Parameters

Returns

`write_pmtiles()`

Parameters

`generate_pmtiles()`

Parameters

Returns

`get_pmtiles_config_builder()`

Parameters

Returns

`_add_layer()`

Parameters

`build()`

Returns

`from_features_data_frame()`

Parameters

Returns

`get_quick_config()`

Returns

`generate_quick_pmtiles()`

Parameters

Returns

`show_pmtiles()`

Parameters

Returns

`with_suggested_min_zoom()`

Returns

`with_suggested_max_zoom()`

Parameters

Returns

Usage Examples