vtiles

Vector tiles generation and writing functionality.

GenerationConfig dataclass

Configuration for generating vector tiles.

Attributes:

Name	Type	Description
min_zoom	int	the lowest zoom for which to generate tiles
max_zoom	int	the highest zoom for which to generate tiles
tile_resolution	int	the resolution of the tiles to generate
buffer	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
feature_filter	Optional[Column]	a predicate Column for filtering features, optional
tile_filter	Optional[Column]	a Column for manipulating the array of features within a tile, optional
feature_simplify	Optional[Column]	a Column for manipulating feature geometries, optional
max_features_per_tile	Optional[int]	the maximum number of features to include in each tile, optional
cache_frequency	Optional[int]	the frequency at which to cache the dataset, optional. e.g 2 means every 2nd zoom level. Default is 2
persist_storage_level	Optional[StorageLevel]	the storage level to cache the dataset at. Default is DISK_ONLY
max_dataset_size	Optional[int]	the maximum size of the dataset from which to generate tiles, optional
partition_count	Optional[int]	the number of partitions to use in tile generation. Default is 2x the number of worker cores.
repartition_frequency	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.

with_suggested_max_zoom(df)

Sets the maxZoom based on heuristics of the input dataframe.

Parameters:

Name	Type	Description	Default
df	DataFrame	The dataframe that will be used along with this Config to generate tiles.	required

Returns:

Type	Description
GenerationConfig	a new GenerationConfig with the maxZoom set based on heuristics of the input dataframe

with_suggested_min_zoom(df)

Sets the minZoom based on heuristics of the input dataframe.

Parameters:

Name	Type	Description	Default
df	DataFrame	The dataframe that will be used along with this Config to generate tiles.	required

Returns:

Type	Description
GenerationConfig	a new GenerationConfig with the minZoom set based on heuristics of the input dataframe

PMTilesCompressionType

Bases: 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.

Attributes:

Name	Type	Description
UNKNOWN	int	unknown
NONE	int	none
GZIP	int	gzip
BROTLI	int	brotli
ZSTD	int	zstd

PMTilesConfig dataclass

Configuration for generating PMTiles.

Attributes:

Name	Type	Description
tile_type	TileType	The type of tile to generate
tile_compression_type	CompressionType	The compression type of the tile data. This should match with the actual tile data.
metadata	str	The metadata to include in the PMTiles. It should be a serialized JSON object.
internal_compression_type	CompressionType	The compression type of internal structures in the PMTiles.
is_clustered	bool	Whether the tiles are clustered. Currently only false is supported.
min_lon	float	The minimum longitude of the tileset
min_lat	float	The minimum latitude of the tileset
max_lon	float	The maximum longitude of the tileset
max_lat	float	The maximum latitude of the tileset
center_zoom	int	The zoom level of the center of the tileset
center_lon	float	The longitude of the center of the tileset
center_lat	float	The latitude of the center of the tileset

PMTilesConfigBuilder

Builder for creating a PMTilesConfig.

Attributes:

Name	Type	Description
name	str	A name for the tileset
description	str	A description of the tileset
attribution	str	An attribution string for the tileset
version	str	A version string for the tileset
tileset_type	TilesetType	The type of tileset in this archive (baselayer or overlay)
layers	List	The vector tile layer that are in the tiles
extra_metadata	Dict	Extra metadata to include in the PMTiles header
tile_type	TileType	The type of tiles in the archive
bounds	Polygon	The bounding box of the data in the tileset in lon/lat
center	Point	The central point of the tileset in lon/lat
tile_compression	CompressionType	The type of compression to apply to each tile's binary
internal_compression	CompressionType	The type of compression to apply to internal structures in the archive
is_clustered	bool	Whether the tiles are clustered(ie ordered in the archive). Currently only false is supported.

add_layer(layer_name, layer_description=None, min_zoom=None, max_zoom=None, fields=None)

Add a layer to the PMTiles configuration.

Parameters:

Name	Type	Description	Default
layer_name	str	The name of the layer as it appears in the tiles	required
layer_description	Optional[str]	An optional description of the layer	None
min_zoom	Optional[int]	the lowest zoom level the layer is visible at	None
max_zoom	Optional[int]	the highest zoom level the layer is visible at	None
fields	Optional[Dict[str, str]]	the attributes that may be present on member features of the layer	None

Returns: The builder object with the new layer added

