RivEX

Summary :: Usage :: Parameters :: Outputs :: Warnings :: Limitations :: Code sample

Summary

Adds a new text field identifying the main channel in each catchment. Optionally exports the identified channel to a separate dataset.

Usage

Requirement for using this tool:

To use this tool you must have attributed the network with:

• Catchment ID
• Distance to network mouth 

This tool adds a new text field called MainChan which identifies polylines as the main channel. If the field exists it creates a new field with a simple numeric suffix (e.g MainChan_1).

Polylines are flagged with a "Y" or a "N" where a "Y" for Yes indicates the polyline is part of the main channel. The main channel is defined as the route from the furthest point upstream to the catchment mouth. RivEX determines the source furthest away from the catchment mouth and tracks down towards the mouth flagging polylines as "Y" for main channel, all other polylines are flagged with a "N".

When RivEX encounters a divergence (think of this as the top end of a loop in the network) it chooses the side that it encounters according to row order in the Feature Class, this can mean RivEX flags the incorrect side of loops. RivEX has no other information to decide which is the appropriate side of a loop to flag as main channel. Whilst RivEX guarantees a single threaded route from source to mouth it can potentially follow incorrect sides of loops. This issue does not occur with river networks derived from DEM's as they typically generate networks without loops.

A catchment is defined as all polylines flowing to a mouth node. Once the source polyline has been identified RivEX traverses downstream from the source to the mouth of the catchment labelling the polylines along the route as "main channel" polylines. As the algorithm searches downstream if it encounters a bifurcation which could potentially be a "short-circuit" across catchments it will always chooses a polyline that is labelled with the currently processing catchment ID.

If the check box Export Main Channel is ticked, RivEX creates a new Feature Class where the polylines flagged as main channel are dissolved into single routes tagged with their catchment ID. The name of this Feature Class is the river layer name with _MainChannel appended and it is stored in fGDB_Network.gdb in the RivEX Outputs folder. Any ZM values in the source network are dropped during the dissolve process.

During the process of identifying the main channel it's possible that poor topology causes RivEX to loop, if this happens the To-Node that causes the network to loop is recorded in the Error log which is loaded into the map and optionally a relate built between the error log table and the network. You would typically review your network, correct the flow direction and rebuild topology. Upon re-running this tool it is quite possible for it to identify further errors downstream as your correction would have allowed the algorithm to progress instead of being trapped in a loop.

Parameters

Outputs

An updated river network with a new text field recording if the polyline is considered part of the main channel within the catchment. Values in this field are only ever Y or N. If the user has selected the optional task of exporting the main channel then a Feature Class is created using the river layer name with _MainChannel appended and it is stored in fGDB_Network.gdb in the RivEX Outputs folder. Any ZM values in the source network are dropped during the dissolve process.

Any topological errors encountered during processing are written to a stand alone table named tblMainChannelFailedToNodeIDs. The table is created in the RivEX workspace folder and stored in the File GeoDatabase found in ..\RivEX_Workspace\ErrorLogs\fGDB_RivEXErrorLogs.gdb

Advice on the structure of the error log table and how it can be used is found within this section of the manual. Take note of the warning if you plan to construct a model using the error log output in subsequent processing.

Warnings

Be aware if your network includes drains or canals that "short-circuit" the dendritic pattern of rivers then you will get incorrect main channels.  This is because the polylines may have been identified as one catchment yet the physical order they are stored in your FeatureClass will influence the identification of the main route.

With the release of ArcGIS Pro 3.2.1 a switch control appears on parameters that accept tables\feature classes, do not interact with it! More advice here.

Limitations

1. This tool uses catchment ID encoded into the network to optimise it search; if there is unusual encoding (e.g. complex deltaic systems can cause the catchment encoding tool to erroneously number the polylines) then this tool could potentially become trapped in a loop. RivEX is able to capture this scenario and abort reporting the problem polyline ID number. You would typically need to review your network by colour coding catchment ID or symbolize flow direction to understand the issue and fix it (you most likely need to flip the direction of the polyline).
2. River network must not be a compressed dataset.

Code sample

A minimum code example showing how to call this tool in a python script. This can be run in console or your preferred IDE. If you right click on the tool in the RivEX toolbox and select properties you can view parameter order.

import arcpy

# Import RivEX toolbox
arcpy.ImportToolbox(r"C:\RivEX_ArcPro\RivEX.atbx")

try:
    # Input river Feature Class
    fc = r"C:\Temp\ORN\ORN.gdb\ORN"
    
    # Run RivEX tool, export main channel polylines is set to True,
    # adding table to map and creating a relate are set to false
    res = arcpy.scrAttrMainChannel_RivEX(fc, True, False, False,)
    
    # Show output Feature Class name which is same as input 
    updatedfc = res.getOutput(0)
    mainChanfc = res.getOutput(2)
    print(updatedfc)
    print(mainChanfc)
except arcpy.ExecuteError:
    print("FAILED to add Main Channel field")