freestiler: Create Vector Tiles from Spatial Data

Description

Create vector tile archives in 'PMTiles' format from 'sf' spatial data frames. Supports 'Mapbox Vector Tile' ('MVT') and 'MapLibre Tile' ('MLT') output formats. Uses a 'Rust' backend via 'extendr' for fast, in-memory tiling with zero external system dependencies.

Author(s)

Maintainer: Kyle Walker kyle@walker-data.com

See Also

Useful links:

• https://walker-data.com/freestiler/

• https://github.com/walkerke/freestiler/

• Report bugs at https://github.com/walkerke/freestiler/issues

Create vector tiles from spatial data

Description

Creates a PMTiles archive containing vector tiles from one or more sf data frames. Supports both Mapbox Vector Tile (MVT) and MapLibre Tile (MLT) formats, multi-layer output, feature dropping, point clustering, and feature coalescing.

Usage

freestile(
  input,
  output,
  layer_name = NULL,
  tile_format = "mvt",
  min_zoom = 0L,
  max_zoom = 14L,
  base_zoom = NULL,
  drop_rate = NULL,
  cluster_distance = NULL,
  cluster_maxzoom = NULL,
  coalesce = FALSE,
  simplification = TRUE,
  generate_ids = TRUE,
  overwrite = TRUE,
  quiet = FALSE
)

Arguments

Details

Input data in any coordinate reference system (CRS) is automatically reprojected to WGS84 (EPSG:4326) before tiling.

Value

The output file path (invisibly).

Examples

## Not run: 
library(sf)
nc <- st_read(system.file("shape/nc.shp", package = "sf"))

# Single layer
freestile(nc, "nc.pmtiles", layer_name = "counties")

# Multi-layer
pts <- st_centroid(nc)
freestile(
  list(counties = nc, centroids = pts),
  "nc_layers.pmtiles"
)

# With dropping and coalescing
freestile(nc, "nc_drop.pmtiles", drop_rate = 2.5, coalesce = TRUE)

# With point clustering
freestile(pts, "pts.pmtiles", cluster_distance = 50, cluster_maxzoom = 8)

## End(Not run)

Create vector tiles from a spatial file

Description

Reads a GeoParquet, GeoPackage, Shapefile, or other spatial file directly into the tiling engine. Input data in any coordinate reference system is automatically reprojected to WGS84 (EPSG:4326) before tiling.

Usage

freestile_file(
  input,
  output,
  layer_name = NULL,
  tile_format = "mvt",
  min_zoom = 0L,
  max_zoom = 14L,
  base_zoom = NULL,
  drop_rate = NULL,
  cluster_distance = NULL,
  cluster_maxzoom = NULL,
  coalesce = FALSE,
  simplification = TRUE,
  overwrite = TRUE,
  quiet = FALSE,
  engine = "geoparquet"
)

Arguments

Details

The GeoParquet engine requires compilation with FREESTILER_GEOPARQUET=true. The DuckDB engine uses the Rust DuckDB backend when included in the build (enabled by default for native builds), or falls back to the R duckdb package. Control backend selection with options(freestiler.duckdb_backend = "auto"|"rust"|"r").

Value

The output file path (invisibly).

Examples

## Not run: 
freestile_file("data.parquet", "output.pmtiles")
freestile_file("data.gpkg", "output.pmtiles", engine = "duckdb")

## End(Not run)

Create a layer specification with per-layer zoom range

Description

Wraps an sf object with optional per-layer zoom range overrides for use in multi-layer tile generation.

Usage

freestile_layer(input, min_zoom = NULL, max_zoom = NULL)

Arguments

Value

A freestile_layer object (list with class attribute).

Examples

## Not run: 
library(sf)
nc <- st_read(system.file("shape/nc.shp", package = "sf"))
roads <- st_read("roads.shp")

freestile(
  list(
    counties = freestile_layer(nc, min_zoom = 0, max_zoom = 10),
    roads = freestile_layer(roads, min_zoom = 8, max_zoom = 14)
  ),
  "layers.pmtiles"
)

## End(Not run)

Create vector tiles from a DuckDB SQL query

Description

Executes a SQL query via DuckDB's spatial extension and pipes the results into the tiling engine. Uses the Rust DuckDB backend when included in the build (enabled by default for native builds), or falls back to the R duckdb package. Control backend selection with options(freestiler.duckdb_backend = "auto"|"rust"|"r").

Usage

freestile_query(
  query,
  output,
  db_path = NULL,
  layer_name = NULL,
  tile_format = "mvt",
  min_zoom = 0L,
  max_zoom = 14L,
  base_zoom = NULL,
  drop_rate = NULL,
  cluster_distance = NULL,
  cluster_maxzoom = NULL,
  coalesce = FALSE,
  simplification = TRUE,
  overwrite = TRUE,
  quiet = FALSE,
  source_crs = NULL,
  streaming = "auto"
)

Arguments

Details

When using the R fallback, source_crs must be supplied explicitly so the query result can be interpreted or reprojected correctly. Pass "EPSG:4326" if the SQL already returns WGS84 geometry, or the source CRS string (for example "EPSG:4267") to have DuckDB reproject to WGS84 before tiling. For file-based input where the CRS is embedded in the file, use freestile_file() with engine = "duckdb" instead, which auto-detects the source CRS.

