Skip to main content
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

​
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
​
convert_polygons_to_label_points
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'
​
df
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

​
df
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

​
UNKNOWN
int
Unknown compression type
​
NONE
int
No compression
​
GZIP
int
GZIP compression
​
BROTLI
int
Brotli compression
​
ZSTD
int
Zstandard compression

​
PMTilesConfig

class PMTilesConfig
Configuration for generating PMTiles.

​
Attributes

​
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

class PMTilesConfigBuilder
Builder for creating a PMTilesConfig.

​
Attributes

​
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

​
PMTilesTileType

class PMTilesTileType(Enum)
Tile types supported by PMTiles format. The tile type reflects the format of the tile data.

​
Values

​
UNKNOWN
int
Unknown tile type
​
MVT
int
Mapbox Vector Tiles format
​
PNG
int
PNG image format
​
JPEG
int
JPEG image format
​
WEBP
int
WebP image format
​
AVIF
int
AVIF image format

​
PMTilesTilesetType

class PMTilesTilesetType(Enum)
The type of tile to generate.

​
Values

​
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()

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
DataFrame
required
The features to generate tiles from.
​
config
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

​
tiles_df
DataFrame
required
The DataFrame of tiles to write
​
path
str
required
The path to write the PMTiles file to
​
config
Optional[PMTilesConfig]
The configuration for generating the PMTiles file. If None, the config will be generated from the features dataframe
​
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.
​
storage_level
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
DataFrame
required
The DataFrame of features to generate tiles from.
​
path
str
required
The path to write the PMTiles file to.
​
config
GenerationConfig
required
The configuration for generating tiles.
​
pmtiles_config
PMTilesConfig
required
The configuration for generating the PMTiles file.
​
storage_level
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
DataFrame
required
The DataFrame of features to generate tiles from.
​
path
str
required
The path to write the PMTiles file to.
​
config
GenerationConfig
required
The configuration for generating tiles. If None, a default config will be used.
​
pmtiles_config
PMTilesConfig
required
The configuration for generating the PMTiles file. If None, a default config will be used.
​
storage_level
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.
​
_map
Any
required
The map object to which the layer will be added.
​
s3_uri
str
required
The S3 URI of the PMTiles file.
​
name
str
required
A descriptive name of the layer. Will default to the file name if not provided.
​
style
dict
required
The style of the layer. See https://leafmap.org/notebooks/82_pmtiles/
​
overlay
bool
required
Whether or not the layer should be an overlay or base layer.
​
show
bool
required
Whether or not the layer should be shown by default.
​
zoom_to_layer
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

​
features_df
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

​
df
DataFrame
required
The DataFrame of features to generate tiles from.
​
path
str
required
The path to write the PMTiles file to.
​
render
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

​
layers
Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]]
required
The layers to show. see overview for more information
​
basemap
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'
​
self
string
required
Parameter description
​
df
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

​
self
string
required
Parameter description
​
df
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()