% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{terrain}
\alias{terrain}
\title{Terrain derivatives from a streamed elevation raster}
\usage{
terrain(
  x,
  v = c("slope", "aspect", "hillshade", "TPI", "roughness", "TRI"),
  unit = c("degrees", "radians"),
  azimuth = 315,
  altitude = 45,
  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}
elevation raster.}

\item{v}{Derivatives to compute, any of \code{"slope"}, \code{"aspect"},
\code{"hillshade"}, \code{"TPI"} (topographic position index), \code{"roughness"},
\code{"TRI"} (terrain ruggedness index). The return follows the input: one
matrix for a single \code{v}, a named list for several.}

\item{unit}{Angular unit for \code{slope} and \code{aspect}: \code{"degrees"} (default) or
\code{"radians"}.}

\item{azimuth, altitude}{Sun position for \code{"hillshade"}, in degrees. Defaults
315 (NW) and 45.}

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

\item{path}{Optional output \code{.vec} path (one band per \code{v}, named after \code{v}).
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 in memory.}

\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 for a single \code{v}, or a named
list of matrices for several, each carrying \code{gt}, \code{extent}, and \code{crs}
attributes (row 1 northmost). When \code{path} is given, the written multi-band
\code{vectra_raster} handle (invisibly).
}
\description{
Computes DEM derivatives from a \code{.vec} elevation raster with Horn's 3x3
method, on the same haloed tile-row strip pass as \code{\link[=focal]{focal()}} -- the input is
read one strip at a time and, when \code{path} is given, the outputs are streamed
straight back to a multi-band \code{.vec}. Matches \pkg{terra}'s
\code{terrain()} / \code{shade()} conventions.
}
\details{
Slope and aspect use the Horn (1981) finite-difference gradient over
the 3x3 neighbourhood; \code{aspect} is degrees clockwise from north (flat cells
return 90). \code{hillshade} is the cosine of the incidence angle for the given
sun position, clamped at 0. \code{TPI} is the cell minus the mean of its eight
neighbours; \code{roughness} is the range over the 3x3; \code{TRI} is the mean
absolute difference to the eight neighbours. Cells whose 3x3 neighbourhood
touches a nodata value or the raster edge return \code{NA}.
}
\examples{
# A tilted surface so slope and aspect are well defined.
z <- outer(1:8, 1:8, function(r, c) 10 + 2 * c + r)
f <- tempfile(fileext = ".vec")
vec_write_raster(z, f, dtype = "f64", extent = c(0, 0, 8, 8))

slp <- terrain(f, v = "slope")
deriv <- terrain(f, v = c("slope", "aspect", "hillshade"))
names(deriv)
unlink(f)

}
\seealso{
\code{\link[=focal]{focal()}} for arbitrary moving windows.
}
