RivEX

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

Summary

Adds a new numeric field identifying the distance to source a polyline is in the river network.

Usage

Requirement for using this tool:

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

• Distance to mouth
• Source ID

This tool adds a new numeric field called Dist2Src which is the distance to source. If the field exists it creates a new field with a simple numeric suffix (e.g. Dist2Src_1). Recorded length will be in the units of the coordinate system, so this attribute is appropriate for datasets in feet or metres, datasets in decimal degrees are rejected.  The distance includes the length of the polyline being attributed so you can think of this as the distance to source starting at the TO-end of the polyline.

Any selection on the input layer is cleared and the tool processes all polylines in the river network.

If the source ID of the polyline is -1 then the output is set to -1 as -1 for the source ID indicates a source could not  be reliably identified.

This tool takes advantage of the attributes, source ID and distance to network mouth encoded into the network, to efficiently assign distance to source. Distance to source is computed as a difference between the source distance to network mouth and current polyline distance to network mouth. Like the distance to mouth tool, this tool is influenced by the presence of loops within the network, this is demonstrated in the image below. Lines are coloured by their source ID and the distance to source labelled. Note headwater channels are not zero distance they include the length of the polyline. Review the loop, the polyline downstream is 7.6Km which indicates the algorithm travelled down the left hand side of the loop (as you look at it).  As the distances are computed from the distance to network mouth any bias captured by distance to mouth will be inherited by the distance to source value. For example if you travel up the network from the mouth but follow the right hand side loop then immediately upstream of the loop you introduce a 0.3Km disparity into any calculation.

Network colour code by source ID and labelled with distance to source

To ensure a network is free from these disparities you could simplify the network into a single threaded network as described in this worked example.

Simple loops around an island often have very similar branch length thus the bias is trivial.

Parameters

Outputs

An updated river network with a new numeric field recording the distance to source for each polyline within the network, units are in the coordinate system of the dataset.

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

1. This tool will reject river networks that do not have linear units. Networks in latitude/longitude will be rejected.
2. Any selection on the input layer is cleared and then the tool processes all polylines in the river network.
3. 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
    res = arcpy.scrAttrDistanceToSource_RivEX(fc)
    
    # 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 source")