From e83d32ffdf4d3b8d71d7b18d2d137f1b4ccfab5e Mon Sep 17 00:00:00 2001
From: RFlx <temospena@gmail.com>
Date: Wed, 17 Jun 2026 15:26:58 +0100
Subject: [PATCH 1/3] export recommended slope color palette and break
 thresholds and update vignettes #34

---
 NAMESPACE            |  2 ++
 R/palette.R          | 28 ++++++++++++++++++++++++++++
 man/slope_breaks.Rd  | 22 ++++++++++++++++++++++
 man/slope_colors.Rd  | 23 +++++++++++++++++++++++
 vignettes/slopes.Rmd | 12 ++++++------
 5 files changed, 81 insertions(+), 6 deletions(-)
 create mode 100644 man/slope_breaks.Rd
 create mode 100644 man/slope_colors.Rd

diff --git a/NAMESPACE b/NAMESPACE
index ca51d28..8337291 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -8,6 +8,8 @@ export(plot_dz)
 export(plot_slope)
 export(route_to_segments)
 export(sequential_dist)
+export(slope_breaks)
+export(slope_colors)
 export(slope_distance)
 export(slope_distance_mean)
 export(slope_distance_weighted)
diff --git a/R/palette.R b/R/palette.R
index bb377e1..2da1e9e 100644
--- a/R/palette.R
+++ b/R/palette.R
@@ -1,5 +1,33 @@
 # R/palette.R
 
+#' Recommended slope colours (dark green to dark red)
+#'
+#' A character vector of six hex colours ranging from dark green (flat terrain)
+#' to dark red (steep terrain), representing increasing slope severity.
+#' Designed to be used together with \code{\link{slope_breaks}}.
+#'
+#' @format A character vector of length 6.
+#' @seealso \code{\link{slope_breaks}}, \code{\link{slopes_palette}}
+#' @examples
+#' slope_colors
+#' plot_slope(lisbon_route_xyz, pal = slope_colors, brks = slope_breaks)
+#' @export
+slope_colors <- c("#267300", "#70A800", "#FFAA00", "#E60000", "#A80000", "#730000")
+
+#' Recommended slope break thresholds
+#'
+#' A numeric vector of seven break points (as proportions, e.g. 0.05 = 5 \%)
+#' that define the slope severity classes used with \code{\link{slope_colors}}.
+#' Classes are: 0--3\%, 3--5\%, 5--8\%, 8--10\%, 10--20\%, >20\%.
+#'
+#' @format A numeric vector of length 7.
+#' @seealso \code{\link{slope_colors}}, \code{\link{slopes_palette}}
+#' @examples
+#' slope_breaks
+#' @export
+slope_breaks <- c(0, 0.03, 0.05, 0.08, 0.10, 0.20, Inf)
+
+
 #' Get color palette for slopes visualization
 #'
 #' Returns a color palette suitable for visualizing slope data, with options
