Segment routes

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

Summary

This tool takes routes (a single polyline) and segments them into user specified lengths. For example you may want to segment a set of 10Km routes into 500m segments.

The segments could represent survey sites or linear sampling units. Segmenting data can help you plan walk over surveys or provide a sampling framework. The extracted segment points are associated with the segment they are built upon using an ID field so you can use the segment points in spatial analysis and relate the results back to the segment.

You can optionally extract, centroid, end points or points spaced along each segment.

Usage

This tool takes routes and segments them into the user specified length. A route is a single polyline. Do not make the mistake of thinking a sequence of polylines along the river network is a route.

A single polyline displayed in red, this is a valid route for the tool	Starting from the source the route is segmented into 500m reaches	Zoomed in section showing optional centroids extracted

RivEX provides several tools that can generate routes; the Link sites tool is a good example or the optional output of find sources or add main channel. You may have generated routes by dissolving the line segments that follow the main stem of a river. Where the routes come from are not important as long as they are in the same coordinate system as your river network and not multi-part.

If you have a set of routes selected then you can choose to process only those by tick on Process only selected routes.

Enter a segmentation length in metres (or feet); this value must be greater than zero and an integer.

The output of this tool is a table written to the File GeoDatabase 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.

Segments are encoded with a variety of attributes. Each segment is given a unique ID number, the ID number of the route it was built upon, a sequence ID, the start and end distance the segment is along the length of the route and a sinuosity value.

Attribute table of segmented data

An example of the attribute data for 500m generated segments.

If you have chosen to extract optional point data, then points have the following attributes: a unique point ID, the segment ID the point is built upon, its XY coordinates, the distance along the route that the point is and the route ID. If you have chosen spaced points then an additional field is created measuring the distance along the segment.

Sample of centroid data created by tool

An example of the attribute table of centroids extracted from the 500m segments.

Optional tasks

Flip direction of route before segmentation - The segmentation starts from the beginning of the route, in some cases this may not be desirable and you want the segmentation to start from the other end. For example your routes were built in a source to sea direction but you want to segment from the sea to source direction. Tick this option on and RivEX will reverse the direction of the route before it starts segmenting. The original route direction is unaltered.

Drop incomplete end segment - It is unlikely that your desired segmentation length divides equally into the route length, this would leave a segment shorter than your segmentation length. Tick this option on and RivEX excludes the final shorter segment from the output, thus all segments in your output dataset will be the segmentation length.

Extract points along each segment - This optional processing step will extract point data from your segments, useful for further sampling or simply to map with display of data. There are four options:

None - Default option. No point data will be created

Centroid - The centroid of each segment is extracted and stored

End points - The end points of the segment are extracted and stored

Spaced - Points at a user specified distance are extracted from the segment and stored

If Spaced is chosen then the user must enter a spacing distance in metres (or feet). This value must be greater than zero and less than the segmentation length.

Add attribute index - Tick this on and RivEX will create an index for the Segment/point ID field in the output Tables, this will improve any query/join performance using this field.

Parameters

