% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial_more.R
\name{proximity}
\alias{proximity}
\title{Euclidean distance to the nearest feature (proximity)}
\usage{
proximity(
  x,
  target = NULL,
  band = 1L,
  path = NULL,
  dtype = "f32",
  compression = c("fast", "balanced", "max")
)
}
\arguments{
\item{x}{A \code{vectra_raster} (from \code{\link[=vec_open_raster]{vec_open_raster()}}) or a path to a \code{.vec}
raster.}

\item{target}{Optional numeric vector of feature values. When \code{NULL}
(default) every non-NA cell is a feature; otherwise a cell is a feature
when its value is in \code{target}.}

\item{band}{Band to read (1-based). Default 1.}

\item{path}{Optional output \code{.vec} path. When given the result is streamed to
disk and the opened \code{\link[=vec_open_raster]{vec_open_raster()}} handle is returned invisibly; when
\code{NULL} the result is returned as an in-memory matrix.}

\item{dtype}{Storage dtype for \code{.vec} output (see \code{\link[=vec_write_raster]{vec_write_raster()}}).
Default \code{"f32"}.}

\item{compression}{Compression effort for \code{.vec} output. Default \code{"fast"}.}
}
\value{
When \code{path} is \code{NULL}, a numeric matrix (row 1 northmost) carrying
\code{gt}, \code{extent}, and \code{crs} attributes, with distance in CRS units and \code{NA}
where the raster holds no feature anywhere. When \code{path} is given, the
written \code{vectra_raster} handle (invisibly).
}
\description{
Computes, for every cell of a \code{.vec} raster, the straight-line Euclidean
distance to the nearest feature cell, in CRS units. Feature cells are the
non-NA cells by default, or the cells whose value is in \code{target}. This is the
raster proximity / Euclidean-distance staple, the distance companion to
\code{\link[=rasterize]{rasterize()}}.
}
\details{
The exact Euclidean distance transform is separable (Felzenszwalb and
Huttenlocher 2012): a one-dimensional lower-envelope-of-parabolas transform
along the rows, then the same transform along the columns, each linear in the
line length and each line independent. vectra runs it as four streamed passes
over tile-row strips, with an out-of-core transpose between the row pass and
the column pass, so the whole grid is never resident. The row pass scales
squared distances by the x resolution and the column pass by the y
resolution, so the result is exact on anisotropic (non-square) cells. This
places proximity on the sort / partition tier of the spatial toolbox.

Distances are straight-line Euclidean in the raster CRS units. Cost-distance,
which accumulates a per-cell friction along the path, is a global
shortest-path problem and stays resident: \code{\link[=collect]{collect()}} the raster and run a
resident solver for that.
}
\examples{
m <- matrix(NA_real_, 12, 12)
m[3, 4] <- 1; m[9, 10] <- 1
f <- tempfile(fileext = ".vec")
vec_write_raster(m, f, dtype = "f64", extent = c(0, 0, 12, 12))

d <- proximity(f)
round(d[1:3, 1:3], 2)
unlink(f)

}
\seealso{
\code{\link[=rasterize]{rasterize()}} to build a raster from streamed points, \code{\link[=mask]{mask()}} to
clip a raster to a polygon layer.
}
