| Title: | Calculate Slopes of Roads, Rivers and Trajectories |
|---|---|
| Description: | Calculates the slope (longitudinal gradient or steepness) of linear geographic features such as roads (for more details, see Ariza-López et al. (2019) <doi:10.1038/s41597-019-0147-x>) and rivers (for more details, see Cohen et al. (2018) <doi:10.1016/j.jhydrol.2018.06.066>). It can use local Digital Elevation Model (DEM) data or download DEM data via the 'ceramic' package. The package also provides functions to add elevation data to linestrings and visualize elevation profiles. |
| Authors: | Robin Lovelace [aut, cre, cph] (ORCID: <https://orcid.org/0000-0001-5679-6536>), Rosa Félix [aut] (ORCID: <https://orcid.org/0000-0002-5642-6006>), Joey Talbot [aut] (ORCID: <https://orcid.org/0000-0002-6520-4560>), Gonçalo Matos [aut] (ORCID: <https://orcid.org/0009-0001-3489-1732>), Dan Olner [rev] (Dan reviewed the package for rOpenSci, see https://github.com/ropensci/software-review/issues/420#issuecomment-857662657), Andy Teucher [rev] (Andy reviewed the package for rOpenSci, see https://github.com/ropensci/software-review/issues/420#issuecomment-858231647) |
| Maintainer: | Robin Lovelace <[email protected]> |
| License: | GPL-3 |
| Version: | 2.0.0 |
| Built: | 2026-06-25 19:57:27 UTC |
| Source: | https://github.com/ropensci/slopes |
Cycle route data
cyclestreets_routecyclestreets_route
An sf object
Returns a SpatRaster (terra package) of the Digital Elevation Model
for central Lisbon, Portugal, bundled with the slopes package.
dem_lisbon()dem_lisbon()
A SpatRaster object with 133 rows, 200 columns, and 1 elevation layer.
dem_lisbon()dem_lisbon()
Extracts cumulative distance and elevation vectors from route XYZ coordinates.
distance_z(route_xyz, lonlat)distance_z(route_xyz, lonlat)
route_xyz |
An sf object with XYZ coordinates |
lonlat |
Logical, whether coordinates are longitude/latitude |
List with components d (distances) and z (elevations)
Adds elevation data to sf objects using a digital elevation model (DEM).
elevation_add( routes, dem = NULL, method = "bilinear", add_z = TRUE, add_column = FALSE, terra = NULL )elevation_add( routes, dem = NULL, method = "bilinear", add_z = TRUE, add_column = FALSE, terra = NULL )
routes |
An sf object containing linestring or point geometries. |
dem |
A SpatRaster object containing elevation data
(default: |
method |
Method for raster extraction (default: |
add_z |
For point geometries only: if |
add_column |
For point geometries only: if |
terra |
Deprecated. Ignored; terra is always used. |
For linestring geometries, the function attaches elevation as the Z coordinate of each vertex, returning an XYZ linestring sf object.
For point geometries, the function embeds the Z coordinate directly in
the geometry by default (returning POINT Z features), consistent with the
linestring behaviour. An elevation column can additionally be added by
setting add_column = TRUE.
An sf object. For linestrings: XYZ linestring geometries. For points:
POINT Z geometry (when add_z = TRUE) and/or an elevation column (when
add_column = TRUE).
library(sf) # Linestring usage: routes <- lisbon_road_network[204, ] dem <- dem_lisbon() (r3d <- elevation_add(routes, dem)) st_z_range(r3d) plot(st_coordinates(r3d)[, 3]) plot_slope(r3d) # Point usage — Z embedded in geometry by default: pts <- sf::st_cast(sf::st_geometry(lisbon_road_network[204, ]), "POINT") pts <- sf::st_sf(id = seq_along(pts), geometry = pts) (pts_z <- elevation_add(pts, dem)) sf::st_z_range(pts_z) # Also add an elevation column: (pts_z_col <- elevation_add(pts, dem, add_column = TRUE)) pts_z_col$elevation # Only an elevation column, keep XY geometry: (pts_col <- elevation_add(pts, dem, add_z = FALSE, add_column = TRUE)) ## Not run: # Get elevation data (requires internet connection, ceramic pkg, and API key): if (requireNamespace("ceramic", quietly = TRUE)) { r3d_get <- elevation_add(cyclestreets_route) plot_slope(r3d_get) } ## End(Not run)library(sf) # Linestring usage: routes <- lisbon_road_network[204, ] dem <- dem_lisbon() (r3d <- elevation_add(routes, dem)) st_z_range(r3d) plot(st_coordinates(r3d)[, 3]) plot_slope(r3d) # Point usage — Z embedded in geometry by default: pts <- sf::st_cast(sf::st_geometry(lisbon_road_network[204, ]), "POINT") pts <- sf::st_sf(id = seq_along(pts), geometry = pts) (pts_z <- elevation_add(pts, dem)) sf::st_z_range(pts_z) # Also add an elevation column: (pts_z_col <- elevation_add(pts, dem, add_column = TRUE)) pts_z_col$elevation # Only an elevation column, keep XY geometry: (pts_col <- elevation_add(pts, dem, add_z = FALSE, add_column = TRUE)) ## Not run: # Get elevation data (requires internet connection, ceramic pkg, and API key): if (requireNamespace("ceramic", quietly = TRUE)) { r3d_get <- elevation_add(cyclestreets_route) plot_slope(r3d_get) } ## End(Not run)
Extracts elevation values from a DEM raster at specified coordinate locations.
Accepts both SpatRaster (terra) and legacy Raster* (raster) objects;
legacy objects are automatically converted to SpatRaster.
elevation_extract(m, dem, method = "bilinear", terra = NULL)elevation_extract(m, dem, method = "bilinear", terra = NULL)
m |
Matrix or sf object with coordinates |
dem |
A SpatRaster (or legacy RasterLayer) containing elevation data |
method |
Method for raster extraction (default: "bilinear") |
terra |
Deprecated. Ignored; terra is always used. |
Numeric vector of elevation values
Downloads elevation data using the ceramic package for given routes.
Returns a SpatRaster object (terra package).
elevation_get(routes, ...)elevation_get(routes, ...)
routes |
An sf object containing linestring geometries |
... |
Additional arguments passed to ceramic::cc_elevation |
A SpatRaster covering the routes
Lisbon road network
lisbon_road_networklisbon_road_network
An sf object
Lisbon road segment
lisbon_road_segmentlisbon_road_segment
An sf object
Lisbon road segment 3D
lisbon_road_segment_3dlisbon_road_segment_3d
An sf object
Lisbon road segment XYZ
lisbon_road_segment_xyz_mapboxlisbon_road_segment_xyz_mapbox
An sf object
Lisbon route 3D
lisbon_route_3dlisbon_route_3d
An sf object
Lisbon route XYZ
lisbon_route_xyz_mapboxlisbon_route_xyz_mapbox
An sf object
Magnolia coordinates
magnolia_xymagnolia_xy
A data frame
Creates symmetric slope breaks around zero for color classification.
make_breaks(brks)make_breaks(brks)
brks |
Vector of positive slope break values (as percentages) |
Vector of slope breaks including negative values and zero
Maps slope gradient values to colors based on break points.
make_colz(g, b, pal)make_colz(g, b, pal)
g |
Vector of slope gradient values |
b |
Vector of break points |
pal |
Vector of colors corresponding to breaks |
Character vector of colors for each slope value
Creates or processes color palettes for slope gradient visualization.
make_pal(pal, b)make_pal(pal, b)
pal |
Color palette (function or character vector) |
b |
Vector of breaks for color mapping |
Character vector of colors
Creates a distance-elevation plot with segments colored by slope gradient.
plot_dz( d, z, fill = TRUE, horiz = FALSE, pal = NULL, ..., legend_position = "top", col = "black", cex = 0.9, bg = grDevices::rgb(1, 1, 1, 0.8), title = "Slope colors (percentage gradient)", brks = c(3, 6, 10, 20, 40, 100), seq_brks = NULL, ncol = 4 )plot_dz( d, z, fill = TRUE, horiz = FALSE, pal = NULL, ..., legend_position = "top", col = "black", cex = 0.9, bg = grDevices::rgb(1, 1, 1, 0.8), title = "Slope colors (percentage gradient)", brks = c(3, 6, 10, 20, 40, 100), seq_brks = NULL, ncol = 4 )
d |
Vector of cumulative distances |
z |
Vector of elevation values |
fill |
Logical, whether to fill segments with slope colors (default: TRUE) |
horiz |
Logical, whether legend should be horizontal (default: FALSE) |
pal |
Color palette for slope visualization (default: NULL, uses slopes_palette) |
... |
Additional arguments passed to graphics functions |
legend_position |
Position of legend (default: "top") |
col |
Color of the elevation profile line (default: "black") |
cex |
Character expansion factor for legend text (default: 0.9) |
bg |
Background color for legend (default: semi-transparent white) |
title |
Title for the legend (default: "Slope colors (percentage gradient)") |
brks |
Vector of slope break points for coloring (default: c(3, 6, 10, 20, 40, 100)) |
seq_brks |
Sequence of breaks to show in legend (default: NULL, auto-generated) |
ncol |
Number of columns in legend (default: 4) |
NULL (creates plot as side effect)
Creates an elevation profile plot from route geometries with XYZ coordinates, with segments colored according to slope gradient.
plot_slope( route_xyz, lonlat = sf::st_is_longlat(route_xyz), fill = TRUE, horiz = FALSE, pal = NULL, legend_position = "top", col = "black", cex = 0.9, bg = grDevices::rgb(1, 1, 1, 0.8), title = "Slope colors (percentage gradient)", brks = c(3, 6, 10, 20, 40, 100), seq_brks = seq(from = 3, to = length(brks) * 2 - 2), ncol = 4, ... )plot_slope( route_xyz, lonlat = sf::st_is_longlat(route_xyz), fill = TRUE, horiz = FALSE, pal = NULL, legend_position = "top", col = "black", cex = 0.9, bg = grDevices::rgb(1, 1, 1, 0.8), title = "Slope colors (percentage gradient)", brks = c(3, 6, 10, 20, 40, 100), seq_brks = seq(from = 3, to = length(brks) * 2 - 2), ncol = 4, ... )
route_xyz |
An sf object containing linestring geometries with XYZ coordinates |
lonlat |
Logical, whether coordinates are longitude/latitude (default: auto-detected) |
fill |
Logical, whether to fill segments with slope colors (default: TRUE) |
horiz |
Logical, whether legend should be horizontal (default: FALSE) |
pal |
Color palette for slope visualization (default: NULL, uses slopes_palette) |
legend_position |
Position of legend (default: "top") |
col |
Color of the elevation profile line (default: "black") |
cex |
Character expansion factor for legend text (default: 0.9) |
bg |
Background color for legend (default: semi-transparent white) |
title |
Title for the legend (default: "Slope colors (percentage gradient)") |
brks |
Vector of slope break points for coloring (default: c(3, 6, 10, 20, 40, 100)) |
seq_brks |
Sequence of breaks to show in legend (default: auto-generated) |
ncol |
Number of columns in legend (default: 4) |
... |
Additional arguments passed to plot_dz |
NULL (creates plot as side effect)
Splits a linestring with XYZ coordinates into individual 2-point segments,
one per consecutive vertex pair. Useful for computing per-segment slopes
with slope_xyz().
route_to_segments(route_xyz)route_to_segments(route_xyz)
route_xyz |
An sf object with a single LINESTRING geometry with Z coordinates,
as returned by |
An sf object with one LINESTRING feature per vertex-to-vertex segment.
route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon()) segs <- route_to_segments(route_xyz) segs$slope <- slope_xyz(segs) summary(segs$slope)route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon()) segs <- route_to_segments(route_xyz) segs$slope <- slope_xyz(segs) summary(segs$slope)
Calculates distances between consecutive points in a coordinate matrix.
sequential_dist(m, lonlat = TRUE)sequential_dist(m, lonlat = TRUE)
m |
Matrix of coordinates (x, y) |
lonlat |
Logical, whether coordinates are longitude/latitude (default: TRUE) |
Numeric vector of distances between consecutive points
Internal helper function to get midpoint and extent of routes in lon/lat coordinates.
sf_mid_ext_lonlat(routes)sf_mid_ext_lonlat(routes)
routes |
An sf object containing linestring geometries |
A list with midpoint coordinates and width/height dimensions
A numeric vector of seven break points in proportion units
(e.g. 0.05 = 5\
Defines six slope severity classes for use with slope_colors:
0–3\
slope_breaksslope_breaks
A numeric vector of length 7.
Use with cut(slope_values, breaks = slope_breaks) where slope values
are proportions as returned by slope_xyz.
slope_breaksslope_breaks
A character vector of six hex colours ranging from dark green (flat, 3\
to dark red (steep, >20\
Use directly with slope_breaks and cut() to colour
segments by slope proportion (as returned by slope_xyz).
slope_colorsslope_colors
A character vector of length 6.
slope_colors route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon()) # 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))slope_colors route_xyz <- elevation_add(lisbon_route, dem = dem_lisbon()) # 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))
Calculates slope gradients from distance and elevation vectors.
slope_distance(d, elevations)slope_distance(d, elevations)
d |
Vector of distance values between points |
elevations |
Vector of elevation values |
Numeric vector of slope values
Computes the mean slope across segments using distance-weighted averaging.
slope_distance_mean(d, elevations, directed = FALSE)slope_distance_mean(d, elevations, directed = FALSE)
d |
Vector of distance values between points |
elevations |
Vector of elevation values |
directed |
Logical, whether to calculate directed slopes (default: FALSE) |
Numeric value representing the mean slope
Applies distance-based weighting to slope calculations for more accurate results.
slope_distance_weighted(d, elevations, directed = FALSE)slope_distance_weighted(d, elevations, directed = FALSE)
d |
Vector of distance values between points |
elevations |
Vector of elevation values |
directed |
Logical, whether to calculate directed slopes (default: FALSE) |
Numeric value representing the weighted slope
Applies slope calculation function to a list of coordinate matrices.
slope_matrices(m_xyz_split, fun = slope_matrix_weighted, ...)slope_matrices(m_xyz_split, fun = slope_matrix_weighted, ...)
m_xyz_split |
List of coordinate matrices with elevation data |
fun |
Function to apply for slope calculation (default: slope_matrix_weighted) |
... |
Additional arguments passed to the slope function |
Numeric vector of slope values for all matrices
Calculates slope gradients from a matrix of coordinates and elevation data.
slope_matrix(m, elevations = m[, 3], lonlat = TRUE)slope_matrix(m, elevations = m[, 3], lonlat = TRUE)
m |
Matrix of coordinates (x, y, z) |
elevations |
Vector of elevation values (default: third column of m) |
lonlat |
Logical, whether coordinates are longitude/latitude (default: TRUE) |
Numeric vector of slope values
Computes the mean slope from a matrix of coordinates with elevation data.
slope_matrix_mean(m, elevations = m[, 3], lonlat = TRUE, directed = FALSE)slope_matrix_mean(m, elevations = m[, 3], lonlat = TRUE, directed = FALSE)
m |
Matrix of coordinates (x, y, z) |
elevations |
Vector of elevation values (default: third column of m) |
lonlat |
Logical, whether coordinates are longitude/latitude (default: TRUE) |
directed |
Logical, whether to calculate directed slopes (default: FALSE) |
Numeric value representing the mean slope
Converts a slope matrix or a legacy RasterLayer to a SpatRaster (terra).
Accepts SpatRaster, legacy Raster*, or a plain matrix.
slope_matrix_to_raster(x)slope_matrix_to_raster(x)
x |
A matrix, SpatRaster, or legacy RasterLayer object |
A SpatRaster object
Applies distance-based weighting to slope calculations from coordinate matrix.
slope_matrix_weighted(m, elevations = m[, 3], lonlat = TRUE, directed = FALSE)slope_matrix_weighted(m, elevations = m[, 3], lonlat = TRUE, directed = FALSE)
m |
Matrix of coordinates (x, y, z) |
elevations |
Vector of elevation values (default: third column of m) |
lonlat |
Logical, whether coordinates are longitude/latitude (default: TRUE) |
directed |
Logical, whether to calculate directed slopes (default: FALSE) |
Numeric value representing the weighted slope
Calculates slope gradients for routes using digital elevation model (DEM) raster data.
slope_raster( routes, dem, lonlat = sf::st_is_longlat(routes), method = "bilinear", fun = slope_matrix_weighted, terra = NULL, directed = FALSE )slope_raster( routes, dem, lonlat = sf::st_is_longlat(routes), method = "bilinear", fun = slope_matrix_weighted, terra = NULL, directed = FALSE )
routes |
An sf object containing linestring geometries |
dem |
A SpatRaster object (terra package) containing elevation data |
lonlat |
Logical, whether coordinates are longitude/latitude (default: auto-detected) |
method |
Method for raster extraction (default: "bilinear") |
fun |
Function for slope calculation (default: slope_matrix_weighted) |
terra |
Deprecated. Ignored; terra is always used. |
directed |
Logical, whether to calculate directed slopes (default: FALSE) |
Numeric vector of slope values
Calculates slope gradients using vector distance and elevation data.
slope_vector(x, elevations)slope_vector(x, elevations)
x |
Vector of distance values |
elevations |
Vector of elevation values |
Numeric vector of slope values
Calculates slope gradients from linestring geometries with XYZ coordinates.
slope_xyz( route_xyz, fun = slope_matrix_weighted, lonlat = TRUE, directed = FALSE )slope_xyz( route_xyz, fun = slope_matrix_weighted, lonlat = TRUE, directed = FALSE )
route_xyz |
An sf object or data frame with XYZ coordinates |
fun |
Function for slope calculation (default: slope_matrix_weighted) |
lonlat |
Logical, whether coordinates are longitude/latitude (default: TRUE) |
directed |
Logical, whether to calculate directed slopes (default: FALSE) |
Numeric vector of slope values
Simplifies raster or matrix data to XYZ coordinate format.
Accepts SpatRaster (terra), legacy Raster* objects, or a plain matrix.
slope_xyz_simple(x)slope_xyz_simple(x)
x |
A SpatRaster, legacy RasterLayer, or matrix object |
A data frame with x, y, z coordinates
Returns a color palette suitable for visualizing slope data, with options for different color schemes.
slopes_palette(n = 6, palette = "Green-Brown")slopes_palette(n = 6, palette = "Green-Brown")
n |
Number of colors to return (default: 6) |
palette |
Name of the color palette to use (default: "Green-Brown") |
A character vector of color codes
# Get default Green-Brown palette with 6 colors slopes_palette() # Get 4 colors from Green-Brown palette slopes_palette(n = 4) # Use a different palette slopes_palette(n = 5, palette = "Blue-Red")# Get default Green-Brown palette with 6 colors slopes_palette() # Get 4 colors from Green-Brown palette slopes_palette(n = 4) # Use a different palette slopes_palette(n = 5, palette = "Blue-Red")