Vector tiles (wherobots.vtiles)

from wherobots import vtiles

generate

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

Generates tiles from a set of features. The features must have a geometry column of the Geometry type. An optional layer column of string type represents what layer that feature belongs in; when it is absent every feature is placed in a layer named “default”. 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

DataFrame

required

the features to generate tiles from

GenerationConfig

default:"None"

the configuration for generating tiles

Returns

DataFrame

a DataFrame of tiles ready to be output as MVTs

generate_pmtiles

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

Generates and writes PMTiles from a DataFrame of features.

Parameters

DataFrame

required

the DataFrame of features to generate tiles from

str

required

the path to write the PMTiles file to

GenerationConfig

default:"None"

the configuration for generating tiles

PMTilesConfig

default:"None"

the configuration for generating the PMTiles file

Optional[StorageLevel]

default:"StorageLevel.MEMORY_AND_DISK"

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

generate_quick_pmtiles

generate_quick_pmtiles(
    df: DataFrame,
    path: str,
    render: bool = True,
) -> Optional[WbglMap]

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

Parameters

DataFrame

required

the DataFrame of features to generate tiles from

str

required

the path to write the PMTiles file to

bool

default:"True"

whether to return a Wherobots-GL Map showing the generated tiles

Returns

Optional[WbglMap]

a Wherobots-GL Map showing the generated tiles if render is True

GenerationConfig

GenerationConfig(
    min_zoom: int = 0,
    max_zoom: int = 15,
    tile_resolution: int = 4096,
    buffer: float = 0.1,
    feature_filter: Optional[Column] = None,
    tile_filter: Optional[Column] = None,
    feature_simplify: Optional[Column] = None,
    max_features_per_tile: Optional[int] = 50000,
    cache_frequency: Optional[int] = None,
    persist_storage_level: Optional[StorageLevel] = None,
    max_dataset_size: Optional[int] = None,
    partition_count: Optional[int] = None,
    repartition_frequency: Optional[int] = None,
    convert_polygons_to_label_points: bool = False,
)

Configuration for generating vector tiles.

Parameters

int

default:"0"

the lowest zoom for which to generate tiles

int

default:"15"

the highest zoom for which to generate tiles

int

default:"4096"

the resolution of the tiles to generate

float

default:"0.1"

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]

default:"None"

a predicate Column for filtering features, optional

Optional[Column]

default:"None"

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

Optional[Column]

default:"None"

a Column for manipulating feature geometries, optional

Optional[int]

default:"50000"

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

Optional[int]

default:"None"

DEPRECATED - no longer used. Tiles are now generated and checkpointed at each zoom level. This parameter is retained for backwards compatibility.

Optional[StorageLevel]

default:"None"

the storage level to persist intermediate features at. Default is MEMORY_AND_DISK

Optional[int]

default:"None"

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

Optional[int]

default:"None"

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

Optional[int]

default:"None"

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

default:"False"

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

with_suggested_max_zoom()

with_suggested_max_zoom(df: DataFrame) -> GenerationConfig

Sets the maxZoom based on heuristics of the input dataframe.

Parameters

DataFrame

required

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

Returns

GenerationConfig

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

with_suggested_min_zoom()

with_suggested_min_zoom(df: DataFrame) -> GenerationConfig

Sets the minZoom based on heuristics of the input dataframe. The suggestion is clamped to this config’s max_zoom so datasets with point-like extents (which suggest very deep zooms) still produce a valid config.

Parameters

DataFrame

required

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

Returns

GenerationConfig

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

get_pmtiles_config_builder

get_pmtiles_config_builder() -> PMTilesConfigBuilder

Returns a PMTilesConfigBuilder for creating a PMTilesConfig.

Returns

PMTilesConfigBuilder

an empty PMTilesConfigBuilder

get_quick_config

get_quick_config() -> GenerationConfig

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

GenerationConfig

a default GenerationConfig for generating tiles

PMTilesCompressionType

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

int

unknown

int

none

int

gzip

int

brotli

int

zstd

Values

PMTilesCompressionType

3

PMTilesCompressionType

2

PMTilesCompressionType

1

PMTilesCompressionType

0

PMTilesCompressionType

4

as_java()

as_java()

PMTilesConfig

PMTilesConfig(
    tile_type: TileType,
    tile_compression_type: CompressionType,
    metadata: str,
    internal_compression_type: CompressionType = CompressionType.GZIP,
    is_clustered: bool = False,
    min_lon: float = -180,
    min_lat: float = -90,
    max_lon: float = 180,
    max_lat: float = 90,
    center_zoom: int = 0,
    center_lon: float = 0,
    center_lat: float = 0,
)

Configuration for generating PMTiles.

Parameters

TileType

required

The type of tile to generate

CompressionType

required

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

str

required

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

CompressionType

