Split Line By Match—Help

Summary
Illustration
Usage
Syntax
Code sample
Environments
Licensing information

Summary

Splits input features based on matching relationships to obtain better corresponding line segmentation.

When dealing with line features in two different data sets—for example, city roads and state roads—having features in 1:1 rather than many-to-many (m:n) matching relationships will aid conflation tasks, such as attribute transfer from one source to the other. This tool is intended to help turn the m:n matches into more 1:1 matches.

The input features and the matched features must be prematched by one of the feature matching based conflation tools, such as Detect Feature Changes, with a match table produced. The matching relationships recorded in the match table are between source and target features.

For each match group, the tool splits the input features based on the node conditions in the matched features. A node can be a dangle end of a line, a pseudo node between two lines, or a junction of multiple lines. For example, a 1:2 matched group means one source feature matched two target features, and the two target features are joined at a pseudo node. The tool will split the input line at a location near the target pseudo node. This is to improve the correspondences between the source and target lines so the next round of feature matching will produce more 1:1 matches for conflation needs.

Illustration

Usage

The output feature class contains all input features that have been split or unaltered, as well as all of their attributes. The following fields are added:
- ORIG_FID—The feature IDs of the input.
- SBM_LnFlag—Stores the following values:
  - Split—Lines that have been split.
  - Not split—Input lines that have not been altered.
  - Short match group—Lines that cannot participate in the process because they don't meet the Minimum Match Group Length parameter condition.
An optional point feature class can be generated to store locations where lines have been split or could not be split. These points can be used to inspect the result if needed. This output includes the following fields:
- ORIG_FID—The feature IDs of the input at the split locations.
- SBM_PtFlag—Stores the following values:
  - At vertex—Locations where an input line has been split at an existing vertex.
  - At nearest—Locations where an input line has been split at the nearest location from the node on the matched features.
  - Short segment—Locations where an input line cannot be split according to the specified Minimum Split Length.
  - Out of range—Locations where an input line cannot be split because the candidate split location is beyond the search distance. Some of these locations may still be used to split the lines as a post process.
  Upon inspection, it may be possible to split additional lines by any of the points flagged as Short segment or Out of range using theSplit Line At Point tool.
The Search Distance parameter is used to find candidate locations for splitting an input line from a node on the matched features. To ensure a better chance of finding a split location closer to a node on the matched features, an internal distance value is derived depending on how close a node is to an input feature. If the derived distance is less than one-third of the search distance, the derived distance is set to one-third of the search distance. If the derived distance is greater than the search distance, the derived distance value is set to the search distance. Any derived distance value in between is used as it is. Therefore, the specified search distance is the maximum value to use. For example, if you specify 90 meters as the search distance, the derived distance values used in the process would be 30 meters, 90 meters, and any values in between.
It is important to set a suitable search distance. The value you used in the prematch can be a good choice. The larger the search distance, the more likely a farther away vertex is used to split an input line, and a farther away input node is found, preventing a split from occurring.
The internally derived search distance is used to find candidate locations on the input feature from a node on the matched features. The following rules are used to determine whether the input line should split and if so, where to split it.
- If a pseudo match node finds a pseudo input node, no split will occur.
- If a nonpseudo match node finds any input node, no split will occur. For example, if a dangle match node finds an input node at a T-junction, the input line will not be split.
- Otherwise, the input feature will be split at the only vertex found, or the nearest vertex found, or if no vertex is found; the nearest location on the input line. However, if a pseudo match node finds a nonpseudo input node, the input line will always be split.
Dangling lines can be split using the Split dangle features parameter. If an input dangle line extends beyond the matched feature at the dangle end, it will be split by default. A dangling line can be split to identify the real difference between the source and target features in the subsequent feature matching.
The Minimum Match Group Length parameter can be used to exclude any match group that is too short to be split relative to the specified value. In a given match group, if both the total length of the input features and the total length of the matched features are smaller than the specified value, the group will be excluded. Splitting features should be avoided in short match groups to prevent over or dissatisfactory splitting. All involved input lines in short match groups will be written to the output and flagged with Short match group in the SBM_LnFlag field.
The Minimum Split Length parameter can be used to prevent short lines from being produced. If splitting an input line will result in a line shorter than this value, the input line will not be split. A point at the split location flagged by Short segment in the SBM_PtFlag field will be written to the point feature class, if specified, as a reference for inspection.
The Split Fields parameter can be used to specify one or more numerical fields, such as a field measuring length, to have their values split based on the proportions of the split lines.

Syntax

