| 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: | 1.0.1.9000 |
| Built: | 2025-09-29 12:45:57 UTC |
| Source: | https://github.com/ropensci/slopes |
Cycle route data
cyclestreets_routecyclestreets_route
An sf object
Lisbon elevation raster
dem_lisbon_rasterdem_lisbon_raster
A raster object
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 (Z) coordinates to linestring geometries using DEM data.
elevation_add( routes, dem = NULL, method = "bilinear", terra = has_terra() && methods::is(dem, "SpatRaster") )elevation_add( routes, dem = NULL, method = "bilinear", terra = has_terra() && methods::is(dem, "SpatRaster") )
routes |
An sf object containing linestring geometries |
dem |
A raster object containing elevation data (default: NULL for automatic download) |
method |
Method for raster extraction (default: "bilinear") |
terra |
Logical, whether to use terra package (default: auto-detected) |
An sf object with XYZ linestring geometries
Extracts elevation values from a DEM raster at specified coordinate locations.
elevation_extract( m, dem, method = "bilinear", terra = has_terra() && methods::is(dem, "SpatRaster") )elevation_extract( m, dem, method = "bilinear", terra = has_terra() && methods::is(dem, "SpatRaster") )
m |
Matrix or sf object with coordinates |
dem |
A raster object containing elevation data |
method |
Method for raster extraction (default: "bilinear") |
terra |
Logical, whether to use terra package (default: auto-detected) |
Numeric vector of elevation values
Downloads elevation data using the ceramic package for given routes.
elevation_get(routes, ..., output_format = "raster")elevation_get(routes, ..., output_format = "raster")
routes |
An sf object containing linestring geometries |
... |
Additional arguments passed to ceramic::cc_elevation |
output_format |
Character string specifying output format ("raster" or "terra") |
Elevation raster data 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)
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
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 checks if input is already a raster.
slope_matrix_to_raster(x)slope_matrix_to_raster(x)
x |
A matrix or RasterLayer object |
A RasterLayer 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 = has_terra() && methods::is(dem, "SpatRaster"), directed = FALSE )slope_raster( routes, dem, lonlat = sf::st_is_longlat(routes), method = "bilinear", fun = slope_matrix_weighted, terra = has_terra() && methods::is(dem, "SpatRaster"), directed = FALSE )
routes |
An sf object containing linestring geometries |
dem |
A raster object 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 |
Logical, whether to use terra package (default: auto-detected) |
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.
slope_xyz_simple(x)slope_xyz_simple(x)
x |
A 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")