% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{spatial_explode}
\alias{spatial_explode}
\title{Explode multipart geometries into single-part features}
\usage{
spatial_explode(
  x,
  geom = "geometry",
  crs = NA,
  out_geom = NULL,
  part = NULL,
  flush_rows = NULL
)
}
\arguments{
\item{x}{A \code{vectra_node} (from \code{\link[=tbl]{tbl()}}, \code{\link[=tbl_tiff]{tbl_tiff()}}, any verb chain, ...).
It is consumed by the stream.}

\item{geom}{Name of the input geometry column holding hex-WKB or WKT strings.
Default \code{"geometry"}. Ignored when \code{coords} is given.}

\item{crs}{Coordinate reference system of the input geometry, in any form
\code{\link[sf:st_crs]{sf::st_crs()}} accepts (EPSG integer, WKT, proj string). Defaults to the
CRS the upstream node carries, or unknown.}

\item{out_geom}{Name of the output geometry column. Defaults to \code{geom}
(or \code{"geometry"} when \code{coords} is used).}

\item{part}{Optional name of an integer column numbering the parts within each
source feature, 1-based. Default \code{NULL} adds no such column.}

\item{flush_rows}{Transformed rows buffered before a spill flush. Larger
values mean fewer, bigger temporary files. Defaults to
\code{getOption("vectra.spatial_flush", 5e5)}.}
}
\value{
A \code{vectra_node} of single-part features, backed by temporary \code{.vtr}
spills (removed when the node is garbage-collected) and carrying the input
CRS.
}
\description{
Streams a lazy vectra query and splits every multipart geometry into its
component single-part geometries: a \code{MULTIPOLYGON} becomes one row per
polygon, a \code{MULTILINESTRING} one row per linestring, a \code{MULTIPOINT} one row
per point, and a \code{GEOMETRYCOLLECTION} one row per member (recursively). The
attributes of the source feature are copied onto each part. Already
single-part geometries pass through unchanged, as does an empty geometry
(kept as one row). This is the streaming counterpart of the QGIS
"multipart to singleparts" tool and of \code{\link[sf:st_cast]{sf::st_cast()}} to a single-part type.
}
\details{
One batch is decoded, exploded, and spilled at a time, so peak memory tracks
one batch and its parts, not the whole layer.
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
mp <- sf::st_multipolygon(list(
  list(rbind(c(0, 0), c(1, 0), c(1, 1), c(0, 1), c(0, 0))),
  list(rbind(c(2, 2), c(3, 2), c(3, 3), c(2, 3), c(2, 2)))))
f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(
  id = 1L,
  geometry = sf::st_as_binary(sf::st_sfc(mp), hex = TRUE)
), f)

# One row per polygon, attributes copied, parts numbered.
tbl(f) |> spatial_explode(part = "part_id") |> collect_sf()
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_map]{spatial_map()}} for per-feature transforms, \code{\link[=spatial_dissolve]{spatial_dissolve()}} to
merge features the other way, \code{\link[=collect_sf]{collect_sf()}} to materialize as \code{sf}.
}
