rsaga.env: Function to set up RSAGA geoprocessing environment: Set up the RSAGA Geoprocessing Environment

Description

rsaga.env creates a list with system-dependent information on SAGA path, module path and data (working) directory. This kind of a list is required by most RSAGA geoprocessing functions and is referred to as the 'RSAGA geoprocessing environment.'

Usage

rsaga.env(path = NULL, modules = NULL, workspace = ".",
  cmd = ifelse(Sys.info()["sysname"] == "Windows", "saga_cmd.exe",
  "saga_cmd"), version = NULL, cores, parallel = FALSE, root = NULL,
  lib.prefix)

Arguments

path

path in which to find cmd; rsaga.env is usually able to find SAGA on your system if it is installed; see Details.

modules

path in which to find SAGA libraries; see Details

workspace

path of the working directory for SAGA; defaults to the current directory (".").

cmd

name of the SAGA command line program; defaults to saga_cmd.exe, its name under Windows

version

optional character string: SAGA GIS (API) version, e.g. "2.0.8"; if missing, a call to rsaga.get.version() is used to determine version number of SAGA API

cores

optional numeric argument, or NA: number of cores used by SAGA GIS; supported only by SAGA GIS 2.1.0 (and higher), ignored otherwise (with a warning). Multicore-enabled SAGA GIS modules such as the one used by rsaga.pisr() seem to run in multicore mode by default when this argument is not specified, therefore cores should only be specified to use a smaller number of cores than available on a machine.

parallel

optional logical argument (default: FALSE): if TRUE, run RSAGA functions that are capable of parallel processing in parallel mode; note that this is completely independent of the behaviour of SAGA GIS (which can be controlled using the cores argument); currently only some RSAGA functions support parallel processing (e.g., pick.from.ascii.grid() or rsaga.get.modules()). parallel=TRUE requires that a parallel backend such as doSNOW or doMC is available and has been started prior to calling any parallelized RSAGA function, otherwise warnings may be generated

root

optional root path to SAGA GIS installation. It is used if RSAGA performce a search for the SAGA command line program (s. search). If left empty, on Windoes C:/ is used, on Linux /usr and on Mac OS /usr/local/Cellar.

lib.prefix

character string: a possible (platform-dependent) prefix for SAGA GIS library names; if missing (recommended), a call to rsaga.lib.prefix() tries to determine the correct prefix, e.g. "" on Windows systems and "lib" on non-Windows systems with SAGA GIS pre-2.1.0. Try specifying "" or "lib" manually if this causes problems, and contact the package maintainer if the detection mechanism fails on your system (indicate your Sys.info()["sysname"] and your SAGA GIS version)

Value

A list with components workspace, cmd, path, modules, version, cores and parallel with values as passed to rsaga.env or default values as described in the Details section.

Details

IMPORTANT: Unlike R functions such as options(), which changes and saves settings somewhere in a global variable, rsaga.env() does not actually 'save' any settings, it simply creates a list that can (and has to) be passed to other rsaga.* functions. See example below.

We strongly recommend to install SAGA GIS on Windows in C:/Program Files/SAGA-GIS, C:/Program Files (x86)/SAGA-GIS,C:/SAGA-GIS, C:/OSGeo4W64/apps/saga-lts or C:/OSGeo4W64/apps/saga. If you use a standalone version of SAGA GIS in a different path, please refer to section 2 bellow.

There are three ways to create a RSAGA environment with rsaga.env:

No paths to the SAGA command line program and to the SAGA modules are specified by the user through the arguments path and modules. On Windows rsaga.env tries to find the SAGA command line program in the following folders C:/Progra~1/SAGA-GIS, C:/Progra~2/SAGA-GIS, C:/SAGA-GIS, C:/OSGeo4W64/apps/saga-lts and C:/OSGeo4W64/apps/saga. If this fails and attempt is being made to find the SAGA command line program with a search on C:/ (The drive letter can be changed with the root argument). The subfolder tools (SAGA Version < 3.0.0 subfolder modules) is checked for the SAGA module libraries. On Unix systems rsaga.env tries to find the SAGA command line program in various default paths. Additionally, on Unix systems the PATH environment variable is checked for the path to the SAGA command line program and the SAGA_MLB environment variable is checked for the SAGA module libraries. If this fails, a search for the SAGA command line program and the module libraries is performed on /usr. If no SAGA command line program can be found, please specify the paths as described in section 2.
The user specifies both the path to the SAGA command line program and to the SAGA module libraries. Both paths are checked if they are valid. Use this if SAGA GIS is located in a non-standard path or if you use more than one SAGA GIS version.
The user specifies only the path to the SAGA command line program. A search for the SAGA modules is performed as described in section 1.

Examples

Run this code

# NOT RUN {
# Check the default RSAGA environment on your computer:
myenv <- rsaga.env()
myenv
# SAGA data in C:/sagadata, binaries in C:/SAGA-GIS, modules in C:/SAGA-GIS/modules:
myenv <- rsaga.env(workspace="C:/sagadata", path="C:/SAGA-GIS")
# Unix: SAGA in /usr/bin (instead of the default /usr/local/bin),
# and modules in /use/lib/saga:
# myenv <- rsaga.env(path="/usr/bin")
# Use the 'myenv' environment for SAGA geoprocessing:
rsaga.hillshade("dem","hillshade",env=myenv)
# ...creates (or overwrites) grid "C:/sagadata/hillshade.sgrd"
# derived from digital elevation model "C:/sagadata/dem.sgrd"

# Same calculation with different SAGA version:
# (I keep several versions in SAGA-GIS_2.0.x folders:)
myenv05 = rsaga.env(path = "C:/Progra~1/SAGA-GIS_2.0.5")
rsaga.hillshade("dem","hillshade205",env=myenv05)
# }