Calculate Transformation Errors (Editing)

Summary

Calculates residue errors and the root mean square error (RMSE) based on the coordinates of the input links between known control points to be used for spatial data transformation.

Usage

• This tool is used before the Transform Features tool to determine whether the control points are suitable for the intended transformation, especially before you transform a large number of features.

• Input link features are lines representing transformation links between corresponding control points.

• The transformation works in a Cartesian or planar coordinate system. A projected coordinate system (PCS) is recommended. Using a geographic coordinate system (GCS) with values in latitude and longitude may result in distortion or cause calculation errors.

• Errors will be calculated for one of the three transformation methods: affine, similarity, and projective. Each method requires a minimum number of transformation links. See Transform a feature for details, including transformation formulas.

  • AFFINE—Requires a minimum of three transformation links
  • PROJECTIVE—Requires a minimum of four transformation links
  • SIMILARITY—Requires a minimum of two transformation links

• The transformation result depends on the quality of the input links. A link should start from a known source location and end at its corresponding destination location, also called control points. The better established the control points, the more accurate the transformed result. The coordinates of the from and to locations of the links will be used to derive the parameters used in transformation equations, which are a best fit between the source and destination control points as described in Transform features. Even if you use the transformation parameters to transform the actual source control points, the resulting locations won't match the destination control point locations. This is called the residual error and it is generated for each transformation link. The residual errors for input links will be written to the specified output table that contains the following fields:

  • Orig_FID—The input link feature ID
  • X_Source—The x-coordinate of the source or from the end location of the link
  • Y_Source—The y-coordinate of the source or from the end location of the link
  • X_Destination—The x-coordinate of the destination or to the end location of the link
  • Y_Destination—The y-coordinate of the destination or to the end location of the link
  • Residual_Error—The residual error of the transformed location

  A RMSE, also known as root mean square deviation (RMSD), will be calculated based on the residual errors and indicates the general suitability of the derived transformation. The RMSE value is written out in the processing messages. It is also a derived output parameter that you can use in a script or model workflow.

  The Transform features topic provides details regarding the calculations of residual errors and RMSE. You must determine the acceptable RMSE value based on your knowledge of the positional accuracy of the input features as well as the control points. If the RMSE value is too high, review the residual errors and discard or replace the links that have high residual errors.

Parameters

Dialog

Label	Explanation	Data Type
Input Link Features	The input link features that link known control points for spatial transformation.	Feature Layer
Output Link Table (Optional)	The output table containing the input links feature IDs and their residual errors. The residual errors for input links will be written to the specified output table that contains the following fields: Orig_FID—The input link feature ID X_Source—The x-coordinate of the source or from the end location of the link Y_Source—The y-coordinate of the source or from the end location of the link X_Destination—The x-coordinate of the destination or to the end location of the link Y_Destination—The y-coordinate of the destination or to the end location of the link Residual_Error—The residual error of the transformed location	Table
Method (Optional)	Specifies the transformation method that will be used to convert the input feature coordinates. Affine transformation—A minimum of three transformation links is required. This is the default. Projective transformation—A minimum of four transformation links is required. Similarity transformation—A minimum of two transformation links is required.	String

Derived Output

Label	Explanation	Data Type
RMSE	Reports the root mean square error (RMSE) value.	Double

Python

arcpy.management.CalculateTransformationErrors(in_link_features, {out_link_table}, {method})

Name	Explanation	Data Type
in_link_features	The input link features that link known control points for spatial transformation.	Feature Layer
out_link_table (Optional)	The output table containing the input links feature IDs and their residual errors. The residual errors for input links will be written to the specified output table that contains the following fields: Orig_FID—The input link feature ID X_Source—The x-coordinate of the source or from the end location of the link Y_Source—The y-coordinate of the source or from the end location of the link X_Destination—The x-coordinate of the destination or to the end location of the link Y_Destination—The y-coordinate of the destination or to the end location of the link Residual_Error—The residual error of the transformed location	Table
method (Optional)	Specifies the transformation method that will be used to convert the input feature coordinates. AFFINE—A minimum of three transformation links is required. This is the default. PROJECTIVE—A minimum of four transformation links is required. SIMILARITY—A minimum of two transformation links is required.	String

Derived Output

Name	Explanation	Data Type
out_rmse	Reports the root mean square error (RMSE) value.	Double

Code sample

CalculateTransformationErrors example 1 (Python window)

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

import arcpy
arcpy.env.workspace = "C:/data/Countries.gdb"
arcpy.edit.CalculateTransformationErrors("control_Links", "output_Table", "AFFINE")

CalculateTransformationErrors example 2 (stand-alone script)

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

import arcpy
import os

# All input data is in country.gdb and output will also go to this gdb
arcpy.env.workspace = os.path.join(os.getcwd(), "country.gdb")

in_links_feats = "link_features"
out_link_table = "output_table"

# Transformation method
method = "SIMILARITY"

result = arcpy.edit.CalculateTransformationErrors(in_links_feats, out_link_table, method)

# Get the transformation error
error = float(result.getOutput(1))

# If error is less than 12.234, run Transform Features
if error < 20.0:
    # Make a copy of the input features 
    arcpy.management.CopyFeatures(in_links_feats, "in_links_copy")
    arcpy.edit.TransformFeatures("in_links_copy", in_links_feats, method, "out_link_table")
else:
    print("Transformation error {} is too high".format(error))

Environments

Current Workspace, Extent