Run the full ProcessSpace analysis in one call

The main entry point of the package. Takes a target stream reach and a LiDAR DEM, generates cross sections, extracts elevations, builds process-space polygons for each stage level, and writes a PDF report and (optionally) a Google Earth KMZ.

processSpace(
  streamChannel,
  rasterDir,
  streamDir = NULL,
  outputFilename = "ProcessSpace.pdf",
  stageLevels = c(1, 2),
  xSectionLength = units::as_units(100, "m"),
  xSectionDensity = units::as_units(20, "m"),
  cut1Dir = "W",
  getSatImage = TRUE,
  googleZoom = 16,
  provider = "Esri.WorldImagery",
  verticalCutoff = 4,
  detrendElevs = TRUE,
  detrendMethod = "crossSection",
  interpSmoothness = "Smooth",
  rasterPaletteLims = c(-2, 2),
  doExportSpatial = TRUE,
  addXSectionPlots = TRUE,
  addTopo = TRUE,
  returnObject = TRUE
)

Arguments

streamChannel

The target stream reach as an sf object: a single contiguous streamline, no forks or gaps.

rasterDir

File path of the LiDAR DEM raster. Read once and reused by every pipeline step.

streamDir

Optional path to the full stream-network shapefile, drawn for context on the overview map.

outputFilename

Base name for outputs: <name>.pdf report, <name>_temp_.kmz, <name>-Images/, and <name>_DetrendedRaster.tif.

stageLevels

Stage increases to model, in meters above the water surface (a units object is also accepted, e.g. units::as_units(c(1,2),"ft")). One process-space polygon layer is built per level. Default c(1, 2).

xSectionLength

Length of cross sections away from the channel.

xSectionDensity

Spacing between cross sections along the channel.

cut1Dir

Cardinal direction ("W","N","E","S") of the upstream end of the reach.

getSatImage

Logical; download the Esri World Imagery basemap (no API key needed). Falls back gracefully when offline.

googleZoom

Basemap tile zoom level (15-17 typically work).

provider

Tile provider passed to maptiles::get_tiles.

verticalCutoff

Cross-section points more than this many meters above/below the channel are trimmed from the plots.

detrendElevs

Logical; compute the detrended ("height above water") raster. The computationally expensive step.

detrendMethod

Detrending method: "crossSection" (default), "streamLine", or "gradeline" - see computeDetrendedRaster. Compare them with compareDetrendMethods.

interpSmoothness

"Smooth" or "Coarse" interpolation (see rasterPlotter).

rasterPaletteLims

Color-scale limits (meters) for the detrended raster overlay in the KMZ.

doExportSpatial

Logical; write the KMZ.

addXSectionPlots

Logical; render the per-transect cross-section PNGs embedded in the KMZ point balloons (the slow part of the export).

addTopo

Logical; add topographic contour lines to the map.

returnObject

Logical; return the transectObject for further use.

Value

The transectObject (invisibly NULL when returnObject = FALSE).

Details

This supersedes the generateCrossSections() %>% allAtOnce() pair with a single call and explicit arguments (no ... routing).

Examples

if (FALSE) { # \dontrun{
streams <- sf::read_sf(system.file("external/streams.shp",
                                   package = "ProcessSpace"))
targetStream <- dplyr::filter(streams, LINKNO %in% c(12, 20))
processSpace(targetStream,
             rasterDir = system.file("external/raster.tif",
                                     package = "ProcessSpace"),
             outputFilename = "exampleOutput.pdf",
             stageLevels = c(1, 2),
             xSectionDensity = units::as_units(10, "m"),
             cut1Dir = "W")
} # }