Add Distance to Mouth
Summary :: Usage :: Parameters :: Outputs :: Warnings :: Limitations :: Code sample
Summary
Adds a new numeric field identifying the distance to mouth of a polyline in the river network.
Usage
This tool adds a new numeric field called Dist2Mth which is the distance to mouth. If the field exists it creates a new field with a simple numeric suffix (e.g. Dist2Mth_1). A mouth is the node that the entire upstream network drains into, this is typically the sea. Mouths can exist inland far from the sea, these could be sink holes in Karst regions or more often drainage points where the river connects into an artificial channel such as a canal.
Recorded length will be in the units of the coordinate system, so this attribute is appropriate for datasets in feet or metres. The distance includes the length of the polyline being attributed so you can think of this as a distance starting at the FROM-end of the polyline. In the image below, red numbers indicate the length of the polyline and black numbers are the distances from the network mouth encoded by RivEX.
Notice upstream of the loop the distance to mouth is 6.5Km and not 7Km. The reason for this is when the algorithm traverses the network in a mouth to source direction the sequence it visits polylines is dictated by the order of records in the FeatureClass table. In the example above it just happens to have gone up the right hand side of the loop first. When the algorithm starts to traverse up the left hand side it detects that the upstream polylines have already been visited and stops searching upstream, to avoid duplication.
No consistent path through braiding sections can be guaranteed as each dataset is uniquely digitised.
Examine the image below for a situation that can often occur within river networks. Here we have two catchments (numbered 5 & 6) that are joined to each other by a link (indicated by the arrow). Depending upon the orientation of the link most of the polylines will fall within one catchment. This would mean that most polylines would have a distance to mouth value linked to a network mouth which is not part of the same catchment.
Removing the link completely or breaking its topological connection at one of its nodes will ensure the rest of the polylines are attributed correctly with distance to mouth values.
Another issue that must be understood is multiple mouths within a catchment. The assumption behind the algorithm logic is that the network drains to single mouth at the coast. It is possible to get mouths within the catchment. These could be channels flowing into a canal or sink holes with a karst region. RivEX does not distinguish between mouths within catchments or at coastal limits. The image below shows how polylines are labelled incorrectly and flow to Mouth "A", this would influence any site analysis you are carrying out that requires distance to network mouth.
The problem of multiple mouths within a catchment can be overcome by using the force longest route option (which is default, but can be turned off). It can significantly influence the output, click here for more information.
If a circular mouth polyline exists, think of this as a single polyline that loops, then these are skipped and given a distance of -1.
Parameters
|
Name |
Help |
Data type |
|
River Network |
The river network. For best results the network should be within a File GeoDatabase |
Feature Layer |
|
Force longest Route |
Some algorithms that RivEX use are sensitive to the digitising sequence of the network (i.e. the row order of the Feature Class). This can generate unusual attribution with catchments that have multiple mouths. Multiple mouths can occur in karst regions or as channels feeding into man made water courses. These are legitimate parts of the network yet they can significantly alter the output by RivEX. The force longest route option changes the behaviour of the algorithm and will influence any catchments with multiple mouths. This option is turned on as default but you you can choose to ignore it by simply un-ticking the check box. |
Boolean |
Outputs
An updated river network with a new numeric field recording the distance from network mouth in the units of the coordinate system.
Warnings
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
- This tool will reject river networks that do not have linear units. Networks in latitude/longitude will be rejected.
- Any selection on the input layer is cleared and then the tool processes all polylines in the river network.
- 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, Force Longest route is set to True
res = arcpy.scrAttrDistanceToMouth_RivEX(fc, True)
# Show output Feature Class name which is same as input
updatedfc = res.getOutput(0)
print(updatedfc)
except arcpy.ExecuteError:
print("FAILED to add Distance to mouth")
