| Label | Explanation | Data Type |
Update Features
| The line features that will be compared to the base features. | Feature Layer |
Base Features
| The line features that will be compared to the update features for change detection. | Feature Layer |
Output Feature Class
| The output line feature class containing the change information. The output contains all participating update features (matched and unmatched) and any unmatched base features. | Feature Class |
Search Distance
| The distance that will be used to search for match candidates. A distance must be specified and it must be greater than zero. You can choose a preferred unit. The default is the feature unit. | Linear Unit |
Match Fields
(Optional) | The match fields from the update and base features. If specified, each pair of fields are compared for match candidates to help determine the right match. | Value Table |
Output Match Table
(Optional) | The output table containing complete feature matching information. | Table |
Change Tolerance
(Optional) | The distance used to determine if there is a spatial change. All matched update features and base features are compared to this tolerance. If any portions of the update or the base features fall outside the zone around the matched feature, it is considered a spatial change. The value must be greater than the XY Tolerance of the input data so this process can be performed and the output will include the LEN_PCT and LEN_ABS fields. The default is 0, meaning this process is not performed. Any value between 0 and the data's XY Tolerance (inclusively) will make the process irrelevant and will be replaced by 0. You can choose a unit; the default is the feature unit. | Linear Unit |
Compare Fields
(Optional) |
The fields that will determine if there is an attribute change between the matched update and base features. | Value Table |
Compare line direction (Optional) | Specifies whether line directions will be compared for matched features.
| Boolean |
Summary
Finds where the update line features spatially match the base line features and detects spatial changes, attribute changes, or both, as well as no change. It then creates an output feature class containing matched update features with information about their changes, unmatched update features, and unmatched base features.
Illustration
Usage
A typical use case for this tool is that you maintain a set of line features, roads, for example, and receive updates periodically from partners as a new set of road features. You want to know which of the updated features are changes to existing base features or are new features to be added, and which base features are old and should be deleted. This tool finds the matching features between the update and base line datasets and detects spatial changes, attribute changes, both spatial and attribute changes, or no changes, and creates an output feature class containing the feature change information.
The output feature class contains all participating update features (matched and unmatched) and any unmatched base features. Information about the detected changes are written to the following fields:
- UPDATE_FID—The feature ID of the update feature. The value is -1 for an unmatched base feature.
- BASE_FID—The feature ID of the base feature. The value is -1 for an unmatched update feature.
- CHANGE_TYPE—The type of change detected, with values as follows:
- S—A matched update feature with a spatial change.
- A—Aa matched update feature with an attribute change.
- SA—A matched update feature with both spatial and attribute changes.
- S_LD—A spatial change as well as opposite line directions.
- SA_LD—Spatial and attribute changes as well as opposite line directions.
- NC—A matched update feature with no change.
- N—An unmatched update feature that is new to the base data.
- D—An unmatched base feature that may need to be deleted from the base data.
The feature matching process is done first based on the Search Distance and the optional Match Fields parameter values. An output match table can be produced to store the match information.
The Search Distance parameter is used in finding match candidates. Use a distance large enough to catch most of the shifts between corresponding features, but not too large to cause unnecessary processing of too many candidates and potentially getting wrong matches.
Once match candidates are found, they are evaluated by a set of geometric measures to determine if they are similar enough to be considered spatially matched.
If you specify one or more pairs of fields for the Match Fields parameter, spatially matched candidates are compared to these field values to help determine the correct match. For example, if the update and base features both have a STREET_NAME field containing street names, and an update feature spatially matches two base features but only one base candidate has the same STREET_NAME value as the update feature, it is the better match. The comparison of text strings is not case sensitive, meaning that First St is considered the same as first st.
The Output Match Table parameter is optional. The match table provides complete feature matching information, including the source and target FIDs, match groups, match relationships, and the level of confidence of the matching derived from spatial and attribute matching conditions. This information can help you understand the match situations and aid in postinspection, postediting, and further analysis. See About feature matching and the match table for details.
In the output match table, the values in the SRC_FID and TGT_FID fields represent update feature IDs and base feature IDs, respectively.
The process of identifying changes occurs after feature matching. The spatial and attribute conditions, as well as line directions of all matched update features, are compared with corresponding base features to determine their CHANGE_TYPE values.
A spatial change (change type S) is detected when one or both of the following occur:
- The matched update features differ from their corresponding base features in topology. For example, one update feature matches two base features.
- In each match group, any portions of the update or base features fall outside the Change Tolerance parameter value.
The Change Tolerance parameter value serves as the width of a buffer zone around the update features or the base features. For each match group, an update buffer is created around all update features and a base buffer around all base features. Then all the update features are compared to the base buffer and all base features are compared to the update buffer. If any portions of the update features fall outside the base buffer or if any portions of the base features fall outside the update buffer, or if both occur, it is considered a spatial change. When a value greater than the XY Tolerance of the input data is specified, the output will include the following new fields:
- LEN_PCT—This field stores length percentage values based on match groups.
- LEN_ABS—This field stores absolute length values in feature units based on match groups.
The values of these fields are determined based on the match group that the output feature belongs to, depending on the following conditions:
- If only update features fall outside the base buffer:
- Lu = total length of the outside portions of the update features.
- Pu (the length percentage) = Lu / the total length of all the update features * 100.
- LEN_PCT = Pu
- LEN_ABS = Lu
- If only base features fall outside the update buffer:
- Lb = total length of the outside portions of the base features.
- Pb (the length percentage) = Lb / the total length of all the base features * 100.
- LEN_PCT = Pb
- LEN_ABS = Lb
- If both of the above occur:
- The larger of Lu and Lb and its associated percentage value are written. In case of Lb being the written, a negative sign is added for the same reason mentioned above.
The percentage value ranges from 0 to 100 in which 0 means both update and base features in a match group are completely within the change tolerance zones,; and 100 means all update or base features are outside the change tolerance zones.
The LEN_PCT and LEN_ABS values can help you determine whether a change is significant. The higher the values, the more dramatic the change. Only features with spatial changes are assigned these values; others are assigned -1.
An attribute change (change type A) is detected based on the Compare Fields parameter value. If you specify one or more pairs of fields for the Compare Fields parameter, matched features are compared to these fields to determine if there is an attribute change. The comparison of text strings is not case sensitive, meaning that First St is considered the same as first st. If both spatial and attribute changes are detected for a matched update feature, it is assigned the change type SA. If no spatial and attribute changes are detected for a matched update feature, it is considered no change and is assigned the change type NC.
Line direction change (S_LD or SA_LD change types) is considered a spatial change and can be detected as an option.
- The matched update features are assigned change type S_LD if the direction of any of their lines are opposite from one or more matched base features, with or without the spatial changes described above. In other words, they are the S or NC types if line directions are not compared.
- The matched update features are assigned change type SA_LD if the direction of any of their lines are opposite from one or more matched base features, in addition to the attribute change or the spatial and attribute changes described above. In other words, they are the A or SA types if line directions are not compared.
The union of input extents is used as the processing extent. The counts of participating source and target features are reported in the processing messages.
Feature matching accuracy relies on data quality, complexity, and similarities of the two inputs.
Minimize data errors and select relevant features as input through preprocessing. In general, it is helpful when the features in an input dataset are topologically correct, have valid geometry, and are singlepart and not duplicate; otherwise, unexpected results may occur.
You can review the detected changes in the output feature class. You may find that the spatial differences between the two data sources are significant and decide that one of them should be adjusted to better match the other. You can also transfer attributes between update features and base features. You can use the rubbersheeting and attribute transfer tools in the Conflation toolset to make the changes.
Note:
All inputs must be in the same coordinate system.
Parameters
arcpy.management.DetectFeatureChanges(update_features, base_features, out_feature_class, search_distance, {match_fields}, {out_match_table}, {change_tolerance}, {compare_fields}, {compare_line_direction})| Name | Explanation | Data Type |
update_features | The line features that will be compared to the base features. | Feature Layer |
base_features | The line features that will be compared to the update features for change detection. | Feature Layer |
out_feature_class | The output line feature class containing the change information. The output contains all participating update features (matched and unmatched) and any unmatched base features. | Feature Class |
search_distance | The distance that will be used to search for match candidates. A distance must be specified and it must be greater than zero. You can choose a preferred unit. The default is the feature unit. | Linear Unit |
match_fields [[source_field, target_field],...] (Optional) | The match fields from the update and base features. If specified, each pair of fields are compared for match candidates to help determine the right match. | Value Table |
out_match_table (Optional) | The output table containing complete feature matching information. | Table |
change_tolerance (Optional) | The distance used to determine if there is a spatial change. All matched update features and base features are compared to this tolerance. If any portions of the update or the base features fall outside the zone around the matched feature, it is considered a spatial change. The value must be greater than the XY Tolerance of the input data so this process can be performed and the output will include the LEN_PCT and LEN_ABS fields. The default is 0, meaning this process is not performed. Any value between 0 and the data's XY Tolerance (inclusively) will make the process irrelevant and will be replaced by 0. You can choose a unit; the default is the feature unit. | Linear Unit |
compare_fields [[source_field, target_field],...] (Optional) |
The fields that will determine if there is an attribute change between the matched update and base features. | Value Table |
compare_line_direction (Optional) | Specifies whether line directions will be compared for matched features.
| Boolean |
Code sample
The following Python window script demonstrates how to use the DetectFeatureChanges function in immediate mode.
import arcpy
arcpy.env.workspace = "C:/data"
arcpy.DetectFeatureChanges_edit("update_Roads.shp",
"base_Roads.shp", "output_changes.shp"
"25 Feet", #, #, "7.6 Meters",
["rdClass", "roadClass"])The following stand-alone script is an example of how to apply the DetectFeatureChanges function in a scripting environment.
# Name: DetectFeatureChanges_example_script2.py
# Description: Perform change detection between newly received road data and
# existing road data and find the number of new roads and the
# total length of them.
# Author: Esri
# -----------------------------------------------------------------------
# Import system modules
import arcpy
from arcpy import env
# Set environment settings
env.overwriteOutput = True
env.workspace = r"D:\conflationTools\ScriptExamples\data.gdb"
# Set local variables
updateFeatures = "updateRoads"
baseFeatures = "baseRoads"
dfcOutput = "dfc_out"
search_distance = "300 Feet"
match_fields = "RD_NAME FULLNAME"
statsTable = "new_roads_stats"
# Perform spatial change detection
arcpy.DetectFeatureChanges_management(updateFeatures, baseFeatures, dfcOutput, search_distance, match_fields)
# ====================================================================================
# Note 1: The result of DetectFeatureChanges may contain errors; see tool reference.
# Inspection and editing may be necessary to ensure correct CHANGE_TYPE N, which
# represents un-matched update feautres, before further calculations.
#
# One of the quick ways of checking whether the CHANGE_TYPE N features have
# matching base features is to find their mid-points and use them to search for
# features in base data, as processed below.
# ====================================================================================
# ======== Check update roads with CHANGE_TYPE N for potential match
# Make Feature Layer with selection of CHANGE_TYPE = 'N' (un-matched update features)
arcpy.MakeFeatureLayer_management(dfcOutput, "sel_N_layer", "CHANGE_TYPE = 'N'")
# Get mid-points of the selected features; the mid-points carry all the attributes.
arcpy.FeatureVerticesToPoints_management("sel_N_layer", "in_memory\midPts", "MID")
# Find nearest base features from the mid-points
arcpy.Near_analysis("in_memory\midPts", baseFeatures, "300 Feet")
# ====================================================================================
# Note 2: At this point you can manually inspect the midPts by the NEAR_DIST values;
# the lower the values, the higher chance (not always) a match was missed in the
# dfc process. Delete features from midPts that have found matching base features
# before further process.
# ====================================================================================
# Transfer CHANGE_TYPE values from features of midPts to update features
arcpy.JoinField_management(updateFeatures, "OBJECTID", "in_memory\midPts", "UPDATE_FID", "CHANGE_TYPE")
# Get the count of new roads and the total length; the remaining roads have
# Null values for CHANGE_TYPE.
arcpy.Frequency_analysis(updateFeatures, statsTable, "CHANGE_TYPE", "Shape_Length")