rpygeo.geoprocessor {RPyGeo}R Documentation

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

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.

Value

The function returns 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.

Note

The Python script created by this geoprocessor is loaded with initialization code for setting up the ArcGIS workspace and enabling ArcGIS extensions. This makes this function pretty inefficient, but you save a lot of time because you don't have to switch between three applications and two programming languages...

ArcGIS is pretty flexible with respect to numeric arguments such as the z factor in Slope_sa being passed as character string. As a consequence, quote.args=TRUE will normally work fine.

wait==FALSE is experimental and not recommended. Watch for file name conflicts if you really want to try it - competing geoprocessing scripts must use different temporary Python script files etc.

Author(s)

Alexander Brenning

See Also

rpygeo.build.env

Examples

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

[Package RPyGeo version 0.9-1 Index]