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.
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:
|
Boolean |
Sampling strategy |
Controls the sampling strategy applied to each polyline:
|
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:
|
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
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.
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!")