Skip to main content
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

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

​
minZoom
Int
default:"0"
The lowest zoom for which to generate tiles
​
maxZoom
Int
default:"15"
The highest zoom for which to generate tiles
​
tileResolution
Int
default:"4096"
The resolution of the tiles to generate
​
buffer
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
​
featureFilter
Option[Column]
default:"None"
A predicate Column for filtering features, optional
​
tileFilter
Option[Column]
default:"None"
A Column for manipulating the array of features within a tile, optional
​
featureSimplify
Option[Column]
default:"None"
A Column for manipulating feature geometries, optional
​
maxFeaturesPerTile
Option[Int]
default:"Some(50000)"
The maximum number of features to include in each tile, optional
​
cacheFrequency
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
​
persistStorageLevel
StorageLevel
default:"StorageLevel.MEMORY_AND_DISK"
The storage level to persist the dataset at. Default is DISK_ONLY
​
maxDatasetSize
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
​
partitionCount
Option[Int]
default:"None"
The number of partitions to use in tile generation. Default is 2x the number of worker cores
​
repartitionFrequency
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
​
convertPolygonsToLabelPoints
Boolean
default:"false"
Experimental, Unstable feature. Whether to replace polygons with a point in each tile the Polygon appears in. Default is false

​
generate()

Generates tiles from a set of features. 
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

​
features
Dataset[Row]
required
The features to generate tiles from
​
config
GenerationConfig
default:"GenerationConfig()"
The configuration for generating tiles

​
Returns

A Dataset of tiles ready to be output as MVTs

​
generatePMTiles()

Generates and writes PMTiles from a DataFrame of features. 
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

​
features
Dataset[Row]
required
The DataFrame of features to generate tiles from
​
path
String
required
The path to write the PMTiles file to
​
config
GenerationConfig
default:"GenerationConfig()"
The configuration for generating tiles
​
pmtilesConfig
Option[PMTilesConfig]
default:"Option.empty"
The configuration for generating the PMTiles file
​
storageLevel
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

​
getPMTilesConfigBuilder()

Retrieves a new PMTilesConfigBuilder for generating a PMTilesConfig. 
def getPMTilesConfigBuilder: PMTilesConfigBuilder

​
Returns

A PMTilesConfigBuilder for generating a PMTilesConfig

​
getQuickConfig()

Retrieves a default GenerationConfig for generating tiles. 
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

A default GenerationConfig for generating tiles

​
writePMTiles()

Writes a DataFrame of tiles to a PMTiles file. 
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

​
tilesDf
DataFrame
required
The dataframe of tiles to write. Output from the generate method
​
path
String
required
The path to write the tiles to. May be S3 or the local filesystem
​
config
Option[PMTilesConfig]
default:"Option.empty"
A PMTilesConfig to write with the tiles. If not provided, a config will be generated from the featuresDf instead
​
featuresDf
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
​
storageLevel
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

​
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

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