R/lighting.R

In loreabad6/terrain: Utility Functions for Terrain Derivatives Calculations

#' Calculate derivatives from the Lighting module
#'
#' @param elev_sgrd input, elevation raster data in SAGA format,
#'                  can be created with \code{elev_to_sgrd()}
#' @param out_dir output directory
#' @param prefix character prefix for output filenames
#' @param envir environment to get SAGA installation,
#'            can be set with \code{init_saga()}
#' @param ... ignored, check help page for possible outputs
#' @param shade Hillshade:
#'              shaded relief from a surface raster by considering the
#'              illumination source angle and shadows.
#'              Boolean, defaults to \code{FALSE}
#' @param svfct,visky Sky View Factor and Visible Sky:
#'              Crucial variable widely used to quantify the characteristics
#'              of surface structures and estimate surface radiation budget.
#'              The SVF expresses the proportion (ratio) of radiation leaving
#'              the sky, assumed isotropic, that is able to reach a ground
#'              surface tilted at an arbitrary angle. Its value must vary
#'              between the minimum of 0, when the sky is not visible at all
#'              and to the maximum of 1, when the ground surface is horizontal
#'              and the sky entirely visible. Visible Sky is computed within
#'              the same algorithm.
#'              Boolean, defaults to \code{FALSE}
#' @param posop,negop Topographic Openness:
#'              Topographic openness expresses the dominance (positive) or
#'              enclosure (negative) of a landscape location. Openness has been
#'              related to how wide a landscape can be viewed from any position.
#'              It has been proven to be a meaningful input for computer aided
#'              geomorphological mapping. Openness is an angular measure of the
#'              relation between surface relief and horizontal distance. For
#'              angles less than 90", it is equivalent to the internal angle of
#'              a cone, its apex at a DEM location, constrained by neighboring
#'              elevations within a specified radial distance. Openness
#'              incorporates the terrain line-of-sight, or viewshed, concept
#'              and is calculated from multiple zenith and nadir angles-here
#'              along eight azimuths. Openness has two viewer perspectives.
#'              Positive values, expressing openness above the surface, are
#'              high for convex forms, whereas negative values describe this
#'              attribute below the surface and are high for concave forms.
#'              Openness values are mapped by gray-scale tones. The emphasis
#'              of terrain convexity and concavity in openness maps facilitates
#'              the interpretation of landforms on the surface of the Earth and
#'              its seafloor, and on the planets, as well as features on any
#'              irregular surface-such as those generated by industrial
#'              procedures.
#'              Boolean, defaults to \code{FALSE}
#'
#' @importFrom here here
#' @importFrom RSAGA rsaga.geoprocessor
#' @export
elev_to_lighting = function(elev_sgrd, out_dir,
                            prefix = '', envir, ...,
                            negop = FALSE, posop = FALSE, shade = FALSE,
                            svfct = FALSE, visky = FALSE) {
  # Hillshade - Module 0
  if (shade) {
    rsaga.geoprocessor(
      'ta_lighting', 0,
      list(
        ELEVATION = elev_sgrd,
        SHADE = here(out_dir, paste0(prefix, "shade", ".sgrd"))
      ),
      env = envir
    )
  }

  # Sky View Factor - Module 3
  module_3_params_set = list(
    SVF = if (svfct) here(out_dir, paste0(prefix, "svfct", ".sgrd")),
    VISIBLE = if (visky) here(out_dir, paste0(prefix, "visky", ".sgrd"))
  )

  module_3_params = module_3_params_set[lengths(module_3_params_set) > 0]

  if (length(module_3_params) > 0) {
    params = append(
      list(DEM = elev_sgrd, METHOD = 1, DLEVEL = 3),
      module_3_params
    )
    rsaga.geoprocessor('ta_lighting', 3, params, env = envir)
  }

  # Topographic Openness - Module 5
  module_5_params_set = list(
    POS = if (posop) here(out_dir, paste0(prefix, "posop", ".sgrd")),
    NEG = if (negop) here(out_dir, paste0(prefix, "negop", ".sgrd"))
  )

  module_5_params = module_5_params_set[lengths(module_5_params_set) > 0]

  if (length(module_5_params) > 0) {
    params = append(
      list(DEM = elev_sgrd, METHOD = 0, DLEVEL = 3),
      module_5_params
    )
    rsaga.geoprocessor('ta_lighting', 5, params, env = envir)
  }
}