Name	Help	Data type
River Network	The river network. For best results the network should be within a File GeoDatabase	Feature Layer
Route layer	The route layer to be segmented. It must be in the same coordinate system as the river network and not contain multi-part geometries.	Feature Layer
Route ID field	A numeric field uniquely identifying the route polyline. This field must contain unique numbers and cannot be the ObjectID field.	Field
Process only selected routes	Controls if selections are honoured or cleared. If CHECKED and you have a subset of route features selected only these will be processed. If CHECKED and you have no route features selected then all features will be processed. If NOT CHECKED then RivEX will clear any existing selection on the route feature layer.	Boolean
Segment length (m or ft)	The length of segments you want to create; units can be in metres or feet but must be greater than zero and an integer.	Long
Output segment feature class name	The output table name for your segmented data. You do not have control over the location where this table is created, RivEX controls that, but you can decide its name. The table name must be a geodatabase compliant name, so must not have spaces, other unusual characters or start with a number. Output will be stored in fGDB_Sampling.gdb in the RivEX Workspace Output folder.	String
Flip direction of route before segmentation	Flips the direction of the route polyline before segmentation starts. This option does not alter the source route. CHECKED - The direction of the polyline is flipped. UNCHECKED (default) - Polyline remains in the direction it was built.	Boolean
Drop incomplete end segment	It is unlikely your chosen segmentation length divides equally into the route, resulting in an end segment shorter than the desired length. CHECKED - The short end segment is excluded from the output dataset. UNCHECKED (default) - The short end segment is retained in the output.	Boolean
Extract points along each segment	A choice option for optional extraction of point data along the segment. None - Default option. No point data will be created. Centroid - The centroid of each segment is extracted and stored. End points - The end points of the segment are extracted and stored. Spaced - Points at a user specified distance are extracted from the segment and stored.	String
Spaced distance (m or ft)	This parameter is only available if you have selected the Spaced option. You must provide a value greater than zero and be less than the segmentation length to be valid. For example you have set your segmentation length to be 250m and the spaced distance to be 50m; RivEX would generate for each segment a point along the segment at 0, 50, 100, 150, 200 & 250m.	Double
Output point feature class name	The output table name for your point data. You do not have control over the location where this table is created, RivEX controls that, but you can decide its name. The table name must be a geodatabase compliant name, so must not have spaces, other unusual characters or start with a number. Output will be stored in fGDB_Sampling.gdb in the RivEX Workspace Output folder.	String
Add an attribute index to output	Indicates if RivEX will create an attribute index for the site ID field in the output table. CHECKED - RivEX will attempt to add an index to the site ID field in the output table. UNCHECKED (default) - No index will be added to any output table. 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
Add Error Log Table to Map	If this is ticked (default) the error log table will be added to the map for your convenience if any errors were found.	Boolean
Build a Relate for Error Log	If this tick box is checked then the error log table must be loaded into the map and RivEX builds a standard relate between the Error Log table and the river network layer. You can use the relate to help you jump to and review the error.	Boolean

Outputs

The output table(s) can be given a name but you have no control over where it is stored, this would be in the file geodatabase in the output folder ..\RivEX_Workspace\Outputs\fGDB_Sampling.gdb.

The primary output table contains the following fields:

Field	Description
UniqueSegID	The unique segment ID
OrigRID	The ID of the route that the segment was built along
SequenceID	The number sequence of segments along its route
Start	The start distance for the segment
End	The end distance for the segment
Sinuosity	The sinuosity of the segment. Sinuosity is computed as length of segment line divide by its straight line distance of end points

The optional point table will have the following fields:

Field	Description
PointID	The unique ID assigned to point
UniqueSegID	The segment ID the point was constructed on
X	The X coordinate of point
Y	The Y coordinate of point
DistAlongRoute	The distance along the route the point is
OrigRID	The ID of the route that the segment was built along
DistAlongSegment	This field only exists if you have selected spaced point extraction and is the distance along the segment

If errors were generated then this tool can create a stand alone table named tblRouteErrors. The table is created in the RivEX workspace folder and stored in the File GeoDatabase found in ..\RivEX_Workspace\ErrorLogs\fGDB_RivEXErrorLogs.gdb. The error log will record routes that failed to segment.

Advice on the structure of the error log table and how it can be used is found within this section of the manual. Take note of the warning if you plan to construct a model using the error log output in subsequent processing.

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

Route layer must be in the same projected coordinate system as the river network.
Routes must be single part geometries

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:\Temp\ORN\ORN.gdb\ORN"

# Input route Feature Class
fcRoutes = r"C:\Temp\ORN\RivEX_Workspace\Outputs\fGDB_Network.gdb\ORN_MainChannel"

# Run RivEX tool to segment all routes into 500m segments and extract segment centroid
res = arcpy.scrSegmentRoutes_RivEX(fcRivers, fcRoutes, "RouteID", False, 500, "seg500", False, True, "Centroid", None, "seg500cent", True, False, False)

# Get segment Feature Class
fcSegments = res.getOutput(0)

# Get a count on number of segments created
res = arcpy.GetCount_management(fcSegments)
n = int(res.getOutput(0))
print("Number of segments created = " + str(n))
except arcpy.ExecuteError:
print("FAILED to segment routes")