build()

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

Returns:

Type	Description
	A PMTilesConfig object based on the values set in the builder

from_features_data_frame(features_df)

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

Pass the features dataframe used for making these tiles to this method to automatically set the bounds, center, and layers based on the features in the dataframe.

Parameters:

Name	Type	Description	Default
features_df	DataFrame	The DataFrame containing the features used to generate the tiles that will go in the PMTiles	required

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

PMTilesTileType

Bases: Enum

Tile types supported by PMTiles format.

The tile type reflects the format of the tile data.

Attributes:

Name	Type	Description
UNKNOWN	int	unknown
MVT	int	mvt
PNG	int	png
JPEG	int	jpeg
WEBP	int	webp
AVIF	int	avif

PMTilesTilesetType

Bases: Enum

The type of tile to generate.

Attributes:

Name	Type	Description
BASELAYER	str	The tileset is designed to be rendered below other layers
OVERLAY	str	The tileset is designed to be rendered above the base layer

generate(dataframe, config=None)

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.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	the features to generate tiles from	required
config	GenerationConfig	the configuration for generating tiles	None

Returns:

Type	Description
DataFrame	a DataFrame of tiles ready to be output as MVTs

generate_pmtiles(dataframe, path, config=None, pmtiles_config=None, storage_level=StorageLevel.MEMORY_AND_DISK)

Generates and writes PMTiles from a DataFrame of features.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	the DataFrame of features to generate tiles from	required
path	str	the path to write the PMTiles file to	required
config	GenerationConfig	the configuration for generating tiles	None
pmtiles_config	PMTilesConfig	the configuration for generating the PMTiles file	None
storage_level	Optional[StorageLevel]	the storage level to cache the tiles DataFrame at. If None, the DataFrame will not be cached	MEMORY_AND_DISK

generate_quick_pmtiles(df, path, render=True)

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

Parameters:

Name	Type	Description	Default
df	DataFrame	the DataFrame of features to generate tiles from	required
path	str	the path to write the PMTiles file to	required
render	bool	whether to return a leafmap Map object showing the generated tiles	True

Returns:

Type	Description
Map	a leafmap Map object showing the generated tiles if render is True

get_pmtiles_config_builder()

Returns a PMTilesConfigBuilder for creating a PMTilesConfig.

Returns:

Type	Description
PMTilesConfigBuilder	an empty PMTilesConfigBuilder

get_quick_config()

Retrieves a default GenerationConfig for generating tiles.

This configuration is optimized for quick (<5 minutes on a Cairo cluster) 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 overzooming 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:

Type	Description
GenerationConfig	a default GenerationConfig for generating tiles

show_pmtiles(layers, basemap='xyz.CartoDB.DarkMatter')

Shows a set of PMTiles layers on a leafmap Map.

The layers can be provided as a list of S3 URIs or dicts. The dicts may contain some or all of the following fields:

• s3_uri: the S3 URI of the PMTiles file. string. required

• name: a descriptive name of the layer. string. will default to the file name.

• style: the style of the layer. dict. see https://leafmap.org/notebooks/82_pmtiles/

• overlay: whether the layer should be an overlay or base layer. boolean

• show: whether the layer should be shown by default. boolean

• zoom_to_layer: whether the map should zoom to the layer when it is added. boolean

Parameters:

Name	Type	Description	Default
layers	Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]]	the layers to show. see overview for more information	required
basemap	str	the basemap to use. string. see https://leafmap.org/notebooks/31_search_basemaps/	'xyz.CartoDB.DarkMatter'

Returns:

Type	Description
Map	a leafmap Map object showing the layers as configured

write_pmtiles(tiles_df, path, config=None, features_df=None, storage_level=StorageLevel.MEMORY_AND_DISK)

Writes a DataFrame of tiles to a PMTiles file.

Parameters:

Name	Type	Description	Default
tiles_df	DataFrame	the DataFrame of tiles to write	required
path	str	the path to write the PMTiles file to	required
config	Optional[PMTilesConfig]	the configuration for generating the PMTiles file. If None, the config will be generated from the features DataFrame	None
features_df	Optional[DataFrame]	the DataFrame of features that the tiles were generated from. This is used to generate the config if one is not provided	None
storage_level	Optional[StorageLevel]	the storage level to cache the tiles DataFrame at. If None, the DataFrame will not be cached	MEMORY_AND_DISK