From 2bcdcf49dabc0eb7169344448d0679400a175fe3 Mon Sep 17 00:00:00 2001
From: rhijmans <r.hijmans@gmail.com>
Date: Fri, 17 May 2024 04:07:18 -0700
Subject: [PATCH] add_grid

---
 R/plot_legend.R | 29 +++++++++++++++++++++++++++++
 man/box.Rd      |  4 +++-
 man/grid.Rd     | 36 ++++++++++++++++++++++++++++++++++++
 man/legend.Rd   |  3 +++
 4 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 man/grid.Rd

diff --git a/R/plot_legend.R b/R/plot_legend.R
index 7f461ed3f..18a383fe2 100644
--- a/R/plot_legend.R
+++ b/R/plot_legend.R
@@ -506,4 +506,33 @@ add_box <- function(...) {
 }
 
 
+add_grid <- function(nx = NULL, ny = nx, col = "lightgray", lty = "dotted", lwd = par("lwd"), equilogs = TRUE) {
+
+
+	p <- terra:::get.clip()
+
+	## adapted from graphics::grid 
+	g.grid.at <- function (side, n, log, equilogs, axp, usr2) {
+		if (is.null(n)) {
+			stopifnot(is.numeric(ax <- axp), length(ax) == 3L)
+			if (log && equilogs && ax[3L] > 0) 
+				ax[3L] <- 1
+			axTicks(side, axp = ax, usr = usr2, log = log)
+		}
+		else if (!is.na(n) && (n <- as.integer(n)) >= 1L) {
+			at <- seq.int(usr2[1L], usr2[2L], length.out = n + 1L)
+			(if (log) 
+				10^at
+			else at)[-c(1L, n + 1L)]
+		}
+	}
+
+    atx <- if (is.null(nx) || (!is.na(nx) && nx >= 1)) 
+        g.grid.at(1L, nx, log = par("xlog"), equilogs, axp = par("xaxp"), usr2 = p[1:2])
+    aty <- if (is.null(ny) || (!is.na(ny) && ny >= 1)) 
+        g.grid.at(2L, ny, log = par("ylog"), equilogs, axp = par("yaxp"), usr2 = p[3:4])
+    abline(v = atx, h = aty, col = col, lty = lty, lwd = lwd)
+    invisible(list(atx = atx, aty = aty))
+}
+
 
diff --git a/man/box.Rd b/man/box.Rd
index e6ea01b03..add53ddba 100644
--- a/man/box.Rd
+++ b/man/box.Rd
@@ -5,7 +5,7 @@
 \title{draw a box}
 
 \description{ 
-Similar to \code{\link{box}} allowing adding a box around a map. This function will place the legend in the locations within the mapped area as delineated by the axes.
+Similar to \code{\link[graphics]{box}} allowing adding a box around a map. This function will place the legend in the locations within the mapped area as delineated by the axes.
 }
 
 \usage{
@@ -17,6 +17,8 @@ add_box(...)
 }
 
 
+\seealso{\code{\link{add_legend}}, \code{\link{add_grid}}}
+
 \examples{
 v <- vect(system.file("ex/lux.shp", package="terra"))
 plot(v)
diff --git a/man/grid.Rd b/man/grid.Rd
new file mode 100644
index 000000000..7a30b7601
--- /dev/null
+++ b/man/grid.Rd
@@ -0,0 +1,36 @@
+\name{add_grid}
+
+\alias{add_grid}
+
+\title{add a grid to an existing terra plot}
+
+\description{ 
+Wrapper around \code{\link[graphics]{grid}} that allows adding a grid to a map. This function will place the legend in the locations within the mapped area as delineated by the axes.
+
+Also see \code{\link{graticule}}
+}
+
+\usage{
+add_grid(nx = NULL, ny = nx, col = "lightgray", lty = "dotted",
+     lwd = par("lwd"), equilogs = TRUE)
+}
+
+\arguments{
+  \item{nx, ny}{number of cells of the grid in x and y direction. When NULL, as per default, the grid aligns with the tick marks on the corresponding default axis (i.e., tickmarks as computed by axTicks). When NA, no grid lines are drawn in the corresponding direction}
+  \item{col}{character or (integer) numeric; color of the grid lines}
+  \item{lty}{character or (integer) numeric; line type of the grid lines}
+  \item{lwd}{non-negative numeric giving line width of the grid lines}
+  \item{equilogs}{logical, only used when log coordinates and alignment with the axis tick marks are active. Setting equilogs = FALSE in that case gives non equidistant tick aligned grid lines}
+}
+
+\seealso{\code{\link{add_box}}, \code{\link{add_grid}}, \code{\link{graticule}}
+
+\examples{
+v <- vect(system.file("ex/lux.shp", package="terra"))
+plot(v)
+add_grid()
+}
+
+\keyword{methods}
+\keyword{spatial}
+
diff --git a/man/legend.Rd b/man/legend.Rd
index 0a6f217e6..d5091e408 100644
--- a/man/legend.Rd
+++ b/man/legend.Rd
@@ -12,6 +12,7 @@ Wrapper around \code{\link{legend}} that allows adding a custom legend to a map
 add_legend(x, y, ...)
 }
 
+
 \arguments{
   \item{x}{The keyword to be used to position the legend (or the x coordinate)}
   \item{y}{The y coordinate to be used to position the legend (is x is also a coordinate)}
@@ -19,6 +20,8 @@ add_legend(x, y, ...)
 }
 
 
+\seealso{\code{\link{add_box}}, \code{\link{add_grid}}}
+
 \examples{
 v <- vect(system.file("ex/lux.shp", package="terra"))
 plot(v)