> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vector Tiles (VTiles) Python API

> Python module for Vector tile generation.

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`

```python theme={"system"}
class GenerationConfig
```

Configuration for generating vector tiles.

### Attributes

<ResponseField name="min_zoom" type="int">
  The lowest zoom for which to generate tiles
</ResponseField>

<ResponseField name="max_zoom" type="int">
  The highest zoom for which to generate tiles
</ResponseField>

<ResponseField name="tile_resolution" type="int">
  The resolution of the tiles to generate
</ResponseField>

<ResponseField name="buffer" type="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
</ResponseField>

<ResponseField name="feature_filter" type="Optional[Column]">
  A predicate Column for filtering features, optional
</ResponseField>

<ResponseField name="tile_filter" type="Optional[Column]">
  A Column for manipulating the array of features within a tile, optional
</ResponseField>

<ResponseField name="feature_simplify" type="Optional[Column]">
  A Column for manipulating feature geometries, optional
</ResponseField>

<ResponseField name="max_features_per_tile" type="Optional[int]">
  The maximum number of features to include in each tile, optional
</ResponseField>

<ResponseField name="cache_frequency" type="Optional[int]">
  The frequency at which to cache the dataset, optional. E.g 2 means every 2nd zoom level. Default is 2
</ResponseField>

<ResponseField name="persist_storage_level" type="Optional[StorageLevel]">
  The storage level to cache the dataset at. Default is DISK\_ONLY
</ResponseField>

<ResponseField name="max_dataset_size" type="Optional[int]">
  The maximum size of the dataset from which to generate tiles, optional
</ResponseField>

<ResponseField name="partition_count" type="Optional[int]">
  The number of partitions to use in tile generation. Default is 2x the number of worker cores
</ResponseField>

<ResponseField name="repartition_frequency" type="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
</ResponseField>

<ResponseField name="convert_polygons_to_label_points" type="bool">
  Experimental, Unstable feature. Whether to replace polygons with a point in each tile the Polygon appears in. Default is false
</ResponseField>

## `with_suggested_min_zoom()`

Sets the minZoom based on heuristics of the input dataframe.

### Parameters

```python theme={"system"}
with_suggested_min_zoom(self, df: DataFrame) -> 'GenerationConfig'
```

<ParamField path="df" type="DataFrame" required>
  The dataframe that will be used along with this Config to generate tiles.
</ParamField>

### Returns

<ResponseField path="GenerationConfig" type="GenerationConfig">
  A new GenerationConfig with the minZoom set based on heuristics of the input dataframe.
</ResponseField>

## `with_suggested_max_zoom()`

Sets the maxZoom based on heuristics of the input dataframe.

```python theme={"system"}
with_suggested_max_zoom(self, df: DataFrame) -> 'GenerationConfig'
```

### Parameters

<ParamField path="df" type="DataFrame" required>
  The dataframe that will be used along with this Config to generate tiles.
</ParamField>

### Returns

<ResponseField path="GenerationConfig" type="GenerationConfig">
  A new GenerationConfig with the maxZoom set based on heuristics of the input dataframe.
</ResponseField>

## `PMTilesCompressionType`

```python theme={"system"}
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

<ResponseField name="UNKNOWN" type="int">
  Unknown compression type
</ResponseField>

<ResponseField name="NONE" type="int">
  No compression
</ResponseField>

<ResponseField name="GZIP" type="int">
  GZIP compression
</ResponseField>

<ResponseField name="BROTLI" type="int">
  Brotli compression
</ResponseField>

<ResponseField name="ZSTD" type="int">
  Zstandard compression
</ResponseField>

## `PMTilesConfig`

```python theme={"system"}
class PMTilesConfig
```

Configuration for generating PMTiles.

### Attributes

<ResponseField name="tile_type" type="TileType">
  The type of tile to generate
</ResponseField>

<ResponseField name="tile_compression_type" type="CompressionType">
  The compression type of the tile data. This should match with the actual tile data
