% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ddbs_mvt.R
\name{ddbs_write_mbtiles}
\alias{ddbs_write_mbtiles}
\title{Write a Mapbox Vector Tile pyramid to an MBTiles file}
\usage{
ddbs_write_mbtiles(
  x,
  dsn,
  layer_name = "layer",
  zoom_levels = 0:6,
  extent = 4096L,
  buffer = 256L,
  conn = NULL,
  overwrite = FALSE,
  quiet = FALSE
)
}
\arguments{
\item{x}{Input spatial data. Can be:
\itemize{
\item A \code{duckspatial_df} object (lazy spatial data frame via dbplyr)
\item An \code{sf} object
\item A \code{tbl_lazy} from dbplyr
\item A character string naming a table/view in \code{conn}
}
Data is returned from this object.}

\item{dsn}{Path to the output \code{.mbtiles} file.}

\item{layer_name}{Name of the vector tile layer. This is the value you pass
as \code{source_layer} when adding the layer in a web map. Defaults to
\code{"layer"}.}

\item{zoom_levels}{Integer vector of zoom levels to generate (e.g.
\code{0:8}). Defaults to \code{0:6}.}

\item{extent}{Integer tile extent (resolution). Defaults to \code{4096}.}

\item{buffer}{Integer tile buffer in pixels. Defaults to \code{256}.}

\item{conn}{A connection object to a DuckDB database. If \code{NULL}, the function
runs on a temporary DuckDB database.}

\item{overwrite}{Logical. Overwrite \code{dsn} if it already exists. Defaults
to \code{FALSE}.}

\item{quiet}{A logical value. If \code{TRUE}, suppresses any informational messages.
Defaults to \code{FALSE}.}
}
\value{
The path to \code{dsn}, invisibly.
}
\description{
Generates a pyramid of Mapbox Vector Tiles (MVT) from a spatial dataset and
stores them in an \href{https://github.com/mapbox/mbtiles-spec}{MBTiles} file
(a SQLite database). For each tile in the requested zoom range the geometries
are clipped and re-projected into tile space (\code{ST_AsMVTGeom}) and encoded
into a binary vector tile (\code{ST_AsMVT}).
}
\details{
The input is re-projected to web mercator (\code{EPSG:3857}), so \code{x} must
have a CRS. All non-geometry columns are carried into the tiles as feature
properties; columns whose type is not supported by the vector tile format are
cast to \code{DOUBLE} (numeric types) or \code{VARCHAR} (everything else), and
\code{BLOB} columns are dropped.

Writing the SQLite container relies on DuckDB's \code{sqlite} extension, which
is installed and loaded automatically (an internet connection may be required
the first time).

MBTiles can be served with a vector tile server, or converted to
\href{https://github.com/protomaps/PMTiles}{PMTiles} (e.g. with the
\code{pmtiles convert} CLI) for static hosting. The resulting tiles can then
be displayed with the \pkg{mapgl} package, for example:

\preformatted{
library(mapgl)
maplibre() |>
  add_pmtiles_source(id = "src", url = "https://example.com/argentina.pmtiles") |>
  add_fill_layer(id = "fill", source = "src", source_layer = "argentina")
}
}
\examples{
\dontrun{
library(duckspatial)

argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", package = "duckspatial")
)

ddbs_write_mbtiles(
  argentina_ddbs,
  dsn         = tempfile(fileext = ".mbtiles"),
  layer_name  = "argentina",
  zoom_levels = 0:6
)
}
}
