| Label | Explanation | Data Type |
Input Features
| The input line features that will be split. They must be prematched with the matched features. | Feature Layer |
Matched Features
| The features that were prematched with the input features. Matched features are used as reference when splitting the input features. | Feature Layer |
Input Match Table
| A table that includes matching information between input and matched features. | Table View |
Output Feature Class
| The output feature class containing split lines and original lines that are not split. | Feature Class |
Search Distance
| The distance value that will be 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 |
Input Features In Match
(Optional) | Specifies whether the input features in the match table are source features or target features, so the correct features will be split.
| String |
Output Split Points
(Optional) | The output point feature class containing points that represent split locations. | Feature Class |
Split dangle features
(Optional) | Specifies whether dangling lines will be split.
| Boolean |
Minimum Match Group Length
(Optional) | The minimum length a match group can be. 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 value provided. | Linear Unit |
Minimum Split Length
(Optional) | The minimum length a split piece can be. If a split will result in one or both of the split pieces being shorter than the value provided, the split will not occur. | Linear Unit |
Split Field(s)
(Optional) | A list of numeric fields from the input features. Their field values will be based on the proportions of the split lines. | Field |
Summary
Splits features based on matching relationships to obtain better corresponding line segmentation.
When working with line features in two different datasets—for example, city roads and state roads—having features in a one-to-one (1:1) matching relationship rather than a many-to-many (m:n) matching relationship will aid conflation tasks, such as attribute transfer from one source to another. This tool helps turn 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 value.
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. 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 value.
- 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 can 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 the Split Line At Point tool.
Use the Search Distance parameter 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. 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 are 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 process 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 an 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 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.
Use the Minimum Match Group Length parameter 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. Avoid splitting features 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.
Use the Minimum Split Length parameter 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.
Use the Split Fields parameter 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.
Parameters
arcpy.edit.SplitLineByMatch(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})| Name | Explanation | Data Type |
in_features | The input line features that will be split. They must be prematched with the matched features. | Feature Layer |
matched_features | The features that were prematched with the input features. Matched features are used as reference when splitting 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 that will be 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.
| 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.
| Boolean |
min_match_group_length (Optional) | The minimum length a match group can be. 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 value provided. | Linear Unit |
min_split_length (Optional) | The minimum length a split piece can be. If a split will result in one or both of the split pieces being shorter than the value provided, the split will not occur. | Linear Unit |
split_fields [split_field,...] (Optional) | A list of numeric fields from the input features. Their field values will be based on the proportions of the split lines. | Field |
Code sample
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.edit.SplitLineByMatch("city_Roads", "county_Roads", "match_table",
"city_roads_split", "50 Meters")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.
"""
# Import system modules
import arcpy
# Set environment settings
arcpy.env.overwriteOutput = True
arcpy.env.workspace = r"D:\conflation\Tools\splitlinebym\roads.gdb"
# 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"
# Use Detect Feature Changes tool to generate the needed match table
arcpy.management.DetectFeatureChanges(sourceFeatures, targetFeatures, dfcOutput, searchDistance, dfcMatchTable)
# Use Split Line By Match tool twice to split source and then target features to improve spatial correspondence
arcpy.edit.SplitLineByMatch(sourceFeatures, targetFeatures, dfcMatchTable, slbmSourceOutput, searchDistance,
"AS_SOURCE", slbmSourceOutputPts, dangle, "", minSplitLength)
arcpy.edit.SplitLineByMatch(targetFeatures, sourceFeatures, dfcMatchTable, slbmTargetOutput, searchDistance,
"AS_TARGET", slbmTargetOutputPts, dangle, "", minSplitLength)
# Perform attribute transfer using the split results
arcpy.edit.TransferAttributes(slbmSourceOutput, slbmTargetOutput, transfer_fields, searchDistance)Environments
Licensing information
- Basic: No
- Standard: No
- Advanced: Yes