</ResponseField>

<ResponseField name="metadata" type="str">
  The metadata to include in the PMTiles. It should be a serialized JSON object
</ResponseField>

<ResponseField name="internal_compression_type" type="CompressionType">
  The compression type of internal structures in the PMTiles
</ResponseField>

<ResponseField name="is_clustered" type="bool">
  Whether the tiles are clustered. Currently only false is supported
</ResponseField>

<ResponseField name="min_lon" type="float">
  The minimum longitude of the tileset
</ResponseField>

<ResponseField name="min_lat" type="float">
  The minimum latitude of the tileset
</ResponseField>

<ResponseField name="max_lon" type="float">
  The maximum longitude of the tileset
</ResponseField>

<ResponseField name="max_lat" type="float">
  The maximum latitude of the tileset
</ResponseField>

<ResponseField name="center_zoom" type="int">
  The zoom level of the center of the tileset
</ResponseField>

<ResponseField name="center_lon" type="float">
  The longitude of the center of the tileset
</ResponseField>

<ResponseField name="center_lat" type="float">
  The latitude of the center of the tileset
</ResponseField>

## `PMTilesConfigBuilder`

```python theme={"system"}
class PMTilesConfigBuilder
```

Builder for creating a PMTilesConfig.

### Attributes

<ResponseField name="name" type="str">
  A name for the tileset
</ResponseField>

<ResponseField name="description" type="str">
  A description of the tileset
</ResponseField>

<ResponseField name="attribution" type="str">
  An attribution string for the tileset
</ResponseField>

<ResponseField name="version" type="str">
  A version string for the tileset
</ResponseField>

<ResponseField name="tileset_type" type="TilesetType">
  The type of tileset in this archive (baselayer or overlay)
</ResponseField>

<ResponseField name="layers" type="List">
  The vector tile layer that are in the tiles
</ResponseField>

<ResponseField name="extra_metadata" type="Dict">
  Extra metadata to include in the PMTiles header
</ResponseField>

<ResponseField name="tile_type" type="TileType">
  The type of tiles in the archive
</ResponseField>

<ResponseField name="bounds" type="Polygon">
  The bounding box of the data in the tileset in lon/lat
</ResponseField>

<ResponseField name="center" type="Point">
  The central point of the tileset in lon/lat
</ResponseField>

<ResponseField name="tile_compression" type="CompressionType">
  The type of compression to apply to each tile's binary
</ResponseField>

<ResponseField name="internal_compression" type="CompressionType">
  The type of compression to apply to internal structures in the archive
</ResponseField>

<ResponseField name="is_clustered" type="bool">
  Whether the tiles are clustered(ie ordered in the archive). Currently only false is supported
</ResponseField>

## `PMTilesTileType`

```python theme={"system"}
class PMTilesTileType(Enum)
```

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

### Values

<ResponseField name="UNKNOWN" type="int">
  Unknown tile type
</ResponseField>

<ResponseField name="MVT" type="int">
  Mapbox Vector Tiles format
</ResponseField>

<ResponseField name="PNG" type="int">
  PNG image format
</ResponseField>

<ResponseField name="JPEG" type="int">
  JPEG image format
</ResponseField>

<ResponseField name="WEBP" type="int">
  WebP image format
</ResponseField>

<ResponseField name="AVIF" type="int">
  AVIF image format
</ResponseField>

## `PMTilesTilesetType`

```python theme={"system"}
class PMTilesTilesetType(Enum)
```

The type of tile to generate.

### Values

<ResponseField name="BASELAYER" type="str">
  The tileset is designed to be rendered below other layers
</ResponseField>

<ResponseField name="OVERLAY" type="str">
  The tileset is designed to be rendered above the base layer
</ResponseField>

## `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.

```python theme={"system"}
generate(dataframe: DataFrame, config: GenerationConfig) -> DataFrame
```

### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  The features to generate tiles from.
</ParamField>

<ParamField path="config" type="GenerationConfig" required>
  The configuration for generating tiles.
