% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/regions.R
\name{a5_polygon_to_cells}
\alias{a5_polygon_to_cells}
\title{Cells whose centres lie inside a polygon}
\usage{
a5_polygon_to_cells(x, resolution)
}
\arguments{
\item{x}{A polygon-like geometry. One of:
\itemize{
\item Any geometry handleable by \code{\link[wk:wk_handle]{wk::wk_handle()}} (e.g. \code{\link[wk:wkt]{wk::wkt()}},
\code{\link[wk:wkb]{wk::wkb()}}, \code{\link[wk:rct]{wk::rct()}}, \code{sf}, \code{sfc}) containing one or more
\code{POLYGON} / \code{MULTIPOLYGON} features.
\item A \code{SpatVector} of polygons (requires the \code{terra} package).
\item A two-column numeric matrix (\code{cbind(lon, lat)}) of vertices,
interpreted as a single outer ring.
\item A \code{data.frame} with columns \code{lon} and \code{lat}, interpreted as a
single outer ring.
}}

\item{resolution}{Integer scalar target resolution (0-30).}
}
\value{
An \link{a5_cell} vector at or coarser than \code{resolution}.
}
\description{
Returns A5 cells at \code{resolution} whose centres fall inside the polygon.
Multi-feature inputs (a \code{MULTIPOLYGON}, an \code{sfc} of multiple polygons,
or a \code{POLYGON} with holes) are handled natively: per polygon part, the
outer-ring cells are computed and any hole-ring cells are subtracted,
then the results are unioned across parts. The final cell set is
compacted; use \code{\link[=a5_uncompact]{a5_uncompact()}} to expand to a uniform-resolution grid.
}
\details{
Membership is determined by \strong{centre-point containment}: a cell is
included iff its centroid lies inside the polygon, with hole rings
properly subtracted. This is distinct from \code{\link[=a5_grid]{a5_grid()}}'s
boundary-intersection semantics; for the same polygon the two
functions can return slightly different cell sets near the boundary.

Coordinates must be WGS 84 longitude/latitude in degrees. Rings are
closed automatically; a trailing duplicate vertex is dropped if
present.

Where no A5 cell centroids at the specified \code{resolution} fall within
the geometry, an empty \code{a5_cell} vector is returned.

Matrix and \code{data.frame} inputs are treated as a single ring; for
multi-feature data or polygons with holes, pass an \code{sf}, \code{sfc}, wk,
or \code{SpatVector} geometry instead.
}
\examples{
poly <- wk::wkt(
  "POLYGON ((-3.3 55.9, -3.1 55.9, -3.1 56, -3.3 56, -3.3 55.9))"
)
cells <- a5_polygon_to_cells(poly, resolution = 8)
length(cells)
}
\seealso{
\code{\link[=a5_linestring_to_cells]{a5_linestring_to_cells()}}, \code{\link[=a5_uncompact]{a5_uncompact()}}.
}
