Skip to content

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

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.

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