</ParamField>

### Returns

<ResponseField path="DataFrame" type="DataFrame">
  A DataFrame of tiles ready to be output as MVTs.
</ResponseField>

## `write_pmtiles()`

Writes a DataFrame of tiles to a PMTiles file.

```python theme={"system"}
write_pmtiles(tiles_df: DataFrame, path: str, config: Optional[PMTilesConfig], features_df: Optional[DataFrame], storage_level: Optional[StorageLevel])
```

### Parameters

<ParamField path="tiles_df" type="DataFrame" required>
  The DataFrame of tiles to write
</ParamField>

<ParamField path="path" type="str" required>
  The path to write the PMTiles file to
</ParamField>

<ParamField path="config" type="Optional[PMTilesConfig]">
  The configuration for generating the PMTiles file. If `None`, the config will be generated from the features dataframe
</ParamField>

<ParamField path="features_df" type="Optional[DataFrame]">
  The DataFrame of features that the tiles were generated from. This is used to generate the config if one is not provided.
</ParamField>

<ParamField path="storage_level" type="Optional[StorageLevel]">
  The storage level to cache the tiles DataFrame at. If `None`, the DataFrame will not be cached.
</ParamField>

## `generate_pmtiles()`

Generates and writes PMTiles from a DataFrame of features.

```python theme={"system"}
generate_pmtiles(dataframe: DataFrame, path: str, config: GenerationConfig, pmtiles_config: PMTilesConfig, storage_level: Optional[StorageLevel])
```

### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  The DataFrame of features to generate tiles from.
</ParamField>

<ParamField path="path" type="str" required>
  The path to write the PMTiles file to.
</ParamField>

<ParamField path="config" type="GenerationConfig" required>
  The configuration for generating tiles.
</ParamField>

<ParamField path="pmtiles_config" type="PMTilesConfig" required>
  The configuration for generating the PMTiles file.
</ParamField>

<ParamField path="storage_level" type="Optional[StorageLevel]">
  The storage level to cache the tiles DataFrame at. If `None`, the DataFrame will not be cached.
</ParamField>

### Returns

<ResponseField path="PMTiles" type="PMTiles">
  The generated PMTiles.
</ResponseField>

## `get_pmtiles_config_builder()`

Returns a PMTilesConfigBuilder for creating a PMTilesConfig.

```python theme={"system"}
get_pmtiles_config_builder() -> PMTilesConfigBuilder
```

### Parameters

<ParamField path="DataFrame" type="DataFrame" required>
  The DataFrame of features to generate tiles from.
</ParamField>

<ParamField path="path" type="str" required>
  The path to write the PMTiles file to.
</ParamField>

<ParamField path="config" type="GenerationConfig" required>
  The configuration for generating tiles. If `None`, a default config will be used.
</ParamField>

<ParamField path="pmtiles_config" type="PMTilesConfig" required>
  The configuration for generating the PMTiles file. If `None`, a default config will be used.
</ParamField>

<ParamField path="storage_level" type="Optional[StorageLevel]">
  The storage level to cache the tiles DataFrame at. If `None`, the DataFrame will not be cached.
</ParamField>

### Returns

<ResponseField path="PMTilesConfigBuilder" type="PMTilesConfigBuilder">
  An empty PMTilesConfigBuilder.
</ResponseField>

### `_add_layer()`

Adds a PMTiles layer to a leafmap Map.

