ArcGIS Desktop

  • ArcGIS Pro
  • ArcMap

  • My Profile
  • Help
  • Sign Out
ArcGIS Desktop

ArcGIS Online

The mapping platform for your organization

ArcGIS Desktop

A complete professional GIS

ArcGIS Enterprise

GIS in your enterprise

ArcGIS Developers

Tools to build location-aware apps

ArcGIS Solutions

Free template maps and apps for your industry

ArcGIS Marketplace

Get apps and data for your organization

  • Documentation
  • Support
Esri
  • Sign In
user
  • My Profile
  • Sign Out

ArcMap

  • Home
  • Get Started
  • Map
  • Analyze
  • Manage Data
  • Tools
  • Extensions

Calculate Transformation Errors

  • Summary
  • Usage
  • Syntax
  • Code sample
  • Environments
  • Licensing information

Summary

Calculates residue errors and 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 prior to the Transform Features tool to determine if the control points are good enough 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 highly recommended. Using a geographic coordinate system (GCS) with values in latitude and longitude may result in undesired distortion or cause calculation errors.

  • Errors are calculated for one of the three transformation methods: affine, similarity, and projective. Each method requires a minimum number of transformation links. See About spatial adjustment transformations for more details, including transformation formulas.

    • AFFINE—Affine transformation requires a minimum of three transformation links.
    • PROJECTIVE—Projective transformation requires a minimum of four transformation links.
    • SIMILARITY—Similarity transformation requires a minimum of two transformation links.
  • The transformation result depends on the quality of your 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 are used to derive the parameters used in transformation equations, which are a best fit between the source and destination control points as described in About spatial adjustment transformations. 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 are 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 end location of the link
    • Y_Source: The y coordinate of the source or from end location of the link
    • X_Destination: The x coordinate of the destination or to end location of the link
    • Y_Destination: The y coordinate of the destination or to end location of the link
    • Residual_Error: The residual error of the transformed location

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

    The "Understanding residual and root mean square" section in About spatial adjustment transformations provides more details on the calculations of residual errors and RMSE. It is up to you to 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, you would need to review the residual errors and discard or replace the links that have high residual errors.

Syntax

arcpy.edit.CalculateTransformationErrors(in_link_features, {out_link_table}, {method})
ParameterExplanationData Type
in_link_features

Input link features that link known control points for spatial transformation.

Feature Layer
out_link_table
(Optional)

The output table containing input links feature IDs and their residual errors. The residual errors for input links are 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 end location of the link
  • Y_Source: The y coordinate of the source or from end location of the link
  • X_Destination: The x coordinate of the destination or to end location of the link
  • Y_Destination: The y coordinate of the destination or to end location of the link
  • Residual_Error: The residual error of the transformed location
Table
method
(Optional)

Transformation method to use to convert input feature coordinates.

  • AFFINE —Affine transformation requires a minimum of three transformation links. This is the default.
  • PROJECTIVE —Projective transformation requires a minimum of four transformation links.
  • SIMILARITY —Similarity transformation requires a minimum of two transformation links.
String

Derived Output

NameExplanationData 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.CalculateTransformationErrors_edit("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 are in country.gdb and output will also go to this gdb
arcpy.env.workspace = os.path.join(os.getcwd(), "country.gdb")

try:
    in_links_feats = "link_features"
    out_link_table = "output_table"
    
    # transformation method
    method = "SIMILARITY"
    
    result = arcpy.CalculateTransformationErrors_edit(in_links_feats, out_link_table, method)

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

    # if error is less than 12.234 then run Transform Features
    if error < 20.0:
        # make a copy of the input features 
        arcpy.CopyFeatures_management(in_links_feats, "in_links_copy")
        arcpy.TransformFeatures_edit("in_links_copy", in_links_feats, method, "out_link_table")
    else:
        print("Transformation error {} is too high".format(error))
        
except arcpy.ExecuteError as aex:
    print(arcpy.GetMessages(2))
    
except Exception as ex:
    print(ex.args[0])

Environments

  • Current Workspace
  • Extent

Licensing information

  • Basic: No
  • Standard: No
  • Advanced: Yes

Related topics

  • An overview of the Editing toolbox

ArcGIS Desktop

  • Home
  • Documentation
  • Support

ArcGIS

  • ArcGIS Online
  • ArcGIS Desktop
  • ArcGIS Enterprise
  • ArcGIS
  • ArcGIS Developer
  • ArcGIS Solutions
  • ArcGIS Marketplace

About Esri

  • About Us
  • Careers
  • Esri Blog
  • User Conference
  • Developer Summit
Esri
Tell us what you think.
Copyright © 2021 Esri. | Privacy | Legal