R/gradient.R

In ambient: A Generator of Multidimensional Noise

#' Calculate the gradient of a scalar field
#'
#' The gradient of a scalar field such as those generated by the different noise
#' algorithms in ambient is a vector field encoding the direction to move to get
#' the strongest increase in value. The vectors generated have the properties of
#' being perpendicular on the contour line drawn through that point. Take note
#' that the returned vector field flows upwards, i.e. points toward the steepest
#' ascend, rather than what is normally expected in a gravitational governed
#' world.
#'
#' @inheritParams curl_noise
#' @param x,y,z,t The coordinates to generate the gradient for as unquoted expressions
#' @param seed A seed for the generator.
#'
#' @export
#'
#' @family derived values
#'
#' @examples
#' grid <- long_grid(seq(0, 1, l = 100), seq(0, 1, l = 100))
#'
#' # Use one of the generators
#' grid$gradient <- gradient_noise(gen_simplex, x = grid$x, y = grid$y)
#' plot(grid$x, grid$y, type = 'n')
#' segments(grid$x, grid$y, grid$x + grid$gradient$x / 100, grid$y + grid$gradient$y / 100)
#'
gradient_noise <- function(
  generator,
  x,
  y,
  z = NULL,
  t = NULL,
  ...,
  seed = NULL,
  delta = NULL
) {
  if (is.null(seed)) {
    seed <- random_seed()
  }
  if (is.null(delta)) {
    delta <- max(
      diff(range(x)),
      diff(range(y %||% 0)),
      diff(range(z %||% 0)),
      diff(range(t %||% 0))
    ) *
      1e-4
  }
  gradient <- list(
    x = (generator(x + delta, y, z, t, seed = seed, ...) -
      generator(x - delta, y, z, t, seed = seed, ...)) /
      (2 * delta)
  )
  if (!is.null(y)) {
    gradient$y <- (generator(x, y + delta, z, t, seed = seed, ...) -
      generator(x, y - delta, z, t, seed = seed, ...)) /
      (2 * delta)
  }
  if (!is.null(z)) {
    gradient$z <- (generator(x, y, z + delta, t, seed = seed, ...) -
      generator(x, y, z - delta, t, seed = seed, ...)) /
      (2 * delta)
  }
  if (!is.null(t)) {
    gradient$t <- (generator(x, y, z, t + delta, seed = seed, ...) -
      generator(x, y, z, t - delta, seed = seed, ...)) /
      (2 * delta)
  }
  as.data.frame(gradient)
}