rsaga.env: Set up the RSAGA Geoprocessing Environment
In debangs/RSAGA: SAGA Geoprocessing and Terrain Analysis in R

Description Usage Arguments Details Value Note Author(s) See Also Examples

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.'

rsaga.env(workspace = ".", cmd = ifelse(Sys.info()["sysname"] == "Windows",
  "saga_cmd.exe", "saga_cmd"), path, modules, version, cores,
  parallel = FALSE, check.libpath = TRUE, check.SAGA = TRUE,
  check.PATH = Sys.info()["sysname"] == "Windows", check.os.default = TRUE,
  os.default.path = rsaga.default.path(), lib.prefix)

`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
`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
`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
`check.libpath`	if `TRUE` (default), first look for SAGA GIS in the folder where the RSAGA package is installed
`check.SAGA`	if `TRUE` (default), next check the path given by the environment variable `SAGA`, if it exists
`check.PATH`	if `TRUE` (default on Windows), next look for SAGA GIS in all the paths in the `PATH` environment variable; defaults to `FALSE` on non-Windows OS
`check.os.default`	if `TRUE`, look for SAGA GIS in the folder specified by `os.default.path`.
`os.default.path`	on Windows, `C:/Progra~1/SAGA-GIS`; on unix, an attempt is made to locate `saga_cmd`
`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)

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.

I strongly recommend to install SAGA GIS in "C:/Program Files/SAGA-GIS" in the case of English-language Windows platforms (the equivalent non-English installation folder in the case of non-English Windows versions seems to work as well). If this is the only SAGA GIS copy on the computer and you do not define a Windows environment variable SAGA, then RSAGA should normally be able to find your SAGA GIS installation in this folder.

rsaga.env tries to collect infromation on the (R)SAGA environment. If path is missing, rsaga.env first looks for an environment variable SAGA; if this is undefined, it checks the current working directory, then the paths given in the PATH environment variable, and finally the function's guess is "C:/Progra~1/SAGA-GIS" (or "/usr/local/bin" on non-Windows systems).

The default modules folder on Windows systems is the modules subfolder of the SAGA binaries' folder. The SAGA_MLB environment variable is not checked by rsaga.env.

On Unix (and Mac OS X) systems, the default modules folder is as specified in the SAGA_MLB environment variable. If this is empty / not set, then the following backup path is used. If path ends with "/bin", then "/bin" is changed to "/lib/saga" and taken as the modules path; otherwise, /usr/local/lib/saga is used.

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.

Note that the default workspace is ".", not getwd(); i.e. the default SAGA workspace folder is not fixed, it changes each time you change the R working directory using setwd.

Alexander Brenning

rsaga.get.version

## 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)

## End(Not run)