Using geoprocessing tools¶
In ArcGIS API for Python, geoprocessing toolboxes and tools within them are represented as Python module and functions within that module. To learn more about this organization, refer to the page titled Accessing geoprocessing tools.In this part of the guide, we will observe:
- Invoking geoprocessing tools
- Understanding tool input parameter and output return types
- Tools with multiple outputs
- Tools that export map image layer as output
Invoking Geoprocessing Tools¶
You can execute a geoprocessing tool easily by importing its toolbox as a module and calling the function for the tool. Let us see how to execute the extract_zion_data
tool from the Zion toolbox URL:
# connect to ArcGIS Online
from arcgis.gis import GIS
from arcgis.geoprocessing import import_toolbox
gis = GIS()
# import the Zion toolbox
zion_toolbox_url = 'http://gis.ices.dk/gis/rest/services/Tools/ExtractZionData/GPServer'
zion = import_toolbox(zion_toolbox_url)
result = zion.extract_zion_data()
Thus, executing a geoprocessing tool is that simple. Let us learn a few more concepts that will help in using these tools efficiently.
Understanding tool input parameter and output return types¶
The functions for calling geoprocessing tools can accept and return built-in Python types such as str, int, bool, float, dicts, datetime.datetime as well as some helper types defined in the ArcGIS API for Python such as the following:
arcgis.features.FeatureSet
- a set of featuresarcgis.geoprocessing.LinearUnit
- linear distance with specified unitsarcgis.geoprocessing.DataFile
- a url or item id referencing dataarcgis.geoprocessing.RasterData
- url or item id and format of raster data
The tools can also accept lists of the above types.
Note: When the helper types are used an input, the function also accepts strings in their place. For example '5 Miles' can be passed as an input instead of LinearUnit(5, 'Miles') and a URL can be passed instead of a DataFile
or RasterData
input.
Some geoprocessing tools are configured to return an arcgis.mapping.MapImageLayer
for visualizing the results of the tool.
In all cases, the documentation of the tool function indicates the type of input parameters and the output values.
Using helper types¶
The helper types (LinearUnit
, DataFile
and RasterData
) defined in the arcgis.geoprocessing
module are simple classes that hold strings or URLs and have a dictionary representation.
The extract_zion_data()
tool invoked above returns an output zip file as a DataFile
:
type(result)
The output Datafile
can be queried as shown in the snippet below.
result
The value types such as DataFile
include helpful methods such as download:
result.download()
Using strings as input¶
Strings can also be used as inputs in place of the helper types such as LinearUnit
, RasterData
and DataFile
.
The example below calls the viewshed tool to compute and display the geographical area that is visible from a clicked location on the map. The function accepts an observation point as a FeatureSet
and a viewshed distance as a LinearUnit
, and returns a FeatureSet
:
viewshed = import_toolbox('http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Elevation/ESRI_Elevation_World/GPServer')
help(viewshed.viewshed)
import arcgis
arcgis.env.out_spatial_reference = 4326
map = gis.map('South San Francisco', zoomlevel=12)
map
The code snippet below adds an event listener to the map, such that when clicked, get_viewshed()
is called with the map widget and clicked point geometry as inputs. The event handler creates a FeatureSet
from the clicked point geometry, and uses the string '5 Miles' as input for the viewshed_distance parameter instead of creating a LinearUnit
object. These are passed into the viewshed function that returns the viewshed from the observation point. The map widget is able to draw the returned FeatureSet
using its draw()
method:
from arcgis.features import Feature, FeatureSet
def get_viewshed(m, g):
res = viewshed.viewshed(FeatureSet([Feature(g)]),"5 Miles") # "5 Miles" or LinearUnit(5, 'Miles') can be passed as input
m.draw(res)
map.on_click(get_viewshed)
Tools with multiple outputs¶
Some Geoprocessing tools can return multiple results. For these tools, the corresponding function returns the multiple output values as a named tuple.
The example below uses a tool that returns multiple outputs:
sandiego_toolbox_url = 'https://gis-public.co.san-diego.ca.us/arcgis/rest/services/InitialResearchPacketCSV_Phase2/GPServer'
multioutput_tbx = import_toolbox(sandiego_toolbox_url)
help(multioutput_tbx.initial_research_packet_csv)
Invoking tools that create multple outputs¶
The code snippet below shows how multiple outputs returned from a tool can be automatically unpacked by Python into multiple variables. Also, since we're not interested in the job status output, we can discard it using "_" as the variable name:
report_output_csv_file, output_map_flags_file, soil_output_file, _ = multioutput_tbx.initial_research_packet_csv()
report_output_csv_file
output_map_flags_file
soil_output_file
Using named tuple to access multiple tool outputs¶
The code snippet below shows using a named tuple to access the multiple outputs returned from the tool:
results = multioutput_tbx.initial_research_packet_csv()
results.report_output_csv_file
results.job_status
Tools that export MapImageLayer as output¶
Some Geoprocessing tools are configured to return their output as MapImageLayer for easier visualization of the results. The resultant layer can be added to a map or queried.
An example of such a tool is below:
hotspots = import_toolbox('https://sampleserver6.arcgisonline.com/arcgis/rest/services/911CallsHotspot/GPServer')
help(hotspots.execute_911_calls_hotspot)
result_layer, output_features, hotspot_raster = hotspots.execute_911_calls_hotspot()
result_layer
hotspot_raster
The resultant hotspot raster can be visualized in the Jupyter Notebook using the code snippet below:
from IPython.display import Image
Image(hotspot_raster['mapImage']['href'])
Feedback on this topic?