SplitLineByMatch_edit (in_features, matched_features, in_match_table, out_feature_class, search_distance, {in_features_as}, {out_point_feature_class}, {split_dangle}, {min_match_group_length}, {min_split_length}, {split_fields})

Parameter	Explanation	Data Type
in_features	The input line features to be split. They must be prematched with the matched features.	Feature Layer
matched_features	Matched features are used as reference when splitting the input features. They must be prematched with the input features.	Feature Layer
in_match_table	A table that includes matching information between input and matched features.	Table View
out_feature_class	The output feature class containing split lines and original lines that are not split.	Feature Class
search_distance	The distance value used to determine split locations. The value must be greater than 0. If units are not specified, the units of the input will be used.	Linear Unit
in_features_as (Optional)	Specifies whether the input features in the match table are source features or target features, so the correct features will be split. AS_SOURCE —The input features are stored as the source features in the match table. This is the default. AS_TARGET —The input features are stored as the target features in the match table.	String
out_point_feature_class (Optional)	The output point feature class containing points that represent split locations.	Feature Class
split_dangle (Optional)	Specifies whether dangling lines will be split. SPLIT_DANGLE —Dangling lines will be split following the tool's split rules. This is the default. NO_SPLIT_DANGLE —Dangling lines will not be split.	Boolean
min_match_group_length (Optional)	A given match group will only participate in the splitting process if either the total length of the input features or the total length of the matched features are greater than the specified value.	Linear Units
min_split_length (Optional)	If a split will result in one or both of the split pieces being shorter than the specified value, the split will not occur.	Linear Units
split_fields [split_field,...] (Optional)	A list of numeric fields from input features. Their field values will be based on the proportions of the split lines.	Field

Code sample

SplitLineByMatch example 1 (Python window)

The following Python window script demonstrates how to use the SplitLineByMatch function in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data/roads.gdb"
arcpy.SplitLineByMatch_edit("city_Roads", "county_Roads", "match_table",
                            "city_roads_split", "50 Meters")

SplitLineByMatch example 2 (stand-alone script)

The following stand-alone script is an example of how to apply the SplitLineByMatch function in a scripting environment.

# Name:        SplitLineByMatch_example_script2.py
# Description: Use DetectFeatureChanges to get initial matching and then use
#              SplitLineByMatch to split the source and target to improve spatial
#              correspondence. 
#              Finally use TransferAttributes to transfer a field value from the
#              split source to the split target features.
# Author:      Esri
# -----------------------------------------------------------------------

# Import system modules
import arcpy
from arcpy import env

# Set environment settings
env.overwriteOutput = True
env.workspace = r"D:\conflation\Tools\splitlinebym\roads.gdb" #r"D:\conflation\roads.gdb"

try:
    # Set local variables
    sourceFeatures = "sourceRoads"
    targetFeatures = "targetRoads"

    dfcOutput = "DFC"
    searchDistance = "100 Feet"
    dfcMatchTable = "DFC_mtable"

    slbmSourceOutput = "out_source"
    slbmSourceOutputPts = "out_sourcePoints"
    slbmTargetOutput = "out_target"
    slbmTargetOutputPts = "out_targetPoints"
    dangle = "SPLIT_DANGLE"
    minSplitLength = "300 Feet"

    transfer_fields = "Mile_Length"

    # User Detect Feature Changes tool to generate the needed match table
    arcpy.DetectFeatureChanges_management(sourceFeatures, targetFeatures, dfcOutput, searchDistance, dfcMatchTable)

    # Use Split Line By Match tool twice to split source and then target features to improve spatial correspondence
    arcpy.SplitLineByMatch_edit(sourceFeatures, targetFeatures, dfcMatchTable, slbmSourceOutput, searchDistance,
                                "AS_SOURCE", slbmSourceOutputPts, dangle, "", minSplitLength)

    arcpy.SplitLineByMatch_edit(targetFeatures, sourceFeatures, dfcMatchTable, slbmTargetOutput, searchDistance,
                                "AS_TARGET", slbmTargetOutputPts, dangle, "", minSplitLength)

    # Perform attribute transfer using the split results
    arcpy.TransferAttributes_edit(slbmSourceOutput, slbmTargetOutput, transfer_fields, searchDistance)

    # print messages
    print(arcpy.GetMessages())
    
except arcpy.ExecuteError as aex:
    print(arcpy.GetMessages(2))
    
except Exception as ex:
    print(ex.args[0])

Environments

Licensing information

ArcGIS Desktop Basic: No
ArcGIS Desktop Standard: No
ArcGIS Desktop Advanced: Yes

ArcMap

Split Line By Match