RivEX

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

Summary

Generate regularly spaced points across network.

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 generates a new point dataset sampling at a regularly distance across the network. Spacing starts from the mouth of a catchment and builds points along the network at a user defined distance. No points are created at the river mouth as this is the mouth node. 

If a selection exists, this is cleared before the tool runs.

If the river network was not quality controlled using RivEX tools you may have null geometry or other topological errors. This tool aborts on null geometry. If this happens you need to run the quality control tool Identify NULL Polylines and resolve the errors before you can use this tool.  Once sampling has completed, RivEX does a final quality control check looking for stacked points. If it finds any it returns a RivEX 059 error.   For this to occur you must have overlapping polylines which are topological errors in your river network.  You can use the Find Identical tool searching on the X_Coord and Y_Coord fields to locate the stacked points which will identify the overlapping polylines.

Points are created along the network separated by the user defined distance until RivEX reaches the headwater stream polylines.  RivEX stops when it is unable to create a new upstream point at the user defined distance.  In the image below the user has set the spacing distance to 1Km.  The sections of river highlighted in green are less than 1Km from the source, thus RivEX stops generating points as 1Km upstream from the last point created would be off the network. 

If your network contains loops or is a multi-threading channel then you will encounter the problem as described below. In the image, 500m spaced points were created along a network. Point 288 is 5Km from the river mouth, yet the next point upstream (280) is also 5Km from the river mouth!  The loop in the network means that one side of the loop is shorter than the other.  When RivEX was used to attribute polylines with distance to river mouth it traversed the side with point 279 first.  It did this because this is the order of the rows in the dataset. 

The only way to avoid the above situation is to simplify your network by reducing loops within your network to a single channel. Thus in the example above you will probably want to remove polyline 279 as this is an artificial channel (e.g. an old mill race) and polylines 287 and 288 constitute the original channel.

If the tool was run from within ArcPro the output Feature Class, if successfully created, will be added to the map symbolized as black points.

Parameters

Outputs

The output is written to a File GeoDatabase called fGDB_Sampling.gdb which is stored in the Outputs folder in the RivEX Workspace. You can control the name of the Feature Class but not its location. The output name must be a valid file geodatabase name.The output will contain the following RivEX fields:

If you have selected the optional processing task, add attribute index, then the SampleID field in the output dataset will be indexed. An index can significantly speed up query operations such as joins or relates.

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. The RivEX_Workspace folder must exist before using this tool, you use the Create a RivEX workspace tool to create the workspace.

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
    fcRivers = r"C:\Scratch\ORN\data.gdb\ORN"

    # Run RivEX tool, sample entire network every 10 Km
    res = arcpy.scrSampleSpacedPoints_RivEX(fcRivers, "10 Kilometers", "fcSample_10K_spaced", False)

    # The sampling point Feature Class, a derived output
    fcSample = res.getOutput(0)

    # Count how many sampling points were created
    res = arcpy.GetCount_management(fcSample)
    n = int(res.getOutput(0))
    print(str(n) + " sampling points were created in total")

except arcpy.ExecuteError:
    print("FAILED to sample network!")