diff --git a/man/slope_breaks.Rd b/man/slope_breaks.Rd
new file mode 100644
index 0000000..f9c6528
--- /dev/null
+++ b/man/slope_breaks.Rd
@@ -0,0 +1,22 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/palette.R
+\name{slope_breaks}
+\alias{slope_breaks}
+\title{Recommended slope break thresholds}
+\format{
+A numeric vector of length 7.
+}
+\usage{
+slope_breaks
+}
+\description{
+A numeric vector of seven break points (as proportions, e.g. 0.05 = 5 \\%)
+that define the slope severity classes used with \code{\link{slope_colors}}.
+Classes are: 0--3\\%, 3--5\\%, 5--8\\%, 8--10\\%, 10--20\\%, >20\\%.
+}
+\examples{
+slope_breaks
+}
+\seealso{
+\code{\link{slope_colors}}, \code{\link{slopes_palette}}
+}
diff --git a/man/slope_colors.Rd b/man/slope_colors.Rd
new file mode 100644
index 0000000..6abc366
--- /dev/null
+++ b/man/slope_colors.Rd
@@ -0,0 +1,23 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/palette.R
+\name{slope_colors}
+\alias{slope_colors}
+\title{Recommended slope colours (dark green to dark red)}
+\format{
+A character vector of length 6.
+}
+\usage{
+slope_colors
+}
+\description{
+A character vector of six hex colours ranging from dark green (flat terrain)
+to dark red (steep terrain), representing increasing slope severity.
+Designed to be used together with \code{\link{slope_breaks}}.
+}
+\examples{
+slope_colors
+plot_slope(lisbon_route_xyz, pal = slope_colors, brks = slope_breaks)
+}
+\seealso{
+\code{\link{slope_breaks}}, \code{\link{slopes_palette}}
+}
diff --git a/vignettes/slopes.Rmd b/vignettes/slopes.Rmd
index ec506f5..95eb5ba 100644
--- a/vignettes/slopes.Rmd
+++ b/vignettes/slopes.Rmd
@@ -132,11 +132,9 @@ slope
 You can visualize the elevation profile of a 3D linestring using `plot_slope()`:
 
 ```{r}
-# ensure a palette and breaks exist
-brks <- c(3, 6, 10, 20, 40, 100)
-pal <- slopes_palette(length(brks) - 1)
+# Use the recommended green-to-red palette and matching break thresholds
 
-plot_slope(sf_linestring_xyz_local, pal = pal, brks = brks)
+plot_slope(sf_linestring_xyz_local, pal = slope_colors, brks = slope_breaks)
 ```
 
 ## Working with segments
@@ -157,7 +155,8 @@ summary(lisbon_route_segments_xyz$slope)
 
 ```{r}
 plot(st_geometry(lisbon_route_segments_xyz),
-  col = heat.colors(length(lisbon_route_segments_xyz$slope))[rank(lisbon_route_segments_xyz$slope)],
+  col = slope_colors[cut(lisbon_route_segments_xyz$slope, breaks = slope_breaks,
+    labels = FALSE, include.lowest = TRUE)],
   lwd = 3, main = "Slope by vertex segments"
 )
 ```
@@ -176,7 +175,8 @@ summary(lisbon_route_100m_xyz$slope)
 
 ```{r}
 plot(st_geometry(lisbon_route_100m_xyz),
-  col = heat.colors(length(lisbon_route_100m_xyz$slope))[rank(lisbon_route_100m_xyz$slope)],
+  col = slope_colors[cut(lisbon_route_100m_xyz$slope, breaks = slope_breaks,
+    labels = FALSE, include.lowest = TRUE)],
   lwd = 3, main = "Slope by 100 m segments"
 )
 ```

From a6777aa77fe411c3df06e629ed5d5be7a0a657a2 Mon Sep 17 00:00:00 2001
From: RFlx <temospena@gmail.com>
Date: Wed, 17 Jun 2026 15:58:08 +0100
Subject: [PATCH 2/3] fix duplicate zero in negative pallete color #34

---
 R/palette.R          | 25 +++++++++++++++----------
 man/slope_breaks.Rd  |  9 +++++----
 man/slope_colors.Rd  |  9 +++++----
 vignettes/slopes.Rmd |  8 ++++----
 4 files changed, 29 insertions(+), 22 deletions(-)

diff --git a/R/palette.R b/R/palette.R
index 2da1e9e..7d91431 100644
--- a/R/palette.R
+++ b/R/palette.R
@@ -2,30 +2,35 @@
 
 #' Recommended slope colours (dark green to dark red)
 #'
-#' A character vector of six hex colours ranging from dark green (flat terrain)
-#' to dark red (steep terrain), representing increasing slope severity.
-#' Designed to be used together with \code{\link{slope_breaks}}.
+#' A character vector of twelve hex colours for use with \code{\link{slope_breaks}}
+#' and \code{\link{plot_slope}}. Colours run from dark green (flat) through amber
+#' to dark red (steep), covering both downhill (negative) and uphill (positive)
+#' slope directions — six colours per direction.
 #'
-#' @format A character vector of length 6.
+#' @format A character vector of length 12.
 #' @seealso \code{\link{slope_breaks}}, \code{\link{slopes_palette}}
 #' @examples
 #' slope_colors
 #' plot_slope(lisbon_route_xyz, pal = slope_colors, brks = slope_breaks)
 #' @export
-slope_colors <- c("#267300", "#70A800", "#FFAA00", "#E60000", "#A80000", "#730000")
+slope_colors <- c(
+  "#730000", "#A80000", "#E60000", "#FFAA00", "#70A800", "#267300",  # downhill
+  "#267300", "#70A800", "#FFAA00", "#E60000", "#A80000", "#730000"   # uphill
+)
 
 #' Recommended slope break thresholds
 #'
-#' A numeric vector of seven break points (as proportions, e.g. 0.05 = 5 \%)
-#' that define the slope severity classes used with \code{\link{slope_colors}}.
-#' Classes are: 0--3\%, 3--5\%, 5--8\%, 8--10\%, 10--20\%, >20\%.
+#' A numeric vector of six positive break points in **percentage units**
+#' (e.g. 5 = 5\%), without \code{0} or \code{Inf}.
+#' \code{\link{plot_slope}} uses these to build a symmetric set of 12 intervals
+#' (downhill and uphill), matched to the 12 colours in \code{\link{slope_colors}}.
 #'
-#' @format A numeric vector of length 7.
+#' @format A numeric vector of length 6.
 #' @seealso \code{\link{slope_colors}}, \code{\link{slopes_palette}}
 #' @examples
 #' slope_breaks
 #' @export
-slope_breaks <- c(0, 0.03, 0.05, 0.08, 0.10, 0.20, Inf)
+slope_breaks <- c(3, 5, 8, 10, 20, 100)
 
 
 #' Get color palette for slopes visualization
diff --git a/man/slope_breaks.Rd b/man/slope_breaks.Rd
index f9c6528..bd98169 100644
--- a/man/slope_breaks.Rd
+++ b/man/slope_breaks.Rd
@@ -4,15 +4,16 @@
 \alias{slope_breaks}
 \title{Recommended slope break thresholds}
 \format{
-A numeric vector of length 7.
+A numeric vector of length 6.
 }
 \usage{
 slope_breaks
 }
 \description{
-A numeric vector of seven break points (as proportions, e.g. 0.05 = 5 \\%)
-that define the slope severity classes used with \code{\link{slope_colors}}.
-Classes are: 0--3\\%, 3--5\\%, 5--8\\%, 8--10\\%, 10--20\\%, >20\\%.
+A numeric vector of six positive break points in \strong{percentage units}
+(e.g. 5 = 5\\%), without \code{0} or \code{Inf}.
+\code{\link{plot_slope}} uses these to build a symmetric set of 12 intervals
+(downhill and uphill), matched to the 12 colours in \code{\link{slope_colors}}.
 }
 \examples{
 slope_breaks
diff --git a/man/slope_colors.Rd b/man/slope_colors.Rd
index 6abc366..e08dda9 100644
--- a/man/slope_colors.Rd
+++ b/man/slope_colors.Rd
@@ -4,15 +4,16 @@
 \alias{slope_colors}
 \title{Recommended slope colours (dark green to dark red)}
 \format{
-A character vector of length 6.
+A character vector of length 12.
 }
 \usage{
 slope_colors
 }
 \description{
-A character vector of six hex colours ranging from dark green (flat terrain)
-to dark red (steep terrain), representing increasing slope severity.
-Designed to be used together with \code{\link{slope_breaks}}.
+A character vector of twelve hex colours for use with \code{\link{slope_breaks}}
+and \code{\link{plot_slope}}. Colours run from dark green (flat) through amber
+to dark red (steep), covering both downhill (negative) and uphill (positive)
+slope directions — six colours per direction.
 }
 \examples{
 slope_colors
diff --git a/vignettes/slopes.Rmd b/vignettes/slopes.Rmd
index 95eb5ba..ab112b7 100644
--- a/vignettes/slopes.Rmd
+++ b/vignettes/slopes.Rmd
@@ -155,8 +155,8 @@ summary(lisbon_route_segments_xyz$slope)
 
 ```{r}
 plot(st_geometry(lisbon_route_segments_xyz),
-  col = slope_colors[cut(lisbon_route_segments_xyz$slope, breaks = slope_breaks,
-    labels = FALSE, include.lowest = TRUE)],
+  col = slope_colors[7:12][cut(abs(lisbon_route_segments_xyz$slope) * 100,
+    breaks = slope_breaks, labels = FALSE, include.lowest = TRUE)],
   lwd = 3, main = "Slope by vertex segments"
 )
 ```
@@ -175,8 +175,8 @@ summary(lisbon_route_100m_xyz$slope)
 
 ```{r}
 plot(st_geometry(lisbon_route_100m_xyz),
-  col = slope_colors[cut(lisbon_route_100m_xyz$slope, breaks = slope_breaks,
-    labels = FALSE, include.lowest = TRUE)],
+  col = slope_colors[7:12][cut(abs(lisbon_route_100m_xyz$slope) * 100,
+    breaks = slope_breaks, labels = FALSE, include.lowest = TRUE)],
   lwd = 3, main = "Slope by 100 m segments"
 )
 ```

From 59f5a28a5d865ad4939f5785f5d27b7cbd9798d8 Mon Sep 17 00:00:00 2001
From: RFlx <temospena@gmail.com>
Date: Wed, 17 Jun 2026 18:27:17 +0100
Subject: [PATCH 3/3] wrap palette and breaks example plots in donttest blocks
 to fix documentation checks #34

---
 R/palette.R         | 9 ++++++++-
 man/slope_breaks.Rd | 4 ++++
 man/slope_colors.Rd | 5 ++++-
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/R/palette.R b/R/palette.R
index 7d91431..a22c26a 100644
--- a/R/palette.R
+++ b/R/palette.R
@@ -11,7 +11,10 @@
 #' @seealso \code{\link{slope_breaks}}, \code{\link{slopes_palette}}
 #' @examples
 #' slope_colors
-#' plot_slope(lisbon_route_xyz, pal = slope_colors, brks = slope_breaks)
+#' \donttest{
+#' route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon())
+#' plot_slope(route_xyz, pal = slope_colors, brks = slope_breaks)
+#' }
 #' @export
 slope_colors <- c(
   "#730000", "#A80000", "#E60000", "#FFAA00", "#70A800", "#267300",  # downhill
@@ -29,6 +32,10 @@ slope_colors <- c(
 #' @seealso \code{\link{slope_colors}}, \code{\link{slopes_palette}}
 #' @examples
 #' slope_breaks
+#' \donttest{
+#' route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon())
+#' plot_slope(route_xyz, pal = slope_colors, brks = slope_breaks)
+#' }
 #' @export
 slope_breaks <- c(3, 5, 8, 10, 20, 100)
 
diff --git a/man/slope_breaks.Rd b/man/slope_breaks.Rd
index bd98169..12d7ce0 100644
--- a/man/slope_breaks.Rd
+++ b/man/slope_breaks.Rd
@@ -17,6 +17,10 @@ A numeric vector of six positive break points in \strong{percentage units}
 }
 \examples{
 slope_breaks
+\donttest{
+route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon())
+plot_slope(route_xyz, pal = slope_colors, brks = slope_breaks)
+}
 }
 \seealso{
 \code{\link{slope_colors}}, \code{\link{slopes_palette}}
diff --git a/man/slope_colors.Rd b/man/slope_colors.Rd
index e08dda9..8fc5c7e 100644
--- a/man/slope_colors.Rd
+++ b/man/slope_colors.Rd
@@ -17,7 +17,10 @@ slope directions — six colours per direction.
 }
 \examples{
 slope_colors
-plot_slope(lisbon_route_xyz, pal = slope_colors, brks = slope_breaks)
+\donttest{
+route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon())
+plot_slope(route_xyz, pal = slope_colors, brks = slope_breaks)
+}
 }
 \seealso{
 \code{\link{slope_breaks}}, \code{\link{slopes_palette}}