Skip to content

About

A modern, rust-powered vector tiles generator for R.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

 
 

freestiler freestiler logo

R Package R-universe version pages-build-deployment

freestiler creates PMTiles vector tilesets from R. Give it an sf object, a file on disk, or a DuckDB SQL query, and it writes a .pmtiles archive you can serve locally or from static hosting. The tiling engine is Rust (freestiler-core) linked in-process via extendr.

About this fork

R-only fork of walkerke/freestiler. Tracks upstream’s R API while always compiling both Rust backends into native builds (including Windows):

Backend Role
Rust DuckDB (bundled) freestile_query(), engine = "duckdb" file reads, streaming points
GeoParquet (native) Direct .parquet tiling via freestile_file()

Upstream often disables DuckDB on Windows CRAN builds; here it is on by default (Rtools GNU/UCRT). The DLL is self-contained — no runtime DuckDB/GeoParquet install on PATH.

Python packaging is not maintained here; use upstream for that.

Direction of travel for this fork (see AGENTS.md and dev/docs/product-gaps.md): strengthen freestiler-core first (layer-spec ingest, memory-honest multi-layer, recipes/metadata), with a possible Rust CLI as the primary non-R surface, then thin R bindings. Dynamic XYZ serving and style/map packaging are later work.

Installation

# install.packages("pak")
pak::pak("jimbrig/freestiler")

Local clone:

just install   # user library
# or: Rscript tools/install.R

r-universe binary (when published — no Rust toolchain required):

install.packages(
  "freestiler",
  repos = c("https://jimbrig.r-universe.dev", "https://cloud.r-project.org")
)

Upstream CRAN / walkerke.r-universe builds may still omit Rust DuckDB on Windows.

library(freestiler)
freestiler:::.has_rust_duckdb()
freestiler:::.has_rust_geoparquet()

Maintainer commands: just build, just test, just smoke, just document, just site.

Quick start

library(sf)
library(freestiler)

nc <- st_read(system.file("shape/nc.shp", package = "sf"))
freestile(nc, "nc_counties.pmtiles", layer_name = "counties")
view_tiles("nc_counties.pmtiles")

Larger sf example (US block groups via tigris):

library(tigris)
options(tigris_use_cache = TRUE)

freestile(
  block_groups(cb = TRUE),
  "us_bgs.pmtiles",
  layer_name = "bgs",
  min_zoom = 4,
  max_zoom = 12
)

File and SQL input (out of R memory)

freestile_file("census_blocks.parquet", "blocks.pmtiles")
freestile_file("counties.gpkg", "counties.pmtiles", engine = "duckdb")

freestile_query(
  query = "SELECT * FROM read_parquet('blocks.parquet') WHERE state = 'NC'",
  output = "nc_blocks.pmtiles",
  layer_name = "blocks"
)

# large point sets — streaming (points only today)
freestile_query(
  query = "SELECT * FROM read_parquet('points.parquet')",
  output = "points.pmtiles",
  layer_name = "pts",
  streaming = "always"
)

Multi-layer (sf today)

freestile(
  list(
    counties = freestile_layer(nc, min_zoom = 0, max_zoom = 10),
    centroids = freestile_layer(st_centroid(nc), min_zoom = 6, max_zoom = 14)
  ),
  "nc_layers.pmtiles"
)

Multi-layer from files/queries without loading sf is tracked work (API parity with the in-memory path).

Viewing with mapgl

library(mapgl)

serve_tiles("us_bgs.pmtiles")

maplibre(hash = TRUE) |>
  add_pmtiles_source(
    id = "bgs-src",
    url = "http://localhost:8080/us_bgs.pmtiles",
    promote_id = "GEOID"
  ) |>
  add_fill_layer(
    id = "bgs-fill",
    source = "bgs-src",
    source_layer = "bgs",
    fill_color = "navy",
    fill_opacity = 0.5
  )

serve_tiles() is convenience httpuv with CORS + Range. For multi-GB archives prefer an external range-capable server (e.g. npx http-server … --cors -c-1).

Formats and extras

  • Default tile format: MVT; optional tile_format = "mlt" (MapLibre Tiles).
  • H3 zoom-adaptive hex binning: freestile_h3() / view_h3_tiles().
  • Categorical point clustering via freestile(..., category = …) (see NEWS / vignettes).

Known gaps (this fork)

Honest limitations relative to a full “data → tiles → style → map → serve” pipeline are summarized in dev/docs/product-gaps.md (ingest parity, recipes, overviews, TileJSON/style packaging, dynamic serve). Short version:

  1. API parity — multi-layer + per-layer encode knobs are richest on sf; file/query paths are mostly single-layer today.
  2. Thinning defaults — without drop_rate / zoom discipline, archives can be huge; cartographic “recipe” tooling is not packaged yet.
  3. Map packaging — beyond view_tiles() / mapgl glue, there is no first-class style/TileJSON/recipe export for MapLibre clients.
  4. Dynamic tiles — product is batch PMTiles (+ static HTTP), not on-demand MVT/MLT XYZ from DuckDB/GeoParquet.

Tracked work: open issues on this repo; near-term themes in AGENTS.md.

Learn more

About

A modern, rust-powered vector tiles generator for R.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages