From a2bdf6bbda01c32666ff476c14124ffb6061db7f Mon Sep 17 00:00:00 2001
From: RFlx <temospena@gmail.com>
Date: Mon, 22 Jun 2026 12:29:50 +0100
Subject: [PATCH] fix colors in segments docs

---
 R/palette.R          | 51 ++++++++++++++++++++++++--------------------
 man/slope_breaks.Rd  | 22 +++++++++----------
 man/slope_colors.Rd  | 23 ++++++++++++++------
 vignettes/slopes.Rmd | 18 ++++++++++------
 4 files changed, 66 insertions(+), 48 deletions(-)

diff --git a/R/palette.R b/R/palette.R
index a22c26a..7285967 100644
--- a/R/palette.R
+++ b/R/palette.R
@@ -2,42 +2,47 @@
 
 #' Recommended slope colours (dark green to dark red)
 #'
-#' 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.
+#' A character vector of six hex colours ranging from dark green (flat, \eqn{\le}3\%)
+#' to dark red (steep, >20\%), representing increasing slope severity.
+#' Use directly with \code{\link{slope_breaks}} and \code{cut()} to colour
+#' segments by slope proportion (as returned by \code{\link{slope_xyz}}).
 #'
-#' @format A character vector of length 12.
-#' @seealso \code{\link{slope_breaks}}, \code{\link{slopes_palette}}
+#' @format A character vector of length 6.
+#' @seealso \code{\link{slope_breaks}}, \code{\link{plot_slope}}
 #' @examples
 #' slope_colors
 #' \donttest{
 #' route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon())
-#' plot_slope(route_xyz, pal = slope_colors, brks = slope_breaks)
+#'
+#' # 1. Colour segments by steepness (ignoring direction) using abs()
+#' segs <- route_to_segments(route_xyz)
+#' segs$slope <- slope_xyz(segs)
+#' col_idx <- cut(abs(segs$slope), breaks = slope_breaks,
+#'   labels = FALSE, include.lowest = TRUE)
+#' plot(sf::st_geometry(segs), col = slope_colors[col_idx], lwd = 3)
+#'
+#' # 2. Symmetric palette for plot_slope(): green = gentle, red = steep either way
+#' plot_slope(route_xyz, pal = c(rev(slope_colors), slope_colors))
 #' }
 #' @export
-slope_colors <- c(
-  "#730000", "#A80000", "#E60000", "#FFAA00", "#70A800", "#267300",  # downhill
-  "#267300", "#70A800", "#FFAA00", "#E60000", "#A80000", "#730000"   # uphill
-)
+slope_colors <- c("#267300", "#70A800", "#FFAA00", "#E60000", "#A80000", "#730000")
 
-#' Recommended slope break thresholds
+#' Recommended slope break thresholds (as proportions)
+#'
+#' A numeric vector of seven break points in **proportion units**
+#' (e.g. 0.05 = 5\%), including \code{0} and \code{Inf} as outer bounds.
+#' Defines six slope severity classes for use with \code{\link{slope_colors}}:
+#' 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}}.
+#' Use with \code{cut(slope_values, breaks = slope_breaks)} where slope values
+#' are proportions as returned by \code{\link{slope_xyz}}.
 #'
-#' @format A numeric vector of length 6.
-#' @seealso \code{\link{slope_colors}}, \code{\link{slopes_palette}}
+#' @format A numeric vector of length 7.
+#' @seealso \code{\link{slope_colors}}, \code{\link{plot_slope}}
 #' @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)
+slope_breaks <- c(0, 0.03, 0.05, 0.08, 0.10, 0.20, Inf)
 
 
 #' Get color palette for slopes visualization
diff --git a/man/slope_breaks.Rd b/man/slope_breaks.Rd
index 12d7ce0..0f40ff0 100644
--- a/man/slope_breaks.Rd
+++ b/man/slope_breaks.Rd
@@ -2,26 +2,26 @@
 % Please edit documentation in R/palette.R
 \name{slope_breaks}
 \alias{slope_breaks}
-\title{Recommended slope break thresholds}
+\title{Recommended slope break thresholds (as proportions)}
 \format{
-A numeric vector of length 6.
+A numeric vector of length 7.
 }
 \usage{
 slope_breaks
 }
 \description{
-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}}.
+A numeric vector of seven break points in \strong{proportion units}
+(e.g. 0.05 = 5\\%), including \code{0} and \code{Inf} as outer bounds.
+Defines six slope severity classes for use with \code{\link{slope_colors}}:
+0--3\\%, 3--5\\%, 5--8\\%, 8--10\\%, 10--20\\%, >20\\%.
+}
+\details{
+Use with \code{cut(slope_values, breaks = slope_breaks)} where slope values
+are proportions as returned by \code{\link{slope_xyz}}.
 }
 \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}}
+\code{\link{slope_colors}}, \code{\link{plot_slope}}
 }
diff --git a/man/slope_colors.Rd b/man/slope_colors.Rd
index 8fc5c7e..ce4530c 100644
--- a/man/slope_colors.Rd
+++ b/man/slope_colors.Rd
@@ -4,24 +4,33 @@
 \alias{slope_colors}
 \title{Recommended slope colours (dark green to dark red)}
 \format{
-A character vector of length 12.
+A character vector of length 6.
 }
 \usage{
 slope_colors
 }
 \description{
-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.
+A character vector of six hex colours ranging from dark green (flat, \eqn{\le}3\\%)
+to dark red (steep, >20\\%), representing increasing slope severity.
+Use directly with \code{\link{slope_breaks}} and \code{cut()} to colour
+segments by slope proportion (as returned by \code{\link{slope_xyz}}).
 }
 \examples{
 slope_colors
 \donttest{
 route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon())
-plot_slope(route_xyz, pal = slope_colors, brks = slope_breaks)
+
+# 1. Colour segments by steepness (ignoring direction) using abs()
+segs <- route_to_segments(route_xyz)
+segs$slope <- slope_xyz(segs)
+col_idx <- cut(abs(segs$slope), breaks = slope_breaks,
+  labels = FALSE, include.lowest = TRUE)
+plot(sf::st_geometry(segs), col = slope_colors[col_idx], lwd = 3)
+
+# 2. Symmetric palette for plot_slope(): green = gentle, red = steep either way
+plot_slope(route_xyz, pal = c(rev(slope_colors), slope_colors))
 }
 }
 \seealso{
-\code{\link{slope_breaks}}, \code{\link{slopes_palette}}
+\code{\link{slope_breaks}}, \code{\link{plot_slope}}
 }
diff --git a/vignettes/slopes.Rmd b/vignettes/slopes.Rmd
index ab112b7..d0dae5e 100644
--- a/vignettes/slopes.Rmd
+++ b/vignettes/slopes.Rmd
@@ -132,9 +132,9 @@ slope
 You can visualize the elevation profile of a 3D linestring using `plot_slope()`:
 
 ```{r}
-# Use the recommended green-to-red palette and matching break thresholds
-
-plot_slope(sf_linestring_xyz_local, pal = slope_colors, brks = slope_breaks)
+# For plot_slope() use a symmetric palette: steep slopes are red on both sides
+# (downhill and uphill), gentle slopes in the middle are green.
+plot_slope(sf_linestring_xyz_local, pal = c(rev(slope_colors), slope_colors))
 ```
 
 ## Working with segments
@@ -154,9 +154,12 @@ summary(lisbon_route_segments_xyz$slope)
 ```
 
 ```{r}
+# Segments are coloured by steepness (absolute slope), regardless of direction
+# (uphill or downhill). slope_breaks are in proportions, matching slope_xyz() output.
+col_idx <- cut(abs(lisbon_route_segments_xyz$slope),
+  breaks = slope_breaks, labels = FALSE, include.lowest = TRUE)
 plot(st_geometry(lisbon_route_segments_xyz),
-  col = slope_colors[7:12][cut(abs(lisbon_route_segments_xyz$slope) * 100,
-    breaks = slope_breaks, labels = FALSE, include.lowest = TRUE)],
+  col = slope_colors[col_idx],
   lwd = 3, main = "Slope by vertex segments"
 )
 ```
@@ -174,9 +177,10 @@ summary(lisbon_route_100m_xyz$slope)
 ```
 
 ```{r}
+col_idx <- cut(abs(lisbon_route_100m_xyz$slope),
+  breaks = slope_breaks, labels = FALSE, include.lowest = TRUE)
 plot(st_geometry(lisbon_route_100m_xyz),
-  col = slope_colors[7:12][cut(abs(lisbon_route_100m_xyz$slope) * 100,
-    breaks = slope_breaks, labels = FALSE, include.lowest = TRUE)],
+  col = slope_colors[col_idx],
   lwd = 3, main = "Slope by 100 m segments"
 )
 ```