```python theme={"system"}
_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.

<ParamField path="_map" type="Any" required>
  The map object to which the layer will be added.
</ParamField>

<ParamField path="s3_uri" type="str" required>
  The S3 URI of the PMTiles file.
</ParamField>

<ParamField path="name" type="str" required>
  A descriptive name of the layer. Will default to the file name if not provided.
</ParamField>

<ParamField path="style" type="dict" required>
  The style of the layer. See [https://leafmap.org/notebooks/82\_pmtiles/](https://leafmap.org/notebooks/82_pmtiles/)
</ParamField>

<ParamField path="overlay" type="bool" required>
  Whether or not the layer should be an overlay or base layer.
</ParamField>

<ParamField path="show" type="bool" required>
  Whether or not the layer should be shown by default.
</ParamField>

<ParamField path="zoom_to_layer" type="bool" required>
  Whether or not the map should zoom to the layer when it is added.
</ParamField>

### `build()`

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

#### Returns

<ResponseField path="PMTilesConfig" type="PMTilesConfig">
  A PMTilesConfig object based on the values set in the builder
</ResponseField>

### `from_features_data_frame()`

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

#### Parameters

<ParamField path="features_df" type="DataFrame" required>
  The DataFrame containing the features used to generate the tiles that will go in the PMTiles
</ParamField>

#### Returns

<ResponseField path="PMTilesConfigBuilder" type="PMTilesConfigBuilder">
  The builder object with the bounds, center, and layers set based on the features in the DataFrame.
</ResponseField>

## `get_quick_config()`

Retrieves a default GenerationConfig for generating tiles.

```python theme={"system"}
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

<ResponseField path="GenerationConfig" type="GenerationConfig">
  A default GenerationConfig for generating tiles.
</ResponseField>

## `generate_quick_pmtiles()`

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

```python theme={"system"}
generate_quick_pmtiles(df: DataFrame, path: str, render: bool) -> leafmap.Map
```

### Parameters

<ParamField path="df" type="DataFrame" required>
  The DataFrame of features to generate tiles from.
</ParamField>

<ParamField path="path" type="str" required>
  The path to write the PMTiles file to.
</ParamField>

<ParamField path="render" type="bool" required>
  Whether to return a leafmap Map object showing the generated tiles.
</ParamField>

### Returns

<ResponseField path="leafmap.Map" type="leafmap.Map">
  A leafmap Map object showing the generated tiles if render is True.
</ResponseField>

## `show_pmtiles()`

Shows a set of PMTiles layers on a leafmap Map.

```python theme={"system"}
show_pmtiles(layers: Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]], basemap: str) -> leafmap.Map
```

### Parameters

<ParamField path="layers" type="Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]]" required>
  The layers to show. see overview for more information
</ParamField>

<ParamField path="basemap" type="str" required>
  The basemap to use. string. see [https://leafmap.org/notebooks/31\_search\_basemaps/](https://leafmap.org/notebooks/31_search_basemaps/)
</ParamField>

### Returns

<ResponseField path="leafmap.Map" type="leafmap.Map">
  A leafmap Map object showing the layers as configured.
</ResponseField>

## `with_suggested_min_zoom()`

Sets the minZoom based on heuristics of the input dataframe.

```python theme={"system"}
with_suggested_min_zoom(self, df: DataFrame) -> 'GenerationConfig'
```

<ParamField path="self" type="string" required>
  Parameter description
</ParamField>

<ParamField path="df" type="DataFrame" required>
  The dataframe that will be used along with this Config to generate tiles.
</ParamField>

### Returns

<ResponseField path="GenerationConfig" type="GenerationConfig">
  A new GenerationConfig with the minZoom set based on heuristics of the input dataframe.
</ResponseField>

## `with_suggested_max_zoom()`

Sets the maxZoom based on heuristics of the input dataframe.

```python theme={"system"}
with_suggested_max_zoom(self, df: DataFrame) -> 'GenerationConfig'
```

### Parameters

<ParamField path="self" type="string" required>
  Parameter description
</ParamField>

<ParamField path="df" type="DataFrame" required>
  The dataframe that will be used along with this Config to generate tiles.
</ParamField>

### Returns

<ResponseField path="GenerationConfig" type="GenerationConfig">
  A new GenerationConfig with the maxZoom set based on heuristics of the input dataframe.
</ResponseField>

## Usage Examples

```python theme={"system"}
from vtiles import *

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

# Example usage of GenerationConfig
instance = GenerationConfig()
```