\name{lines}

\docType{methods}

\alias{points}
\alias{lines}
\alias{polys}

\alias{lines,SpatVector-method}
\alias{lines,SpatRaster-method}
\alias{lines,SpatGraticule-method}
\alias{lines,SpatExtent-method}
\alias{lines,sf-method}

\alias{points,SpatVector-method}
\alias{points,SpatRaster-method}
\alias{points,SpatExtent-method}
\alias{points,sf-method}

\alias{polys,SpatVector-method}
\alias{polys,SpatRaster-method}
\alias{polys,SpatExtent-method}
\alias{polys,sf-method}


\title{Add points, lines, or polygons to a map}

\description{
Add a vector geometries to a plot (map) with \code{points}, \code{lines}, or \code{polys}. 

These are simpler alternatives for \code{\link[terra:plot]{plot(x, add=TRUE)}}

These methods also work for a small(!) SpatRaster. Only cells that are not NA in the first layer are used.
}

\usage{
\S4method{points}{SpatVector}(x, y=NULL, col, cex=0.7, pch=16, alpha=1, jitter=0, legend=FALSE, ...)

\S4method{lines}{SpatVector}(x, y=NULL, col, lwd=1, lty=1, arrows=FALSE, alpha=1, legend=FALSE, ...)

\S4method{polys}{SpatVector}(x, y=NULL, col, border="black", lwd=1, lty=1, alpha=1, legend=FALSE, ...)

\S4method{points}{SpatRaster}(x, ...)

\S4method{lines}{SpatRaster}(x, mx=10000, ...)

\S4method{polys}{SpatRaster}(x, mx=10000, dissolve=TRUE, ...)

\S4method{points}{SpatExtent}(x, col="black", alpha=1, ...)

\S4method{lines}{SpatExtent}(x, col="black", alpha=1, ...)

\S4method{polys}{SpatExtent}(x, col, alpha=1, ...)
}

\arguments{
  \item{x}{SpatVector or SpatExtent}
  \item{y}{missing, or a character (variable name) or positive integer (column number) to color the geometries by the values of that variable of \code{x}. With \code{lines}, \code{y} can also be a SpatVector; if both \code{x} and \code{y} have point geometry and the same number of rows, lines are drawn between pairs of points}
  \item{col}{character. Colors}
  \item{legend}{logical. If \code{TRUE} and \code{y} is a variable name/number, a legend is shown}
  \item{border}{character. color(s) of the polygon borders. Use \code{NULL} or \code{NA} to not draw a border}
  \item{cex}{numeric. point size magnifier. See \code{\link{par}}}
  \item{pch}{positive integer, point type. See \code{\link{points}}. On some (linux) devices, the default symbol "16" is a not a very smooth circle. You can use "20" instead (it takes a bit longer to draw) or "1" for an open circle}
  \item{alpha}{number between 0 and 1 to set transparency}
  \item{jitter}{numeric. The amount of random noise used to adjust label positions, possibly avoiding overlaps. See argument 'factor' in \code{\link{jitter}}}
  \item{lwd}{numeric, line-width. See \code{\link{par}}}
  \item{lty}{positive integer, line type. See \code{\link{par}}}
  \item{arrows}{logical. If \code{TRUE} and \code{y} is a SpatVector, arrows are drawn instead of lines. See \code{\link[graphics]{arrows}} for additional arguments}
  \item{mx}{positive number. If the number of cells of SpatRaster \code{x} is higher, the method will fail with an error message}
  \item{dissolve}{logical. Should boundaries between cells with the same value be removed?} 
  \item{...}{additional graphical arguments such as \code{lwd}, \code{cex} and \code{pch}}  
}


\examples{ 
f <- system.file("ex/lux.shp", package="terra")
v <- vect(f)

r <- rast(v)
values(r) <- 1:ncell(r)
plot(r)
lines(v)
points(v)

# color by the values of a variable
plot(v, col="light gray", border="white")
lines(v, "NAME_1", lwd=5)
points(centroids(v), "AREA", cex=2, legend="topright")
}

\keyword{methods}
\keyword{spatial}

