> ## 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 (wherobots.vtiles)

> Generate vector tiles and PMTiles archives from Spark DataFrames.

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

## generate

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

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

<ParamField path="config" type="GenerationConfig" default="None">
  the configuration for generating tiles
</ParamField>

#### Returns

<ResponseField name="return" type="DataFrame">
  a DataFrame of tiles ready to be output as MVTs
</ResponseField>

## generate\_pmtiles

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

<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" default="None">
  the configuration for generating tiles
</ParamField>

<ParamField path="pmtiles_config" type="PMTilesConfig" default="None">
  the configuration for generating the PMTiles file
</ParamField>

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

## generate\_quick\_pmtiles

```python theme={"system"}
generate_quick_pmtiles(
    df: DataFrame,
    path: str,
    render: bool = True,
) -> Optional[WbglMap]
```

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

#### 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" default="True">
  whether to return a Wherobots-GL `Map` showing the generated tiles
</ParamField>

#### Returns

<ResponseField name="return" type="Optional[WbglMap]">
  a Wherobots-GL `Map` showing the generated tiles if render is True
</ResponseField>

## GenerationConfig

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

<ParamField path="min_zoom" type="int" default="0">
  the lowest zoom for which to generate tiles
</ParamField>

<ParamField path="max_zoom" type="int" default="15">
  the highest zoom for which to generate tiles
</ParamField>

<ParamField path="tile_resolution" type="int" default="4096">
  the resolution of the tiles to generate
</ParamField>

<ParamField path="buffer" type="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
</ParamField>

<ParamField path="feature_filter" type="Optional[Column]" default="None">
  a predicate Column for filtering features, optional
</ParamField>

<ParamField path="tile_filter" type="Optional[Column]" default="None">
  a Column for manipulating the array of features within a tile, optional
</ParamField>

<ParamField path="feature_simplify" type="Optional[Column]" default="None">
  a Column for manipulating feature geometries, optional
</ParamField>

<ParamField path="max_features_per_tile" type="Optional[int]" default="50000">
  the maximum number of features to include in each tile, optional
</ParamField>

<ParamField path="cache_frequency" type="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.
</ParamField>

<ParamField path="persist_storage_level" type="Optional[StorageLevel]" default="None">
  the storage level to persist intermediate features at. Default is
  MEMORY\_AND\_DISK
</ParamField>

<ParamField path="max_dataset_size" type="Optional[int]" default="None">
  the maximum size of the dataset from which to generate tiles, optional
</ParamField>

<ParamField path="partition_count" type="Optional[int]" default="None">
  the number of partitions to use in tile generation. Default is 2x the number
  of worker cores.
</ParamField>

<ParamField path="repartition_frequency" type="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.
</ParamField>

<ParamField path="convert_polygons_to_label_points" type="bool" default="False">
  Experimental, Unstable feature. whether to replace polygons with a point
  in each tile the Polygon appears in. Default is false.
</ParamField>

### with\_suggested\_max\_zoom()

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

Sets the maxZoom based on heuristics of the input dataframe.

#### Parameters

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

#### Returns

<ResponseField name="return" type="GenerationConfig">
  a new GenerationConfig with the maxZoom set based on heuristics of the input dataframe
</ResponseField>

### with\_suggested\_min\_zoom()

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

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

#### Returns

<ResponseField name="return" type="GenerationConfig">
  a new GenerationConfig with the minZoom set based on heuristics of the input dataframe
</ResponseField>

## get\_pmtiles\_config\_builder

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

Returns a PMTilesConfigBuilder for creating a PMTilesConfig.

#### Returns

<ResponseField name="return" type="PMTilesConfigBuilder">
  an empty PMTilesConfigBuilder
</ResponseField>

## get\_quick\_config

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

<ResponseField name="return" type="GenerationConfig">
  a default GenerationConfig for generating tiles
</ResponseField>

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

<ResponseField name="UNKNOWN" type="int">
  unknown
</ResponseField>

<ResponseField name="NONE" type="int">
  none
</ResponseField>

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

<ResponseField name="BROTLI" type="int">
  brotli
</ResponseField>

<ResponseField name="ZSTD" type="int">
  zstd
</ResponseField>

#### Values

<ResponseField name="BROTLI" type="PMTilesCompressionType">
  `3`
</ResponseField>

<ResponseField name="GZIP" type="PMTilesCompressionType">
  `2`
</ResponseField>

<ResponseField name="NONE" type="PMTilesCompressionType">
  `1`
</ResponseField>

<ResponseField name="UNKNOWN" type="PMTilesCompressionType">
  `0`
