> ## 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) Scala Object

> Scala API 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`

```scala theme={"system"}
case class GenerationConfig(
  minZoom: Int = 0,
  maxZoom: Int = 15,
  tileResolution: Int = 4096,
  buffer: Double = 0.1,
  featureFilter: Option[Column] = None,
  tileFilter: Option[Column] = None,
  featureSimplify: Option[Column] = None,
  maxFeaturesPerTile: Option[Int] = Some(50000),
  cacheFrequency: Option[Int] = Some(2),
  persistStorageLevel: StorageLevel = StorageLevel.MEMORY_AND_DISK,
  maxDatasetSize: Option[Int] = None,
  partitionCount: Option[Int] = None,
  repartitionFrequency: Option[Int] = None,
  convertPolygonsToLabelPoints: Boolean = false
) extends Product with Serializable
```

Configuration for generating vector tiles.

### Parameters

<ParamField path="minZoom" type="Int" default="0">
  The lowest zoom for which to generate tiles
</ParamField>

<ParamField path="maxZoom" type="Int" default="15">
  The highest zoom for which to generate tiles
</ParamField>

<ParamField path="tileResolution" type="Int" default="4096">
  The resolution of the tiles to generate
</ParamField>

<ParamField path="buffer" type="Double" 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="featureFilter" type="Option[Column]" default="None">
  A predicate Column for filtering features, optional
</ParamField>

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

<ParamField path="featureSimplify" type="Option[Column]" default="None">
  A Column for manipulating feature geometries, optional
</ParamField>

<ParamField path="maxFeaturesPerTile" type="Option[Int]" default="Some(50000)">
  The maximum number of features to include in each tile, optional
</ParamField>

<ParamField path="cacheFrequency" type="Option[Int]" default="Some(2)">
  The frequency at which to cache the dataset, optional. E.g 2 means every 2nd zoom level. Default is 2
</ParamField>

<ParamField path="persistStorageLevel" type="StorageLevel" default="StorageLevel.MEMORY_AND_DISK">
  The storage level to persist the dataset at. Default is DISK\_ONLY
</ParamField>

<ParamField path="maxDatasetSize" type="Option[Int]" default="None">
  The maximum size of the dataset from which to generate tiles, optional. If the dataset is larger than this, it will be reduced to this size by randomly sampling features
</ParamField>

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

<ParamField path="repartitionFrequency" type="Option[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="convertPolygonsToLabelPoints" type="Boolean" default="false">
  Experimental, Unstable feature. Whether to replace polygons with a point in each tile the Polygon appears in. Default is false
</ParamField>

## `generate()`

Generates tiles from a set of features.

```scala theme={"system"}
def generate(
  features: Dataset[Row],
  config: GenerationConfig = GenerationConfig()
): Dataset[Row]
```

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.

### Parameters

<ParamField path="features" type="Dataset[Row]" required>
  The features to generate tiles from
</ParamField>

<ParamField path="config" type="GenerationConfig" default="GenerationConfig()">
  The configuration for generating tiles
</ParamField>

### Returns

<ResponseField path="Dataset[Row]" type="Dataset[Row]">
  A Dataset of tiles ready to be output as MVTs
</ResponseField>

## `generatePMTiles()`

Generates and writes PMTiles from a DataFrame of features.

```scala theme={"system"}
def generatePMTiles(
  features: Dataset[Row],
  path: String,
  config: GenerationConfig = GenerationConfig(),
  pmtilesConfig: Option[PMTilesConfig] = Option.empty,
  storageLevel: Option[StorageLevel] = Some(StorageLevel.MEMORY_AND_DISK)
): Unit
```

Wrapper over `VTiles.generate` and `VTiles.writePMTiles`.

### Parameters

<ParamField path="features" type="Dataset[Row]" required>
  The DataFrame of features to generate tiles from
</ParamField>

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

<ParamField path="config" type="GenerationConfig" default="GenerationConfig()">
  The configuration for generating tiles
</ParamField>

<ParamField path="pmtilesConfig" type="Option[PMTilesConfig]" default="Option.empty">
  The configuration for generating the PMTiles file
</ParamField>

<ParamField path="storageLevel" type="Option[StorageLevel]" default="Some(StorageLevel.MEMORY_AND_DISK)">
  The storage level to cache the tiles DataFrame at. If None, the DataFrame will not be cached
</ParamField>

## `getPMTilesConfigBuilder()`

Retrieves a new PMTilesConfigBuilder for generating a PMTilesConfig.

```scala theme={"system"}
def getPMTilesConfigBuilder: PMTilesConfigBuilder
```

### Returns

<ResponseField path="PMTilesConfigBuilder" type="PMTilesConfigBuilder">
  A PMTilesConfigBuilder for generating a PMTilesConfig
</ResponseField>

## `getQuickConfig()`

Retrieves a default GenerationConfig for generating tiles.

```scala theme={"system"}
def getQuickConfig: GenerationConfig
```

This configuration is optimized for quick (less than 5 minute 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 path="GenerationConfig" type="GenerationConfig">
  A default GenerationConfig for generating tiles
</ResponseField>

## `writePMTiles()`

Writes a DataFrame of tiles to a PMTiles file.

```scala theme={"system"}
def writePMTiles(
  tilesDf: DataFrame,
  path: String,
  config: Option[PMTilesConfig] = Option.empty,
  featuresDf: Option[Dataset[Row]] = Option.empty,
  storageLevel: Option[StorageLevel] = Some(StorageLevel.DISK_ONLY)
): Unit
```

### Parameters

<ParamField path="tilesDf" type="DataFrame" required>
  The dataframe of tiles to write. Output from the generate method
</ParamField>

<ParamField path="path" type="String" required>
  The path to write the tiles to. May be S3 or the local filesystem
</ParamField>

<ParamField path="config" type="Option[PMTilesConfig]" default="Option.empty">
  A PMTilesConfig to write with the tiles. If not provided, a config will be generated from the featuresDf instead
</ParamField>

<ParamField path="featuresDf" type="Option[Dataset[Row]]" default="Option.empty">
  A dataframe of the features the tilesDf was generated from. Used to generate a config from. If not provided, a config must be provided
</ParamField>

<ParamField path="storageLevel" type="Option[StorageLevel]" default="Some(StorageLevel.DISK_ONLY)">
  The storage level to cache the tilesDf at. Default is DISK\_ONLY. Providing None will not cache the tilesDf
</ParamField>

## Type Aliases

The VTiles object provides access to the following PMTiles-related types:

* `PMTileType`: Tile types supported by PMTiles format
* `PMTilesCompressionType`: Compression types supported by PMTiles format
* `PMTilesConfig`: Configuration for generating PMTiles
* `PMTilesConfigBuilder`: Builder for creating a PMTilesConfig
* `PMTilesWriter`: Writer for PMTiles files

## Usage Examples

```scala theme={"system"}
import com.wherobots.VTiles
import org.apache.spark.sql.Dataset

// Create a quick configuration for tile generation
val quickConfig = VTiles.getQuickConfig

// Generate tiles from features
val tiles = VTiles.generate(featuresDataset, quickConfig)

// Generate and write PMTiles directly
VTiles.generatePMTiles(
  features = featuresDataset,
  path = "s3://my-bucket/tiles.pmtiles",
  config = quickConfig
)

// Create a custom configuration
val customConfig = VTiles.GenerationConfig(
  minZoom = 0,
  maxZoom = 12,
  tileResolution = 2048,
  maxFeaturesPerTile = Some(10000)
)

// Generate tiles with custom config
val customTiles = VTiles.generate(featuresDataset, customConfig)

// Write tiles to PMTiles format
VTiles.writePMTiles(
  tilesDf = customTiles,
  path = "s3://my-bucket/custom-tiles.pmtiles",
  featuresDf = Some(featuresDataset)
)
```