Vector Tiles (VTiles) Scala Object

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

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

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

Option[Column]

default:"None"

A predicate Column for filtering features, optional

Option[Column]

default:"None"

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

Option[Column]

default:"None"

A Column for manipulating feature geometries, optional

Option[Int]

default:"Some(50000)"

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

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

StorageLevel

default:"StorageLevel.MEMORY_AND_DISK"

The storage level to persist the dataset at. Default is DISK_ONLY

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

Option[Int]

default:"None"

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

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

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

Dataset[Row]

required

The features to generate tiles from

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

Dataset[Row]

required

The DataFrame of features to generate tiles from

String

required

The path to write the PMTiles file to

GenerationConfig

default:"GenerationConfig()"

The configuration for generating tiles

Option[PMTilesConfig]

default:"Option.empty"

The configuration for generating the PMTiles file

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

DataFrame

required

The dataframe of tiles to write. Output from the generate method

String

required

The path to write the tiles to. May be S3 or the local filesystem

Option[PMTilesConfig]

default:"Option.empty"

A PMTilesConfig to write with the tiles. If not provided, a config will be generated from the featuresDf instead

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

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

Wherobots Cloud REST API

WherobotsDB

Vector tiles (PMTiles)

Havasu (Iceberg) table management

GeoStats and Map Matching

Rasterflow

Vector Tiles (VTiles) Scala Object

`GenerationConfig`

Parameters

`generate()`

Parameters

Returns

`generatePMTiles()`

Parameters

`getPMTilesConfigBuilder()`

Returns

`getQuickConfig()`

Returns

`writePMTiles()`

Parameters

Type Aliases

Usage Examples

​GenerationConfig

​Parameters

​generate()

​Parameters

​Returns

​generatePMTiles()

​Parameters

​getPMTilesConfigBuilder()

​Returns

​getQuickConfig()

​Returns

​writePMTiles()

​Parameters

​Type Aliases

​Usage Examples

`GenerationConfig`

Parameters

`generate()`

Parameters

Returns

`generatePMTiles()`

Parameters

`getPMTilesConfigBuilder()`

Returns

`getQuickConfig()`

Returns

`writePMTiles()`

Parameters

Type Aliases

Usage Examples