default:"CompressionType.GZIP"

The compression type of internal structures in the PMTiles.

bool

default:"False"

Whether the tiles are clustered. Currently only false is supported.

float

default:"-180"

The minimum longitude of the tileset

float

default:"-90"

The minimum latitude of the tileset

float

default:"180"

The maximum longitude of the tileset

float

default:"90"

The maximum latitude of the tileset

int

default:"0"

The zoom level of the center of the tileset

float

default:"0"

The longitude of the center of the tileset

float

default:"0"

The latitude of the center of the tileset

as_java()

as_java()

PMTilesConfigBuilder

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.

add_layer()

add_layer(
    layer_name: str,
    layer_description: Optional[str] = None,
    min_zoom: Optional[int] = None,
    max_zoom: Optional[int] = None,
    fields: Optional[Dict[str, str]] = None,
)

Add a layer to the PMTiles configuration.

Parameters

str

required

The name of the layer as it appears in the tiles

Optional[str]

default:"None"

An optional description of the layer

Optional[int]

default:"None"

the lowest zoom level the layer is visible at

Optional[int]

default:"None"

the highest zoom level the layer is visible at

Optional[Dict[str, str]]

default:"None"

the attributes that may be present on member features of the layer

Returns

The builder object with the new layer added

build()

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

from_features_data_frame(features_df: DataFrame) -> PMTilesConfigBuilder

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

DataFrame

required

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

Returns

PMTilesConfigBuilder

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

PMTilesTilesetType

The type of tile to generate.

Attributes

str

The tileset is designed to be rendered below other layers

str

The tileset is designed to be rendered above the base layer

Values

PMTilesTilesetType

'baselayer'

PMTilesTilesetType

'overlay'

as_java()

as_java()

PMTilesTileType

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

Attributes

int

unknown

int

mvt

int

png

int

jpeg

int

webp

int

avif

Values

PMTilesTileType

5

PMTilesTileType

3

PMTilesTileType

1

PMTilesTileType

2

PMTilesTileType

0

PMTilesTileType

4

as_java()

as_java()

show_pmtiles

show_pmtiles(
    layers: Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]],
    basemap: Optional[str] = None,
) -> Optional[WbglMap]

Shows a set of PMTiles layers inline on a Wherobots-GL 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. defaults to the file name.
fill_color / line_color: optional hex colors for the layer.

Parameters

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

required

the layers to show. see overview for more information

Optional[str]

default:"None"

optional basemap; the historical leafmap identifiers (e.g. "xyz.CartoDB.DarkMatter") are mapped to the Wherobots-GL styles (light / dark / terrain / satellite). Defaults to dark.

Returns

Optional[WbglMap]

a Wherobots-GL Map rendering the layers inline in the notebook

write_pmtiles

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

Writes a DataFrame of tiles to a PMTiles file.

Parameters

DataFrame

required

the DataFrame of tiles to write

str

required

the path to write the PMTiles file to

Optional[PMTilesConfig]

default:"None"

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

Optional[DataFrame]

default:"None"

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

Optional[StorageLevel]

default:"StorageLevel.MEMORY_AND_DISK"

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

​generate

​Parameters

​Returns

​generate_pmtiles

​Parameters

​generate_quick_pmtiles

​Parameters

​Returns

​GenerationConfig

​Parameters

​with_suggested_max_zoom()

​Parameters

​Returns

​with_suggested_min_zoom()

​Parameters

​Returns

​get_pmtiles_config_builder

​Returns

​get_quick_config

​Returns

​PMTilesCompressionType

​Attributes

​Values

​as_java()

​PMTilesConfig

​Parameters

​as_java()

​PMTilesConfigBuilder

​Attributes

​add_layer()

​Parameters

​Returns

​build()

​Returns

​from_features_data_frame()

​Parameters

​Returns

​PMTilesTilesetType

​Attributes

​Values

​as_java()

​PMTilesTileType

​Attributes

​Values

​as_java()

​show_pmtiles

​Parameters

​Returns

​write_pmtiles

​Parameters

generate

Parameters

Returns

generate_pmtiles

Parameters

generate_quick_pmtiles

Parameters

Returns

GenerationConfig

Parameters

with_suggested_max_zoom()

Parameters

Returns

with_suggested_min_zoom()

Parameters

Returns

get_pmtiles_config_builder

Returns

get_quick_config

Returns

PMTilesCompressionType

Attributes

Values

as_java()

PMTilesConfig

Parameters

as_java()

PMTilesConfigBuilder

Attributes

add_layer()

Parameters

Returns

build()

Returns

from_features_data_frame()

Parameters

Returns

PMTilesTilesetType

Attributes

Values

as_java()

PMTilesTileType

Attributes

Values

as_java()

show_pmtiles

Parameters

Returns

write_pmtiles

Parameters