provides tutorials on how to make a script tool and how to make a processing op Make sure the DLL is registered on your machine. …
Processing Schematic Networks with ArcToolbox
By Tim Whiteaker
7/6/03
Abstract
A tool is written to process the Arc Hydro schematic network using ArcGIS
90 ArcToolbox technology By default, the processing performs a simple
accumulation routines with attributes on the schematic features in order
from upstream features to downstream features However, more complex
processing behavior may be associated with the tool by creating DLLs that
serve as processing ops As a result, a certain degree of hydrologic
modeling may be performed from within the GIS
Table of Contents
Abstract i
Table of Contents ii
1 Introduction 1
2 Background 2
21 Arc Hydro Schematic Network 2
22 ArcToolbox 90 4
23 Scripts and DLLs 5
3 Methodology 6
31 Schematic Features 6
311 Schematic Nodes 6
312 Schematic Links 7
32 Schematic Values 7
321 Received Values 8
322 Incremental Values 8
323 Total Values 9
324 Passed Values 9
33 Schematic Behaviors 10
331 Receiving Behavior 10
332 Passing Behavior 10
34 Processing Order 11
4 Procedure of Application 12
41
Data Model 12
411 Schematic Node and Schematic Link Classes 12
412 Attributes of Schematic Features 12
42 Processing Procedure 13
421 Data Preparation 14
422 The Process Loop 15
43 Implementation with ArcToolbox 18
431 ProcessSchematic Script Tool 19
432 ProcSchematic Script 22
433 MBSchematic DLL 23
434 Processing Ops 23
5 Results 24
6 Conclusions 30
Appendix A: Tutorials 31
A1 How to Create a Script Tool 31
A2 How to Create a Processing Op 37
1 Introduction
The ArcGIS Hydro data model Arc Hydro provides a framework for organizing
and preprocessing geospatial and temporal data for use in hydrologic and
hydraulic simulation models One of the products created by Arc Hydro is a
schematic network, which represents connectivity between features in the
landscape through a network of nodes and links This paper describes a
methodology for processing attributes of schematic networks using ArcGIS
90 ArcToolbox technology The network is processed starting with upstream
features and moving downstream, so that values are passed along the
network The process assumes that the network is dendritic and that
no
backwater effects occur Thus for each feature, all inputs are processed
and then passed accordingly to the next downstream feature This type of
application is useful in receiving loads of contaminants from watersheds,
and decaying the loads along the stream network to calculate a final load
at the outlet of the network
The paper is organized into six chapters The first chapter provides an
introduction to the research topic The second chapter provides background
information on Arc Hydro schematic networks and ArcToolbox The third
chapter outlines the methodology used in this research The fourth chapter
describes the procedure for applying the methodology The fifth chapter
presents results, while the final chapter draws conclusions from the
research
This paper also includes an appendix that provides tutorials on how to make
a script tool and how to make a processing op for the ProcessSchematic
tool
2 Background
21 Arc Hydro Schematic Network
Arc Hydro organizes water resources data into a set of feature classes in a
geodatabase Each feature class possesses attributes for describing data
of a particular type Feature classes may also participate in
relationships with
other feature classes These relationships are
maintained through key fields in the feature classes More information on
Arc Hydro can be found at the Arc Hydro Online Support System
http://wwwcrwrutexasedu/giswr/hydro/ArcHOSS/indexcfm, or from the Arc
Hydro book
Through the attributes and relationships of Arc Hydro, a schematic network
may be created that describes the connectivity between features From this
point on, the term schematic network will be used to describe an Arc
Hydro schematic network in this paper
A schematic network may be created from up to two Arc Hydro feature
classes Typically, Watersheds and HydroJunctions are used for this
purpose The JunctionID attribute on a Watershed stores the HydroID of the
HydroJunction that serves as the outlet for that Watershed The NextDownID
attribute of a HydroJunction stores the HydroID of the next downstream
HydroJunction
Figure 21 Geospatial Data Representing Watersheds and the Hydro Network
With these attributes, connectivity is established between Watersheds and
HydroJunctions From this connectivity, a schematic network representing
those features may be created
Figure 22 Schematic Network Representing
Watersheds and HydroJunctions
The schematic network is composed of two feature classes: Schematic link
and Schematic node Schematic nodes are located at the centroid of the
features that they represent Schematic links are straight lines that
connect Schematic nodes The Schematic nodes contain a field called
FeatureID, which stores the HydroID of the source feature that is
represented by the schematic feature Schematic links contain FromNodeID
and ToNodeID, which identify the HydroID of the Schematic nodes connected
to a given Schematic link FromNodeID identifies the from node, and
ToNodeID identifies the to node
The schematic features are further subdivided into two types Type 1
features are associated with a JunctionID-HydroID relationship from the
source features, such as JunctionID on Watershed pointing to the HydroID of
that Watersheds outlet HydroJunction Type 2 features are associated with
a NextDownID-HydroID relationship from the source features see Fig 23
The types are specified in the SrcType attribute of Schematic node, and the
LinkType attribute of Schematic link
Once the schematic network has been created, attributes from the source
features may be copied to
the schematic features using the FeatureID-
HydroID association
Figure 23 Schematic Network Overlain on Watersheds and the Hydro Network
22 ArcToolbox 90
In ArcGIS 90, the user may create custom tools for ArcToolbox as Script
Tools A script tool retrieves geospatial inputs from the GIS, and then
calls a script to perform processing on that data
Figure 24 ArcCatalog View of a Toolbox with a Script Tool
Attaching a script to a tool creates functionality beyond what the core
ArcToolbox tools provide Through a script, any number of DLLs or
executables may be called to perform advanced processing before finally
returning control back to ArcToolbox In simpler applications, the
processing may take place in the script itself, for example in using
empirical relationships to calculate runoff from rainfall over a given
area
23 Scripts and DLLs
The programming code required to implement the methodology presented in
this paper is stored in scripts and DLLs A script consists of lines of
programming code that may be executed at any time While typically lacking
in the robustness and complexity of DLLs and executables, scripts provide a
quick way to get a job done Scripts
may be written in one of several
scripting languages VBScript is used as the scripting language in this
research
A DLL dynamic linked library contains functions and subroutines for
performing work Often, the procedures in a DLL are accessed by
instantiating classes within the DLL A DLL cannot execute on its own It
is called from within another process operating on the computer DLLs are
typically much more powerful than scripts They are written in programming
languages such as C and Visual Basic Visual Basic is used as the
programming language for DLLs in this research
3 Methodology
This chapter describes the methodology used in this research to process
schematic networks The schematic network is composed of Schematic Node
features and Schematic Link features Each feature has a set of attributes
that describe the state of that feature and what information it will pass
to the next downstream feature in the network Also associated with each
feature is a set of behaviors that define how the feature responds to
information from upstream features, and how the feature determines what
information will be passed to the next downstream feature
Processing a schematic network
means performing some kind of modeling to
pass hydrologic information along the network The methodology used in
this research applies to schematic networks in which information is only
passed in the downstream direction Thus before a given schematic feature
is processed, all upstream features must have already been processed
31 Schematic Features
There are two classes of schematic features: schematic nodes and schematic
links These features are described below
311 Schematic Nodes
A schematic node represents a hydrologic feature, such as a watershed or a
junction in the stream network Schematic nodes are typically created from
polygon or point features, with a node being located at the centroid of its
related polygon feature or at the same location as its related point
feature
Figure 31 Schematic Node at the Centroid of Corresponding Watershed
Feature
312 Schematic Links
A schematic link represents a connection between two schematic nodes A
schematic link cannot be connected to more than two schematic nodes,
although a schematic node could be connected to several schematic links
In other words, a schematic link exists for every connection that a
schematic node has with
other schematic nodes In Figure 31, the node
with FeatureID 2940, which represents a watershed, is connected to the node
with FeatureID 1595, which represents the stream network junction serving
as the outlet of the watershed, by a schematic link represented as a
straight green line
32 Schematic Values
The movement of water or contaminants in the water across the landscape
can be simulated by passing values down the schematic network Schematic
network features incorporate four types of values: received values,
incremental values, total values, and passed values
321 Received Values
Received values are those values received by a schematic feature from
adjacent upstream schematic features, after the values passed from those
upstream features have been processed by the receiving feature A node can
only receive values from adjacent upstream links, and a link can only
receive a value from its adjacent upstream node
As an example, consider the simple schematic network shown in Figure 32
Node 2 represents the most downstream feature in the network Links 1 and
2 are connected to upstream schematic features beyond the dashed lines
Suppose that streamflow is being routed throughout
the network Link 1 and
Link 2 both flow into Node 1 Therefore, the received values for Node 1
consist of the streamflows from Link 1 and Link 2
Figure 32 Sample Schematic Network
Once the streamflows are combined, Node 1 passes those flows to Link 3
Thus, the received value for Link 3 consists of the streamflow from Node 1
322 Incremental Values
An incremental value is the value incorporated into the schematic network
at a given schematic features location Continuing the example using
Figure 32, suppose that Node 1 is also at the location of a rice field A
certain volume of water is withdrawn at that location for irrigation
purposes This water is removed from the schematic network Thus Node 1
would possess a negative incremental value, which is taken into account
when determining how much water from Links 1 and 2 is passed to Link 3
Figure 33 Water Withdrawal at Node 1 Represented as a Negative Incremental
Value
Incremental values may also be positive For example, at a node
representing a watershed, the incremental value for that node could be the
runoff produced in that watershed from a given rainfall event
323 Total Values
The total value for a schematic
feature is obtained by combining the
incremental value and the received values, most commonly by simple
addition For example, the total flow for Node1 in Figure 33 is the sum
of the streamflows from Links 1 and 2, minus the flow withdrawn for
irrigation purposes
324 Passed Values
A passed value is the value that a schematic feature passes to the next
downstream feature in the network Continuing the example above, suppose
that the streamflow passed from Node 1 to Link 3 includes a bacterial load
As the bacteria travel along the length of the stream connecting the
junctions represented by Nodes 1 and 2, suppose that the bacteria decay
according to a first order decay rate The bacterial load at the most
downstream point of Link 3, after the decay rate has been applied, is the
load that Link 3 passes to Node 2
Figure 34 Passing of Bacterial Load from Link 3 to Node 2
33 Schematic Behaviors
When communicating with other schematic features, a given schematic feature
possesses certain behaviors that control how that feature will accept
values from upstream features, and how it will pass values to downstream
features These behaviors are called receiving behavior and
passing
behavior, respectively Each behavior uses the values associated with a
given schematic feature, along with other attributes and algorithms as
necessary, to determine the final value for a given attribute of that
feature
331 Receiving Behavior
Receiving behavior defines how a schematic feature processes incoming
values along with its incremental value to produce a total value for that
feature The simplest example of receiving behavior is to calculate the
sum of all incoming values and the incremental value for a given feature
Using the example in Figure 34, if Link 1 and Link 2 pass bacterial loads
of 7 and 8 lb/day, respectively, and Node 1 has an incremental value of 2
lb/day, then the total value for Node 1 is simply the sum of those values,
or 17 lb/day
For a more complex example of receiving behavior, consider two links that
pass a time series of information rather than a single value to a node
The node must combine the two time series to produce a total time series
This process involves grouping together and processing values based on each
time step, which may require interpolation
332 Passing Behavior
Passing behavior defines how a schematic feature processes
its total value
to produce a value that will be passed to the next downstream schematic
feature The simplest example of passing behavior is to pass the total
value for a given feature
Using the example in Figure 34, the passing behavior for Link 3 involves a
first order decay process Thus, without any new bacterial load inputs,
the load passed to Node 2 from Link 3 will be less than the load received
by Link 3, due to decay along the length of the link
34 Processing Order
This methodology applies to schematic networks in which no backwater
effects occur In other words, each schematic feature receives no
information from or about downstream schematic features However, since
each feature does receive information from upstream features, all upstream
features should be processed so that they know what value they should
pass before processing a given schematic feature
Thus a processing order must be established so that upstream features are
processed before downstream features An implementation of an ordering
scheme is described in Chapter 4: Procedure of Application
4 Procedure of Application
This chapter describes the procedure used to implement the methodology
described in
Chapter 3 within the ArcGIS 90 ArcToolbox environment This
procedure includes a data model to support schematic navigation and
attribute storage, an algorithm for sorting the schematic features from
upstream to downstream, and the actual implementation of the procedure in
ArcToolbox The ArcToolbox tool is called ProcessSchematic
41 Data Model
411 Schematic Node and Schematic Link Classes
The ProcessSchematic tool operates on two geodatabase object classes: a
schematic node class and a schematic link class These classes may be
feature classes or standalone tables, as the geometry of the nodes and
links is not taken into consideration by the ProcessSchematic tool
Rather, the tool uses attributes within the node and link classes to
establish connectivity between them Thus, any two feature classes or
tables or combination thereof may be used with the ProcessSchematic tool,
as long as they are located in the same geodatabase Note that if the
schematic nodes and links are stored in tables, those tables must be
registered with the geodatabase
The ProcessSchematic tool was designed to operate on an Arc Hydro schematic
network, which uses feature classes to represent schematic
nodes and links
Therefore, while the technically correct description of a schematic
element in a standalone table is a row, the term feature will be used to
describe schematic elements, as that term provides a better conceptual
context of what a schematic element represents In other words, schematic
nodes and schematic links will be referred to as schematic features,
whether or not they belong to a feature class or a table
412 Attributes of Schematic Features
Arc Hydro Attributes
Because the ProcessSchematic tool was designed to operate on an Arc Hydro
schematic network, the tool assumes that the Arc Hydro schematic attributes
exist in the schematic node and schematic link classes These attributes
are used for identifying schematic features and navigating the schematic
network
For Schematic Nodes, these attributes include:
HydroID - Unique identifier for the feature in the geodatabase
SrcType - Integer, user-defined, which indicates the type of the
schematic feature
For Schematic Links, these attributes include:
HydroID - Unique identifier for the feature in the geodatabase
LinkType - Integer, user-defined, which indicates the type of the
schematic feature
FromNodeID - The HydroID of the schematic node located at the
beginning of the schematic link
ToNodeID - The HydroID of the schematic node located at the end of the
schematic link
In order for the ProcessSchematic tool to work correctly, all HydroIDs for
the schematic features must be unique within the geodatabase
Value Attributes
In addition to the Arc Hydro attributes, schematic features may also
possess attributes that describe the values that those features operate
with For both the schematic node and link classes, these optional
attributes include:
Incremental Value - Stores the incremental value for the given feature
Total Value - Stores the total value for the given feature
Passed Value - Stores the value that the feature will pass to the next
downstream feature in the network
By default, the ProcessSchematic tool obtains values to be processed in the
schematic network from the incremental value field Any values in the
total value field or the passed value field will be overwritten by the new
values calculated by the tool If the user does not wish to store the
total value or the passed value in the attribute
table for the schematic
features, then these attributes need not be provided to the
ProcessSchematic tool The incremental value field is also left as an
optional attribute, in case the user wishes to perform schematic processing
that requires complexity than using the incremental value field as a
starting point for obtaining values in the network
Supplemental Attributes
Depending on what type of process is specified for each feature, other
attributes may be required For example, when decaying loads along a
schematic link, travel time and decay constant may be required In these
cases, the attributes may be located on the features to which they pertain
These attributes are not read directly by the ProcessSchematic tool, but
by the specific processing op designed to work with those attributes
Processing ops are described in Section 43
42 Processing Procedure
This section describes the procedure used by the ProcessSchematic tool for
working with schematic networks The procedure may be summarized into two
major components: Data Preparation and the Process Loop
In Data Preparation, the features in the schematic network are sorted from
upstream to downstream, and collections are
initialized that will store
values during the processing of the network
Once the features have been sorted, each feature is processed in the
correct order until all features have been processed Two types of
processes may occur: a receive process and a pass process
Receive Process
In a receive process, values received from upstream features are processed
along with the incremental value for a given feature to produce a total
value for that feature By default, a receive process invokes a simple
accumulation, so that all values received by a feature are added to its
incremental value to produce the total value for that feature If more
complex processing is required, a DLL may be provided as a processing op to
perform the receive process
Pass Process
In a pass process, the total value for a given feature is processed to
produce a value that the feature will pass to the next downstream feature
By default, a pass process simply passes the total value for a given
feature to the next downstream feature If more complex processing is
required, a DLL may be provided as a processing op to perform the pass
process
421 Data Preparation
Before processing can begin, the schematic features
must first be sorted so
that features are processed from upstream to downstream Consider the
schematic network in Figure 41 In this network, Type 1 features are
colored green, and Type 2 features are colored red The number shown by
each feature represents the HydroID for that feature Schematic nodes have
HydroIDs indexed at 1000, while schematic links are indexed at 4000 The
features at the top of the diagram represent the most upstream features,
while the feature at the bottom of the diagram ie schematic node 1007
represents the most downstream feature
Using the FromNodeID and ToNodeID attributes on schematic link, a Sort
Collection is built containing the schematic features in order from
upstream to downstream A collection is a Visual Basic object containing
a set of values or other objects For example, in the sample schematic in
Figure 31, the Sort Collections first entry might be the feature with
HydroID 1001, followed by the feature with HydroID 4002, and so on
A Topology Collection is also created at this time For each feature, this
collection stores the HydroIDs of upstream features, indexed by the HydroID
of the current feature For example, the feature with
HydroID 1003 will
have associated HydroIDs of 4002 and 4004 in the Topology Collection
Finally, a Value Collection is created to store the values that each
feature will pass to the next downstream feature For example, the
schematic node with HydroID 1001 might have a value of 30 in the Value
Collection, which may represent the flow that the node sends downstream
These collections serve as efficient tools in processing the schematic
network
Figure 41 Sample Schematic Network
422 The Process Loop
Once the features in the schematic network have been sorted, each feature
is processed in the correct order For each feature, upstream values are
processed and combined with the incremental value for that feature using a
receive process The combined value is then processed using a pass process
to produce a value that will be passed to the next downstream feature, and
so on There are five steps in the process loop:
1 Get upstream features
2 Get upstream values
3 Process upstream and incremental values
4 Process current value to pass downstream
5 Update Value Collection with value to pass
To illustrate the process loop, an example using the schematic link
with
HydroID 4003 from the network in Figure 41 is given
1 Get Upstream Features
From the topology collection, we find that schematic node 1003 is upstream
of schematic link 4003
Figure 42 Accessing the Topology Collection
2 Get Upstream Values
From the Value Collection, we find that schematic node 1003 has a value to
pass of 3
Figure 43 Accessing the Value Collection
3 Process Upstream and Incremental Values
The appropriate processor for this feature is identified by noting that
this is a Type 2 schematic link, and that the process to be called is a
receive process Once the processor is identified, it is called to perform
the receive process
The resulting value from the receive process is stored in the attribute
table for the current feature, in the total value field if supplied
4 Process Value to Pass Downstream
The appropriate pass processor is called for this feature, given that this
is a Type 2 schematic link
5 Update Value Collection
The Value Collection for the current feature is updated, so that the entry
associated with this feature contains the value that this feature will pass
to the next downstream feature
The resulting value from the pass
process is stored in the attribute table
for the current feature, in the passed value field if supplied
Figure 44 shows a summary of one iteration of the process loop
Figure 44 Summary of Single Iteration in the Process Loop
43 Implementation with ArcToolbox
The implementation of this procedure in ArcToolbox requires the following
components:
ProcessSchematic - Script tool within an ArcGIS 90 toolbox
ProcSchematicvbs - Script written in VBScript on disk, referenced
by Script tool
MBSchematicdll - DLL written in VB that sorts the schematic
features and handles the calling of process DLLs
Process DLLs - zero or more DLLs that may be called to process
schematic features
Both scripts and DLLs are used in this research The majority of
processing in the methodology described above occurs within a DLL The
script is required to provide a bridge between ArcToolbox and the DLL, as
ArcToolbox script tools may only be linked to a script, and not a DLL
Thus, the interface provided by the ArcToolbox script tool manages the
input and output data, the DLL performs the processing work, and the script
serves as the go-between
Figure 45
Implementation of Methodology Using Scripts and DLLs
431 ProcessSchematic Script Tool
The ProcessSchematic script tool was created in a custom toolbox for ArcGIS
90 This tool is linked to the script ProcSchematicvbs, and passes the
following parameters to that script:
Schematic link feature class
Incremental value field in schematic link feature class read only
Total value field in schematic link feature class write only
Passed value field in the schematic link feature class write only
Schematic node feature class
Incremental value field in schematic node feature class read only
Total value field in schematic node feature class write only
Passed value field in the schematic node feature class write only
List of processing ops for the processing ops
List of source types for the processing ops
List of feature types for the processing ops
List of behavior types for the processing ops
Recall that the tool reads information from the incremental value fields,
and if specified, writes information to the total and passed value fields
Thus, the values in the incremental value fields are not altered by the
tool Also, the
tool reads no information from the total or value fields
It simply overwrites any existing information in those fields with new
information calculated while processing the schematic network
Figure 46a Feature and Op Inputs for ProcessSchematic Script Tool
Figure 46b Processing Op Descriptors for ProcessSchematic Script Tool
The classes in the DLLs that will perform advanced processing are specified
in the Processing Ops list To specify a processing op, the name of the
DLL is given, followed by a period, then followed by the name of the class
in the DLL that will do the processing In Figure 45a, the name of the
DLL is WaterQualityProcessors, and the name of the class in the DLL is
ClsDecay Note that this DLL must be registered on the computer in order
for the script to locate it
Each class in a DLL that will serve as a processing op must contain a
public function with the following signature:
Public Function ProcessValspRow As IRow, colVals As Collection As Double
The function must be called ProcessVals, and it must have the two
arguments of type IRow and Collection The first argument represents the
schematic feature that is to be processed The second argument is a
Visual
Basic Collection object that stores the values that are to be processed for
this schematic feature Each object in the Collection is an array
representing a value from an upstream and information needed to obtain that
upstream feature The first value in the array at the lowest index is
the value from the upstream feature The second value is the name of the
feature class to which that upstream feature belongs The third value is
the ObjectID of that upstream feature The function must return a value of
type Double
Each processing op must be associated with a specific source type, feature
type, and behavior in the script tool The first entry in the list of
processing ops corresponds to the first entry in the list of source types,
the first entry in the list of feature types, and the first entry in the
list of behavior types The second entry in the list of processing ops
corresponds to the second entry in the list of source types, and so on
Thus, the number of entries in the lists of source types, feature types,
and behavior types much match the number of entries in the list of
processing ops
The feature type defines whether the processing op is associated with
schematic
links or schematic nodes The source type defines the type of
schematic node indicated by SrcType field or schematic link indicated by
LinkType field that the processing op is associated with Finally,
behavior type defines whether the processing op is associated with
receiving behavior or passing behavior Thus, each processing op is only
used in a very specific instance For example, an op that decays loads
might only be used with schematic links of Type 2 and values are being
passed from a schematic link to the next downstream feature
If no processing ops are given for a combination of feature type, source
type, and behavior passing/receiving, then the default behavior is a
simple accumulation for receiving operations, and passing the total value
without changing the value for passing operations
The script tool also receives two parameters from the script:
Success: Boolean - True if operation was successful
Abort: Boolean - True if operation failed or was canceled
The two parameters allow the script tool to be chained together in a
sequence with other tools in an ArcToolbox model They do not affect the
execution of the script
432 ProcSchematic Script
This
VBScript script takes the inputs from the ProcessSchematic script tool
and converts them into a format that the MBSchematic DLL can recognize
The script also creates an instance of clsProcessSchematic, a class from
the MBSchematic DLL that performs most of the work in processing the
schematic network The script calls the ProcessSchematic function from
clsProcessSchematic, and feeds the class the parameters from the script
tool When the class is finished, the script determines if the operation
was successful, and sends the appropriate information Success or Abort
back to the script tool
433 MBSchematic DLL
This DLL performs most of the work outlined in this methodology, including
data preparation and control of the process loop The DLL contains a class
called clsProcessSchematic with a function called ProcessSchematic that may
be called from a script The function accepts inputs about the schematic
network and the processing ops The MBSchematic DLL controls the
instantiation of each of the processing ops specified in the script tool,
and determines when each op is called based on the other script tool
parameters After sorting the features, the DLL loops through each
feature
If a feature meets the criteria for calling a specific op, the
DLL passes that feature and the appropriate values to that op for
processing
The MBSchematic DLL also handles the writing of data ie, the values in
the Total Value field to the geodatabase However, because each
processing op receives an IRow object as one of the parameters, the
processing ops also have the ability to write values to the geodatabase, if
such behavior is necessary
434 Processing Ops
Zero or more processing ops may be used to process the schematic network
The ops are specified in the script tool, along with the conditions for
their use ie, source type, feature type, and behavior type Each op is
specified by giving the DLL name, followed by a period, and then followed
by the name of the class in the DLL that will perform the operation For
example, a DLL called WaterQualityProcessors with a class called ClsDecay
would be specified as WaterQualityProcessorsClsDecay
Each class that will serve as a processing op must have a public function
with the following signature:
Public Function ProcessValspRow As IRow, colVals As Collection As Double
Following this structure gives the user the ability to create
as many
processing ops as desired The MBSchematic DLL, which handles
instantiating and calling the ops are the correct time, does not know or
care how the processing ops do their work MBSchematic simply passes the
ops some information, and expects some information in return The
processing op could be as simple or as complex as needed
More information on the arguments of the ProcessVals function and how to
create a processing op is available in the appendix
5 Results
The methodology presented in this paper was applied to an Arc Hydro dataset
for Galveston Bay in Texas The dataset includes Watersheds with drainage
area in square km and bacteria loadings in cfu/yr Watersheds are related
to their outlet HydroJunctions through a JunctionID-HydroID relationship
HydroJunctions are related to their next downstream HydroJunction through a
NextDownID-HydroID relationship
Figure 51 Arc Hydro Dataset for Galveston Bay
Galveston Bay is located on the Gulf of Mexico Thus, because this dataset
is a coastal dataset, some of the network edges and watersheds are not
connected directly to the main stream network The main stream network
flows from the northwest part of the basin towards
the southeast
A schematic network was built from the Watersheds and HydroJunctions In
addition to the Arc Hydro attributes, other attributes were added to the
schematic features to support calculation of drainage area and decayed
loads on those features The schematic features have the following
attribute structure
Schematic node SchemaNode
HydroID - Unique identifier
FeatureID - HydroID of feature from which the Schematic node was
created
SrcType - Type 1 for Watershed node, Type 2 for HydroJunction node
IncArea - Incremental drainage area sq km
TotArea - Total drainage area sq km
IncLoad - Incremental bacterial load cfu/yr
TotLoad - Total bacterial load cfu/yr
Schematic link SchemaLink
HydroID - Unique identifier
FromNodeID - HydroID of from Schematic node
ToNodeID - HydroID of to Schematic node
LinkType - Type 1 for Watershed-HydroJunction link, Type 2 for
HydroJunction-HydroJunction link
IncArea - Incremental drainage area sq km
TotArea - Total drainage area sq km
IncLoad - Incremental bacterial load cfu/yr
TotLoad - Total bacterial load cfu/yr
TravelTime_day - Travel time along the
link days
DecayConst_day - Decay constant 1/day used for decaying bacterial
loads
Figure 52 Schematic Network for Galveston Bay
Incremental drainage area and bacterial loading were calculated for the
Type 1 Schematic nodes using the association between FeatureID on Schematic
node and HydroID on Watershed The tables were joined, and fields
calculated using the Field Calculator in ArcMap
Figure 53 Calculation of Incremental Drainage Area for Schematic node
Figure 54 Resulting Attribute Table for Schematic node after Field
Calculation
Drainage Area
The ProcessSchematic tool was run to calculate drainage area for the
schematic features No processing ops were specified, because only simple
accumulation and passing behavior was required to calculate the total
drainage area for each feature The script tool inputs for this
calculation are shown in Figure 45
Figure 55 ProcessSchematic Inputs for Drainage Area Calculation
Bacterial Load
The ProcessSchematic tool was run again to calculate bacterial load
WaterQualityProcessorsClsDecay was specified as a processing op for
schematic links of both Type 1 and Type 2 source types and passing
behavior ClsDecay
decays loads according to the formula:
P Po e-kt
Where:
P Decayed load cfu/yr
Po Initial Load cfu/yr
k Decay constant 1/day
t Travel time day
The travel time and decay constant are specified as attributes on the
schematic links These attributes are read directly by ClsDecay The rest
of the script tool inputs for this calculation are shown in Figure 46
Figure 56 ProcessSchematic Inputs for Bacterial Load Calculation
The results from these operations show correct calculations of drainage
area and bacterial loads on the schematic features
Figure 57 Attributes of Schematic node after Schematic Network Processing
Figure 58 Schematic links Showing Total Drainage Area
Figure 58 shows the schematic links with a legend defined by the magnitude
of the total drainage area for each link Schematic links with a larger
drainage area will be drawn with a thicker line From the figure, it is
clear that schematic links further downstream possess a larger drainage
area than those upstream
6 Conclusions
With the capabilities in ArcToolbox for ArcGIS 90, an even tighter
integration between Arc Hydro and hydrologic models can be engineered
The
simple examples illustrated in this research could be extended to allow for
more complex modeling involving time series and processing ops hooked onto
simulation routines from models such as HEC-HMS
The methodology could also be extended to include more than the current
maximum of two source feature classes, so that any number of feature
classes participating in a reactive network could be processed
Because the ProcessSchematic script tool is designed to operate in a chain
with other tools in Model Builder, sophisticated models could be assembled
to model various scenarios with the push of a button
Appendix A: Tutorials
A1 How to Create a Script Tool
Script tools can be created in ArcToolbox to perform tasks in addition to
those provided with standard ArcToolbox tools Script tools must be
associated with a script on disk The code for the script is not located
within the script tool Rather, the script tool gathers the geospatial
inputs and passes them to the script for processing, while typically
receiving some kind of output from the script when processing has been
completed
Scripts may be written in Python, VBScript, or other scripting languages
For this example,
well create a simple script in VBScript that reads in a
name from an ArcToolbox script tool and returns a message box that says,
theName says Hello The script will pass the name that it received from
the script tool, back to the script tool in case the script is
participating in model that requires further use of the name parameter
The first step is to create a script Once the script has been created, it
may be associated with a script tool in ArcToolbox
To create a script:
1 Open Notepad
2 Type or better yet, cut and paste the following lines of code
This is a comment
This script was made by your name here
Create GeoProcessing object
This object interacts with the ArcToolbox script tool
Set gp WScriptCreateObjectesriCoreGPDispatch1
Retrieve the input parameters
This is how we get parameters from the script tool
TheName WScriptargumentsItem0 arguments are indexed at 0
Do some work in this case, just say hello
MsgBox TheName says hello
Send output back to the script tool
In this case, we just send the same name back
gpSetParameterAsText 1, TheName
3 Save the file as c:\temp\helloworldvbs
Script tools are located in toolboxes
To create a new script tool:
1 Open ArcCatalog
2 Well create a new toolbox for this example Right click in the
directory where the toolbox is to be created
3 Click NewToolbox, and give the toolbox a name Well use MyToolbox
as the name in this example
Figure A11 Creating a New Toolbox
4 Right click the toolbox, then click NewScript Tool
5 Call the script tool HelloWorld Note that no spaces are allowed in
the name of the tool You may include spaces in the label for the
tool You may also type in a Description this appears when you click
Show Help when you open a tool and set other options
Figure A12 Naming a Script Tool
6 Click Next to continue
7 Here you are asked for the name of the script to associate with this
script tool Navigate to c:\temp\helloworldvbs and click Open
Figure A13 Associating a Script with a Script Tool
8 Click Next to continue
9 In this window you specify parameters for the tool Place the mouse
cursor over the first empty space under Display Name and left click
10 Type Name and then select String as the Data Type
11 Click on the next empty space under Display Name, and type Output
Name Set
this parameters Data Type to String
12 In the Parameter Properties for Output Name, change the Type to
Derived, and the Direction to Output
Figure A14 Defining Parameters for a Script Tool
13 Click Finish to complete this tool
To run the script tool:
14 Navigate to MyToolbox
15 Expand MyToolbox so that the Hello World script tool is visible
Figure A15 Hello World Script Tool in MyToolbox
16 Double click the script tool to run it
17 In the Name text box, type in your name
Figure A16 Inputting Parameters for Running a Script Tool
18 Click OK After a moment, you will see a message box similar to the
one below
Figure A17 Message Box from helloworldvbs
19 Click OK to close the message box The script tool has now finished
running
Scripts tools can be very simple, like the example shown here, and they can
also be very complicated You can view the source code for
ProcSchematicvbs to see a more complicated example of scripting
A2 How to Create a Processing Op
The methodology presented in this research allows the end user to create
processing ops for use with the ProcessSchematic tool This tutorial shows
how to create a
processing op with Visual Basic
A processing op is simply a class in a DLL with a public function with the
following signature:
Public Function ProcessValspRow As IRow, colVals As Collection As Double
The function must be called ProcessVals, and it must have the two
arguments of type IRow and Collection The first argument represents the
schematic feature that is to be processed
The second argument is a Visual Basic Collection object that stores the
values that are to be processed for this schematic feature Each object in
the Collection is an array representing a value from an upstream feature
or the incremental value from the current feature and information needed
to obtain that upstream feature The first value in the array at the
lowest index is the value from the upstream feature The second value is
the name of the feature class to which that upstream feature belongs The
third value is the ObjectID of that upstream feature The function must
return a value of type Double
These are the only restrictions for the op Otherwise, the op can process
the inputs in as simple or complex a fashion as required
Figure A21 shows the contents of an example colVals object,
for
hypothetical SchemeNode with ObjectID 123 The collection contains three
objects Each of these objects is an array composed of value, feature
class name, ObjectID Note that because SchemaNode 123 possesses an
incremental value, the first object in colVals represents that node and its
value The second and third objects in the collection represent values
coming in from two upstream SchemaLinks
In some cases, a custom processing op may need to distinguish between
upstream values and the incremental value for a feature Because the pRow
object of the current feature is also passed to the processing op in the
ProcessVals function, the op can compare the feature class name and
ObjectID from any array in colVals to the feature class name and ObjectID
of the incoming pRow Note that the array representing the incremental
value for a feature may or may not be the first Item in the colVals
collections A processing op can check the name and ObjectID in each array
to determine which, if any, of the arrays originated from the pRow object
Figure A21 Anatomy of colVals Collection The first Item represents an
incremental value, with the second and third Items represent
incoming
upstream values
In this example, we will create an op that returns the sum of all values
given to it
To create a processing op:
1 Open Microsoft Visual Studio
2 Create a new ActiveX DLL project
Figure A22 Creating a New ActiveX DLL
3 Rename the default class to clsAddition
Figure A23 Renaming the Default Class
4 In the Project menu, click Project1 Properties
5 Change the Project Name to ModelBuilderOps and click OK
6 In the Project menu, click References
7 Place a check by the ESRI object library to add a reference to this
library and click OK The ESRI object library is necessary to work
with the IRow object passed to the ProcessVals function
Figure A24 Setting a Reference to the ESRI Object Library
8 Type or Copy/Paste the following into the code for clsAddition
This code does not make use of the IRow argument However, a more
complicated op could read additional parameters from pRow if
necessary
Public Function ProcessValspRow As IRow, colVals As Collection As Double
Dim i As Long
Dim j As Integer
Dim vArray As Variant
ProcessVals 0
For i 1 To colValsCount
Get the array at this index
position in the collection
vArray colValsItemi
Get the lowest index for this array
j LBoundvArray
Get the value from the array
Note: the value is at the first position in the array
ProcessVals ProcessVals vArrayj
Next i
End Function
9 From the File menu, click Make ModelBuilderOpsdll Specify a
location for the DLL and click OK
10 Make sure the DLL is registered on your machine See your system
administrator if you are unsure about how to register a DLL
The new processing op is now ready to go To use this op, associate it
with the Receive behavior type in the ProcessSchematic tool in ArcToolbox
when you run the tool
Source:gamasutra.com