</ResponseField>

<ResponseField name="ZSTD" type="PMTilesCompressionType">
  `4`
</ResponseField>

### as\_java()

```python theme={"system"}
as_java()
```

## PMTilesConfig

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

<ParamField path="tile_type" type="TileType" required>
  The type of tile to generate
</ParamField>

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

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

<ParamField path="internal_compression_type" type="CompressionType" default="CompressionType.GZIP">
  The compression type of internal structures in the PMTiles.
</ParamField>

<ParamField path="is_clustered" type="bool" default="False">
  Whether the tiles are clustered. Currently only false is supported.
</ParamField>

<ParamField path="min_lon" type="float" default="-180">
  The minimum longitude of the tileset
</ParamField>

<ParamField path="min_lat" type="float" default="-90">
  The minimum latitude of the tileset
</ParamField>

<ParamField path="max_lon" type="float" default="180">
  The maximum longitude of the tileset
</ParamField>

<ParamField path="max_lat" type="float" default="90">
  The maximum latitude of the tileset
</ParamField>

<ParamField path="center_zoom" type="int" default="0">
  The zoom level of the center of the tileset
</ParamField>

<ParamField path="center_lon" type="float" default="0">
  The longitude of the center of the tileset
</ParamField>

<ParamField path="center_lat" type="float" default="0">
  The latitude of the center of the tileset
</ParamField>

### as\_java()

```python theme={"system"}
as_java()
```

## PMTilesConfigBuilder

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

### add\_layer()

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

<ParamField path="layer_name" type="str" required>
  The name of the layer as it appears in the tiles
</ParamField>

<ParamField path="layer_description" type="Optional[str]" default="None">
  An optional description of the layer
</ParamField>

<ParamField path="min_zoom" type="Optional[int]" default="None">
  the lowest zoom level the layer is visible at
</ParamField>

<ParamField path="max_zoom" type="Optional[int]" default="None">
  the highest zoom level the layer is visible at
</ParamField>

<ParamField path="fields" type="Optional[Dict[str, str]]" default="None">
  the attributes that may be present on member features of the layer
</ParamField>

#### Returns

<ResponseField name="return">
  The builder object with the new layer added
</ResponseField>

### build()

```python theme={"system"}
build()
```

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

#### Returns

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

### from\_features\_data\_frame()

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

<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 name="return" type="PMTilesConfigBuilder">
  The builder object with the bounds, center, and layers set based on the features in the DataFrame
</ResponseField>

## PMTilesTilesetType

The type of tile to generate.

#### Attributes

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

#### Values

<ResponseField name="BASELAYER" type="PMTilesTilesetType">
  `'baselayer'`
</ResponseField>

<ResponseField name="OVERLAY" type="PMTilesTilesetType">
  `'overlay'`
</ResponseField>

### as\_java()

```python theme={"system"}
as_java()
```

## PMTilesTileType

Tile types supported by PMTiles format.

The tile type reflects the format of the tile data.

#### Attributes

<ResponseField name="UNKNOWN" type="int">
  unknown
</ResponseField>

<ResponseField name="MVT" type="int">
  mvt
</ResponseField>

<ResponseField name="PNG" type="int">
  png
</ResponseField>

<ResponseField name="JPEG" type="int">
  jpeg
</ResponseField>

<ResponseField name="WEBP" type="int">
  webp
</ResponseField>

<ResponseField name="AVIF" type="int">
  avif
</ResponseField>

#### Values

<ResponseField name="AVIF" type="PMTilesTileType">
  `5`
</ResponseField>

<ResponseField name="JPEG" type="PMTilesTileType">
  `3`
</ResponseField>

<ResponseField name="MVT" type="PMTilesTileType">
  `1`
</ResponseField>

<ResponseField name="PNG" type="PMTilesTileType">
  `2`
</ResponseField>

<ResponseField name="UNKNOWN" type="PMTilesTileType">
  `0`
</ResponseField>

<ResponseField name="WEBP" type="PMTilesTileType">
  `4`
</ResponseField>

### as\_java()

```python theme={"system"}
as_java()
```

## show\_pmtiles

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

<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="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.
</ParamField>

#### Returns

<ResponseField name="return" type="Optional[WbglMap]">
  a Wherobots-GL `Map` rendering the layers inline in the notebook
</ResponseField>

## write\_pmtiles

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

<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]" default="None">
  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]" default="None">
  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]" default="StorageLevel.MEMORY_AND_DISK">
  the storage level to cache the tiles DataFrame at. If None, the DataFrame will not be
  cached
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.