Sample every polyline

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

Summary

Generates one or more sampling points along every polyline in the network.

Usage

This tool generates a new point dataset sampling each individual polyline within the network. If a selection exists, checking on the optional tick box allows you to process a subset of your network.

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.

You can sample each polyline in the network in one of two ways:

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.

If using the Regular sample strategy then values must be between 0 and 100%, no duplicate values are allowed and values are the percentage length along the line you want a sampling point created. You can add multiple values as comma separated values. NO SPACES ARE ALLOWED IF SEPARATING WITH COMMAS. For example if you entered 25,50,75 then a sampling point is created at 25%, 50% and 75% along the length of the polyline, thus creating 3 points per polyline.

If using the Random sample strategy then the polyline is sampled randomly along its length the number of times you specify. This value must be an integer and be equal to or greater than 1. You also have the option to avoid sampling the same location (this is default), but if unchecked this could potentially cause RivEX to create stacked points purely by chance.

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

Every polyline sampling point symbology

Parameters

Name	Help	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.	Boolean
Sampling strategy	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.	String
Number of times to randomly sample polyline	This parameter is only valid if strategy is set to RANDOMLY. This is the number of times you want to randomly sample along the length of the line. This value must be an integer and be equal to or greater than 1.	Long
Percentage along polyline	This parameter is only valid if strategy is set to REGULAR. Values must be between 0 and 100%. No duplicate values are allowed. Values are the percentage length along the line you want a sampling point created. You can add multiple values as comma separated values. For example if you entered 25,50,75 then a sampling point is created at 25%, 50% and 75% along the length of the polyline, thus creating 3 points per polyline.	String
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.	Boolean
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.	String
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.	Boolean

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

Field	Description
SampleID	A unique numeric ID number given to the sampling point.
PolylineID	The Polyline ID number the sampling point was generated upon.
X_Coord	The X coordinate of the sampling point.
Y_Coord	The Y coordinate of the sampling point.
LineLength	The length of the polyline being sampled. Units will be in the same as the network, typically in metres or feet.
Per_Along	The percentage length along the line the sampling point is. Measured from the FROM end of the polyline.
Dist_Along	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.

Warnings

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.

Limitations

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.

See warning above.

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 every polyline at locations 50% and 75% along length of line, add an attribute index.

# 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.scrSampleEveryPolyline_RivEX(fcRivers, False, "Regular", "#", "50,75", True, "fcSample", True)

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