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


Generate random points across the river network.


This tool generates a new point dataset sampling randomly across the network. If a selection exists and appropriate check box ticked then only the selected polylines are sampled, these could be for example a set of polylines making up a sub-catchment.

You have a variety of options that can influence (bias) the selection process and it is important that you understand these. Click here to review these options. Avoid sampling nodes is ticked on as default.  If your network is in units of feet and you have set the exclusion zone distance, then RivEX will convert the metres value into feet.

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

Random sampling




Data type

River Network

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

Feature Layer

Sample only selected polylines

Controls if selections are honoured or cleared:

  • If CHECKED and you have a subset of polylines selected only these will be sampled.

  • If CHECKED and you have no polylines selected then all polylines will be sampled.

  • If NOT CHECKED then RivEX will clear any existing selection on the network and all polylines will be sampled.


Number of sample points to create

Controls the sampling strategy applied to each polyline:

  • REGULAR - Allows you to sample at user specified distances as percentages along the length of the polyline.

  • RANDOMLY - Samples the polyline in random locations along its length a user specified number of times.


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.


Avoid sampling same location on polyline

Controls if RANDOM sampling is allowed to create points at the same location:

  • If CHECKED, RivEX will not generate stacked points, each point will be a unique location along the length of the polyline, this is default.

  • If NOT CHECKED, RivEX may (by chance) randomly sample the same location along the length of the polyline and this will lead to stacked sampling points.


Avoid nodes

Controls if RivEX is allowed to to sample at the ends (nodes) of the polyline:

  • If CHECKED RivEX will avoid creating points at the ends of the polylines. This is Default.

  • If NOT CHECKED then RivEX could potentially create, by chance, points at the ends of the polylines.

It is recommended that you CHECK this option as it avoids sampling points being created a tributary junctions which themselves cause subsequent issues.


Apply exclusion zone (m)

If a value greater than zero is entered, then this applies an exclusion zone around the point as it is generated. If other existing sampling points are found within the zone then the sampling point is rejected and RivEX attempts to create another. This process is repeated up to 200 times before RivEX bails out.

Be aware creating large exclusion zones on small networks will quickly exhaust sampling space and RivEX will fail to create the required number of points.


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 point dataset will contain the following 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.

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.


RivEX will attempt to locate a random point but if it fails it will try up to 200 times.  If after the 200th attempt it is still unsuccessful it will bail out.  This scenario can occur when for example you have included an exclusion zone around each point, but this was set so large that no other points could be placed on the same network.

A limitation of this tool run in a script is that it only accepts feature classes for the river layer. It will fail with inputs as layers with/without selections. If you need to process data with selections you need to use the tool directly from the toolbox or python console, more details here.

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.

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.

See warning above.

import arcpy

# Import RivEX toolbox

    # Input river Feature Class
    fcRivers = r"C:\Scratch\ORN\data.gdb\ORN"

    # Run RivEX tool, create 100 sample points across network

    # WARNING This tool will fail if river data is a layer with a selection! If you need to pass in selections use tool directly from toolbox
    res = arcpy.scrSampleRandomNetwork_RivEX(fcRivers, False, 100, "fcSample_100", False, True, "#", False)

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

    # Verify number of sampling points created
    res = arcpy.GetCount_management(fcSample)
    n = int(res.getOutput(0))
    print(str(n) + " sample points created")

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

Return to top of page