rpygeo.geoprocessor: ArcGIS Geoprocessor Workhorse

Description

This function creates a Python geoprocessing script file and runs it from the operating system using the ArcGIS Geoprocessor.

Usage

rpygeo.geoprocessor(fun, args = NULL, py.file = "rpygeo.py",  msg.file = "rpygeo.msg", env = rpygeo.env, extensions = NULL,  working.directory = getwd(), quote.args = TRUE, add.gp = TRUE,  wait = TRUE, clean.up = wait, detect.required.extensions = TRUE)

Arguments

fun

This can be either a complete Python geoprocessing command (see examples), a single geoprocessing function name, or a vector of function or Python expressions to be evaluated by the Python geoprocessor.

args

Vector or list of arguments to be passed to the function listed in fun. The argument quote.args determines whether these arguments will be decorated with quotation marks.

py.file

Name of the temporary Python script file (in the working.directory).

msg.file

Name of the temporary file in which to dump Python/ArcGIS error messages (in the working.directory).

env

A list defining the RPyGeo working environment. Defaults to the standard working environment rpygeo.env, which is created at start-up. See rpygeo.build.env for details.

extensions

Optional character vector listing ArcGIS extension that should be enabled before using the geoprocessing function. This adds to any extensions that are listed in the environment or eventually detected by rpygeo.required.extensions.

working.directory

The working directory for temporary files (i.e. the Python script and error message files); defaults to R's current working directory.

quote.args

Logical value (default: TRUE) or logical vector that determines whether quotation marks have to be added to the args arguments before passing them to Python. If this is a vector, it must have the same length as args. See Details.

add.gp

Logical (default: TRUE). See Details.

wait

Logical (default: TRUE). Experimental(!) option. If FALSE (NOT recommended), do not wait for the operating system / ArcGIS to finish the Python geoprocessing script.

clean.up

Logical (default TRUE) or character vector ("msg", "py", or c("msg","py")). Determines whether the error message file, the Python script file, or both (default) should be deleted after geoprocessing is finished. Ignored if wait is FALSE.

detect.required.extensions

Logical (default: TRUE). Determines whether rpygeo.required.extensions should try to find out which ArcGIS extensions are required to evaluate the function(s).

Value

NULL if is was successful, or otherwise a character vector with the ArcGIS error message. In addition, the ArcGIS function will generate the output described in the ArcGIS help files etc. Depending on the clean.up argument, the Python code may still be available in the py.file, and error messages in msg.file.

Details

This function is the R geoprocessing workhorse that creates a Python geoprocessing script, runs it, and returns any error messages.

If fun is a ready-to-use Python expression such as , then add.gp only determines whether the "gp." has to be added as a prefix to access the Python geoprocessor or not. In most cases however, fun will be a single ArcGIS geoprocessing script function such as "Slope_sa", where "_sa" tells us that this function can be found in the Spatial Analyst extension of ArcGIS (rpygeo.required.extensions will check this for you if the detected... argument is TRUE) Now args will be a vector or list of arguments to Slope_sa, e.g. c("dem","slope") or list("dem","slope","PERCENT_RISE",2) (see ArcGIS help files for information on the arguments of Slope_sa). These will result in Python expressions gp.Slope_sa("dem", "slope") and gp.Slope_sa("dem", "slope", "PERCENT_RISE", 2) if add.gp==TRUE and if we use the quote.args arguments TRUE and c(T,T,T,F), respectively. Dataset names will always be relative to the path or geodatabase defined in the geoprocessing environment settings env$workspace. Also, ArcGIS will be allowed to overwrite any existing output files (env$overwriteoutput==1) or not (==0). See rpygeo.build.env for details.

Examples

Run this code

# Allow ArcGIS to overwrite existing datasets:
## Not run: rpygeo.env$overwriteoutput = 1
# Calculate the slope of a DEM raster dataset
# in the current ArcGIS workspace:
## Not run: rpygeo.geoprocessor("Slope_sa",c("dem","slope"))
# Same:
## Not run: rpygeo.geoprocessor("Slope_sa('dem','slope')")
# Same, using the more convenient wrapper:
## Not run: rpygeo.Slope.sa("dem","slope")

# Three at a time or separately:
## Not run: date()
## Not run: rpygeo.geoprocessor("Slope_sa('dem','slope')",
#   "Aspect_sa('dem','aspect')", "Hillshade_sa('dem','hshd')")## End(Not run)
## Not run: date() # ~20 sec on my computer
## Not run: rpygeo.Slope.sa("dem","slope")
## Not run: rpygeo.Aspect.sa("dem","aspect")
## Not run: rpygeo.Hillshade.sa("dem","hshd")
## Not run: date() # ~50 sec
## Not run: rpygeo.Delete.management("slope")
## Not run: rpygeo.Delete.management("aspect")
## Not run: rpygeo.Delete.management("hshd")

# Calculate the Euclidian distance from railway lines
# up to a max. distance of 1000 map units:
## Not run: rpygeo.geoprocessor("EucDistance_sa",
#     args=list("rail.shp","raildist",1000))## End(Not run)
# Same:
## Not run: rpygeo.EucDistance.sa("rail.shp","raildist",maxdist=1000)

# Use MapAlgebra to calculate a distance-decay function:
## Not run: rpygeo.geoprocessor("SingleOutputMapAlgebra_sa",
#     args=c("exp( raildist / -100 )","distdecay"))## End(Not run)

# Or why not in just one step if you like MapAlgebra:
## Not run: rpygeo.geoprocessor( "SingleOutputMapAlgebra_sa",
#     args=c("exp( EucDistance( rail.shp, \#, \#, 1000 ) / -100 )","distdecay") )## End(Not run)