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


Generate regularly spaced points across network.


Requirement for using this tool:

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

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. 

1Km spaced point example

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. 

500m spaced point example

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.

Spaced sampling points




Data type

River Network

The river network. For best results the network should be within a File GeoDatabase

Feature Layer


The distance you want to create spaced points across your network, you can choose units of Meters or Kilometres. Zero and negative numbers are invalid.

Linear Units

Output feature class name

The output Feature class name for your sampling point dataset. You do not have control over the location where this dataset is created, RivEX controls that, but you can decide its name. The Feature Class name must be a geodatabase compliant name, so must not have spaces, other unusual characters or start with a number.


Add an attribute index to output

Indicates if RivEX will create an attribute index for the sample ID field in the output layers

  • CHECKED - RivEX will attempt to add an index to the sample ID field in the output layer(s).

  • UNCHECKED (default) - No index will be added to any output layer(s).

If you plan to join or relate data then it is STRONGLY recommended you create attribute indices for the outputs; an index can significantly speed up query operations.



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:




A unique numeric ID number given to the sampling point.


The Polyline ID number the sampling point was generated upon.


The X coordinate of the sampling point.


The Y coordinate of the sampling point.


The length of the polyline being sampled. Units will be in the same as the network, typically in metres or feet.


The percentage length along the line the sampling point is. Measured from the FROM end of the polyline.


The distance along the line the sampling point is. Measured from the FROM end of the polyline.


The distance to the network mouth, this will be in the units specified in the spacing parameter.


The catchment ID the point is within (this is taken from the value encoded into the network).

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.


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.


  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

    # 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!")

Return to top of page