From 485303e4ea9a5ca418fa794e68e1c8f854bc7c13 Mon Sep 17 00:00:00 2001 From: Anatolii Tsyplenkov Date: Tue, 14 Jan 2025 12:19:43 +1300 Subject: [PATCH 1/2] feat: plan_curvature --- NAMESPACE | 1 + R/curvature.R | 91 +++++++++++++++++++++++-- R/filters.R | 6 +- man/wbw_plan_curvature.Rd | 63 +++++++++++++++++ tests/tinytest/test_curvature.R | 116 ++++++++++++++++++-------------- 5 files changed, 219 insertions(+), 58 deletions(-) create mode 100644 man/wbw_plan_curvature.Rd diff --git a/NAMESPACE b/NAMESPACE index e524ff2..fd45f8c 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -52,6 +52,7 @@ export(wbw_minimum_filter) export(wbw_multidirectional_hillshade) export(wbw_olympic_filter) export(wbw_percentile_filter) +export(wbw_plan_curvature) export(wbw_profile_curvature) export(wbw_random_sample) export(wbw_range_filter) diff --git a/R/curvature.R b/R/curvature.R index 3d1ec2a..9adc526 100644 --- a/R/curvature.R +++ b/R/curvature.R @@ -360,10 +360,10 @@ S7::method(wbw_mean_curvature, WhiteboxRaster) <- function( #' @description #' This tool calculates the profile curvature from a digital elevation #' model (\eqn{dem}), or the rate of change in slope along a flow line. -#' +#' #' Curvature is the second derivative of the topographic surface defined -#' by a DEM. Profile curvature characterizes the degree of downslope -#' acceleration or deceleration within the +#' by a DEM. Profile curvature characterizes the degree of downslope +#' acceleration or deceleration within the #' landscape (Gallant and Wilson, 2000). #' #' WhiteboxTools reports curvature in radians multiplied by 100 for easier @@ -402,8 +402,8 @@ S7::method(wbw_mean_curvature, WhiteboxRaster) <- function( #' #' @eval rd_wbw_link("profile_curvature") #' @references -#' Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, -#' in Terrain Analysis: Principles and Applications, edited by J. P. +#' Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, +#' in Terrain Analysis: Principles and Applications, edited by J. P. #' Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
#' Florinsky, I. (2016). Digital terrain analysis in soil science and #' geology. Academic Press.
@@ -448,3 +448,84 @@ S7::method(wbw_profile_curvature, WhiteboxRaster) <- function( source = out ) } + +#' Plan Curvature +#' @keywords geomorphometry +#' +#' @description +#' This tool calculates the plan curvature (i.e. contour curvature), or +#' the rate of change in aspect along a contour line, from a digital +#' elevation model (\eqn{dem}). Curvature is the second derivative of the +#' topographic surface defined by a DEM. Plan curvature characterizes the +#' degree of flow convergence or divergence within the +#' landscape (Gallant and Wilson, 2000). +#' +#' @details +#' WhiteboxTools reports curvature in degrees multiplied by 100 for easier +#' interpretation. The Z conversion factor (\eqn{z_factor}) is only important +#' when the vertical and horizontal units are not the same in the DEM. +#' When this is the case, the algorithm will multiply each elevation in the +#' DEM by the Z Conversion Factor. +#' +#' If the DEM is in the geographic coordinate system (latitude and longitude), +#' the following equation is used: +#' +#' \deqn{zfactor = \frac{1.0}{111320.0 \times \cos(midlat)}} +#' +#' The algorithm uses the same formula for the calculation of plan curvature +#' as Gallant and Wilson (2000). Plan curvature is negative for diverging +#' flow along ridges and positive for convergent areas, +#' e.g. along valley bottoms. +#' +#' @eval rd_input_raster("dem") +#' @param log_transform \code{logical}, default \code{FALSE}. Wheter +#' log-transform the output raster or not. See details. +#' @param z_factor \code{double}, Z conversion factor is only important +#' when the vertical and horizontal units are not the same in the DEM. +#' When this is the case, the algorithm will multiply each elevation in the +#' DEM by the Z conversion factor +#' +#' @return [WhiteboxRaster] object. +#' +#' @eval rd_wbw_link("plan_curvature") +#' @references +#' Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, +#' in Terrain Analysis: Principles and Applications, edited by J. P. +#' Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
+#' +#' @seealso [wbw_total_curvature()], [wbw_profile_curvature()] +#' +#' @eval rd_example("wbw_plan_curvature") +#' +#' @export +wbw_plan_curvature <- S7::new_generic( + name = "wbw_plan_curvature", + dispatch_args = "dem", + fun = function(dem, log_transform = FALSE, z_factor = 1) { + S7::S7_dispatch() + } +) + +S7::method(wbw_plan_curvature, WhiteboxRaster) <- function( + dem, + log_transform = FALSE, + z_factor = 1 +) { + # Checks + check_env(wbe) + checkmate::assert_logical(log_transform, len = 1) + checkmate::assert_double(z_factor, len = 1) + + # WBT + out <- wbe$plan_curvature( + dem = dem@source, + log_transform = log_transform, + z_factor = z_factor + ) + + # Return + WhiteboxRaster( + name = "Plan Curvature", + source = out + ) +} diff --git a/R/filters.R b/R/filters.R index e2728e6..b13b594 100644 --- a/R/filters.R +++ b/R/filters.R @@ -86,18 +86,18 @@ S7::method(wbw_adaptive_filter, WhiteboxRaster) <- function( #' similarity to the center pixel. #' #' The size of the filter is determined by setting the standard deviation -#' distance parameter (`sigma_dist`); the larger the standard deviation the +#' distance parameter (\code{sigma_dist}); the larger the standard deviation the #' larger the resulting filter kernel. #' The standard deviation can be any number in the range #' 0.5-20 and is specified in the unit of pixels. The standard deviation -#' intensity parameter (`sigma_int`), specified in the same units as the +#' intensity parameter (\code{sigma_int}), specified in the same units as the #' z-values, determines the intensity domain contribution to kernel weightings. #' #' @eval rd_input_raster("x") #' @param sigma_dist \code{double}, standard deviation distance parameter in #' **pixels**. #' @param sigma_int \code{double}, standard deviation intensity parameter, -#' in the same units as z-units of input raster `x` (usually, meters). +#' in the same units as z-units of input raster \code{x} (usually, meters). #' #' @return [WhiteboxRaster] object containing filtered values #' diff --git a/man/wbw_plan_curvature.Rd b/man/wbw_plan_curvature.Rd new file mode 100644 index 0000000..7596ea6 --- /dev/null +++ b/man/wbw_plan_curvature.Rd @@ -0,0 +1,63 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/curvature.R +\name{wbw_plan_curvature} +\alias{wbw_plan_curvature} +\title{Plan Curvature} +\usage{ +wbw_plan_curvature(dem, log_transform = FALSE, z_factor = 1) +} +\arguments{ +\item{dem}{Raster object of class \link{WhiteboxRaster}. See \code{\link[=wbw_read_raster]{wbw_read_raster()}} for more details.} + +\item{log_transform}{\code{logical}, default \code{FALSE}. Wheter +log-transform the output raster or not. See details.} + +\item{z_factor}{\code{double}, Z conversion factor is only important +when the vertical and horizontal units are not the same in the DEM. +When this is the case, the algorithm will multiply each elevation in the +DEM by the Z conversion factor} +} +\value{ +\link{WhiteboxRaster} object. +} +\description{ +This tool calculates the plan curvature (i.e. contour curvature), or +the rate of change in aspect along a contour line, from a digital +elevation model (\eqn{dem}). Curvature is the second derivative of the +topographic surface defined by a DEM. Plan curvature characterizes the +degree of flow convergence or divergence within the +landscape (Gallant and Wilson, 2000). +} +\details{ +WhiteboxTools reports curvature in degrees multiplied by 100 for easier +interpretation. The Z conversion factor (\eqn{z_factor}) is only important +when the vertical and horizontal units are not the same in the DEM. +When this is the case, the algorithm will multiply each elevation in the +DEM by the Z Conversion Factor. + +If the DEM is in the geographic coordinate system (latitude and longitude), +the following equation is used: + +\deqn{zfactor = \frac{1.0}{111320.0 \times \cos(midlat)}} + +The algorithm uses the same formula for the calculation of plan curvature +as Gallant and Wilson (2000). Plan curvature is negative for diverging +flow along ridges and positive for convergent areas, +e.g. along valley bottoms. +} +\examples{ +f <- system.file("extdata/dem.tif", package = "wbw") +wbw_read_raster(f) |> + wbw_plan_curvature() +} +\references{ +For more information, see \url{https://www.whiteboxgeo.com/manual/wbw-user-manual/book/tool_help.html#plan_curvature} + +Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, +in Terrain Analysis: Principles and Applications, edited by J. P. +Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J. \if{html}{\out{
}} +} +\seealso{ +\code{\link[=wbw_total_curvature]{wbw_total_curvature()}}, \code{\link[=wbw_profile_curvature]{wbw_profile_curvature()}} +} +\keyword{geomorphometry} diff --git a/tests/tinytest/test_curvature.R b/tests/tinytest/test_curvature.R index 669cbed..382f077 100644 --- a/tests/tinytest/test_curvature.R +++ b/tests/tinytest/test_curvature.R @@ -2,24 +2,28 @@ source("setup.R") # Test successful filter returns expect_inherits( - wbw_gaussian_curvature(x), - c("wbw::WhiteboxRaster", "S7_object") + wbw_gaussian_curvature(x), + c("wbw::WhiteboxRaster", "S7_object") ) expect_inherits( - wbw_maximal_curvature(x), - c("wbw::WhiteboxRaster", "S7_object") + wbw_maximal_curvature(x), + c("wbw::WhiteboxRaster", "S7_object") ) expect_inherits( - wbw_minimal_curvature(x), - c("wbw::WhiteboxRaster", "S7_object") + wbw_minimal_curvature(x), + c("wbw::WhiteboxRaster", "S7_object") ) expect_inherits( - wbw_mean_curvature(x), - c("wbw::WhiteboxRaster", "S7_object") + wbw_mean_curvature(x), + c("wbw::WhiteboxRaster", "S7_object") ) expect_inherits( - wbw_profile_curvature(x), - c("wbw::WhiteboxRaster", "S7_object") + wbw_profile_curvature(x), + c("wbw::WhiteboxRaster", "S7_object") +) +expect_inherits( + wbw_plan_curvature(x), + c("wbw::WhiteboxRaster", "S7_object") ) # Test curvature alterations @@ -30,62 +34,74 @@ expect_inherits( true_median <- median(x) expect_true( - wbw_gaussian_curvature(x) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_gaussian_curvature(x) |> + median() |> + all.equal(true_median) |> + is.character() +) +expect_true( + wbw_gaussian_curvature(x, log_transform = TRUE) |> + median() |> + all.equal(true_median) |> + is.character() +) +expect_true( + wbw_maximal_curvature(x) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_gaussian_curvature(x, log_transform = TRUE) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_maximal_curvature(x, log_transform = TRUE) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_maximal_curvature(x) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_minimal_curvature(x) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_maximal_curvature(x, log_transform = TRUE) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_minimal_curvature(x, log_transform = TRUE) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_minimal_curvature(x) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_mean_curvature(x) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_minimal_curvature(x, log_transform = TRUE) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_mean_curvature(x, log_transform = TRUE) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_mean_curvature(x) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_profile_curvature(x) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_mean_curvature(x, log_transform = TRUE) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_profile_curvature(x, log_transform = TRUE) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_profile_curvature(x) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_plan_curvature(x) |> + median() |> + all.equal(true_median) |> + is.character() ) expect_true( - wbw_profile_curvature(x, log_transform = TRUE) |> - median() |> - all.equal(true_median) |> - is.character() + wbw_plan_curvature(x, log_transform = TRUE) |> + median() |> + all.equal(true_median) |> + is.character() ) From d1d1a72c4fc59da707ff4ad7fe5df006d3d5ed54 Mon Sep 17 00:00:00 2001 From: Anatolii Tsyplenkov Date: Tue, 14 Jan 2025 13:21:57 +1300 Subject: [PATCH 2/2] docs: cross-reference fix --- R/curvature.R | 2 +- man/wbw_plan_curvature.Rd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/R/curvature.R b/R/curvature.R index 9adc526..1e47c85 100644 --- a/R/curvature.R +++ b/R/curvature.R @@ -493,7 +493,7 @@ S7::method(wbw_profile_curvature, WhiteboxRaster) <- function( #' in Terrain Analysis: Principles and Applications, edited by J. P. #' Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
#' -#' @seealso [wbw_total_curvature()], [wbw_profile_curvature()] +#' @seealso [wbw_profile_curvature()] #' #' @eval rd_example("wbw_plan_curvature") #' diff --git a/man/wbw_plan_curvature.Rd b/man/wbw_plan_curvature.Rd index 7596ea6..cd400c5 100644 --- a/man/wbw_plan_curvature.Rd +++ b/man/wbw_plan_curvature.Rd @@ -58,6 +58,6 @@ in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J. \if{html}{\out{
}} } \seealso{ -\code{\link[=wbw_total_curvature]{wbw_total_curvature()}}, \code{\link[=wbw_profile_curvature]{wbw_profile_curvature()}} +\code{\link[=wbw_profile_curvature]{wbw_profile_curvature()}} } \keyword{geomorphometry}