Value

The output file path (invisibly).

Examples

## Not run: 
# Query a GeoParquet file
freestile_query(
  "SELECT * FROM read_parquet('data.parquet') WHERE pop > 50000",
  "output.pmtiles"
)

# Query a Shapefile
freestile_query(
  "SELECT * FROM ST_Read('counties.shp')",
  "counties.pmtiles"
)

# Query with an existing DuckDB database
freestile_query(
  "SELECT * FROM my_table WHERE region = 'West'",
  "west.pmtiles",
  db_path = "my_database.duckdb"
)

## End(Not run)

Read PMTiles metadata

Description

Reads the header and JSON metadata from a PMTiles file.

Usage

pmtiles_metadata(path)

Arguments

Value

A list with header fields (zoom levels, bounds, tile format, etc.) and a nested metadata element containing vector layer information, or NULL on error.

Examples

## Not run: 
meta <- pmtiles_metadata("my_tiles.pmtiles")
meta$min_zoom
meta$max_zoom
meta$metadata$vector_layers

## End(Not run)

Create vector tiles from spatial data (multi-layer support)

Description

Create vector tiles from spatial data (multi-layer support)

Usage

rust_freestile(
  layers,
  output_path,
  tile_format,
  global_min_zoom,
  global_max_zoom,
  base_zoom,
  do_simplify,
  generate_ids,
  quiet,
  drop_rate,
  cluster_distance,
  cluster_maxzoom,
  do_coalesce
)

Arguments

Create tiles from a file via DuckDB spatial (requires duckdb feature)

Description

Create tiles from a file via DuckDB spatial (requires duckdb feature)

Usage

rust_freestile_duckdb(
  input_path,
  output_path,
  layer_name,
  tile_format,
  min_zoom,
  max_zoom,
  base_zoom,
  do_simplify,
  drop_rate,
  cluster_distance,
  cluster_maxzoom,
  do_coalesce,
  quiet
)

Arguments

Create tiles from a DuckDB SQL query (requires duckdb feature)

Description

Create tiles from a DuckDB SQL query (requires duckdb feature)

Usage

rust_freestile_duckdb_query(
  sql,
  db_path,
  output_path,
  layer_name,
  tile_format,
  min_zoom,
  max_zoom,
  base_zoom,
  do_simplify,
  drop_rate,
  cluster_distance,
  cluster_maxzoom,
  do_coalesce,
  quiet,
  streaming_mode
)

Arguments

Create tiles from a GeoParquet file (requires geoparquet feature)

Description

Create tiles from a GeoParquet file (requires geoparquet feature)

Usage

rust_freestile_file(
  input_path,
  output_path,
  layer_name,
  tile_format,
  min_zoom,
  max_zoom,
  base_zoom,
  do_simplify,
  drop_rate,
  cluster_distance,
  cluster_maxzoom,
  do_coalesce,
  quiet
)

Arguments

Read PMTiles header and metadata as a JSON string

Description

Read PMTiles header and metadata as a JSON string

Usage

rust_pmtiles_metadata(path)

Arguments

Serve PMTiles files via local HTTP server with CORS

Description

Start a local HTTP server to serve PMTiles files with CORS headers and HTTP range request support. This allows PMTiles to be consumed by mapgl and MapLibre GL JS. The server runs in the background and can be stopped with stop_server().

Usage

serve_tiles(path, port = 8080)

Arguments

Details

If a server is already running on the requested port, it is stopped first.

The server uses httpuv (a dependency of Shiny) to serve static files with the CORS and range-request headers that PMTiles requires. Works well for files up to ~1 GB. For larger files, consider an external server like npx http-server /path --cors -c-1.

Value

Invisibly returns a list with url, port, and dir. The server handle is stored internally so it can be stopped with stop_server().

See Also

stop_server(), view_tiles()

Examples

## Not run: 
# Serve a directory
serve_tiles("/tmp/tiles")

# Serve a single file (its directory is served)
serve_tiles("us_bgs.pmtiles")

# Stop when done
stop_server()

## End(Not run)

Stop a local tile server

Description

Stop a local tile server

Usage

stop_server(port = NULL)

Arguments

Value

Invisibly returns TRUE if a server was stopped.

See Also

serve_tiles()

Examples

## Not run: 
serve_tiles("tiles/")
stop_server()        # stop all
stop_server(8080)    # stop specific port

## End(Not run)

Quickly view a PMTiles file on an interactive map

Description

Starts a local tile server (if needed) and creates an interactive mapgl map showing the tileset. Layer type and styling are auto-detected from the PMTiles metadata when possible.

Usage

view_tiles(
  input,
  layer = NULL,
  layer_type = NULL,
  color = NULL,
  opacity = 0.5,
  port = 8080,
  promote_id = NULL
)

Arguments

Value

A mapgl map object (can be piped into further mapgl operations).

See Also

serve_tiles(), freestile()

Examples

## Not run: 
freestile(nc, "nc.pmtiles", layer_name = "counties")
view_tiles("nc.pmtiles")

# Override auto-detection
view_tiles("roads.pmtiles", layer_type = "line", color = "red")

# Point data
view_tiles("airports.pmtiles", layer_type = "circle", color = "orange")

## End(Not run)