rpygeo.geoprocessor {RPyGeo} | R Documentation |
This function creates a Python geoprocessing script file and runs it from the operating system using the ArcGIS Geoprocessor.
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)
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
fun ction. This adds to any extensions that are listed
in the env ironment 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 fun ction(s). |
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.
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
.
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.
Alexander Brenning
# 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)