Transform Features

Summary

Converts the coordinates of input features from one location to another through scaling, shifting, and rotating based on the transformation links between known corresponding control points.

Usage

Caution:

This tool modifies the input data. See Tools that do not create output datasets for more information and strategies to avoid undesired data changes.

Note:

All inputs must be in the same coordinate system.

• Input features can be points, lines, or polygons.

• Input link features are lines representing transformation links between known corresponding control points. The starting point of a link is the source control point location and the endpoint of the link is the corresponding target control point location.

• 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.

• All input features are transformed by 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 transformed 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 transformation parameters, which are a best fit between the source and destination control points. 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. As an option, the residual errors for input links can be written out to a 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.TransformFeatures(in_features, in_link_features, {method}, {out_link_table})

Parameter	Explanation	Data Type
in_features	Input features, the coordinates of which are to be transformed.	Feature Layer
in_link_features	Input link features that link known control points for the transformation.	Feature Layer
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
out_link_table (Optional)	The output table containing input links and their residual errors.	Table

Derived Output

Name	Explanation	Data Type
out_rmse	Reports the root mean square error (RMSE) value.	Double
out_feature_class	The updated input features.	Feature Layer

Code sample

TransformFeatures example 1 (Python window)

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

import arcpy
arcpy.env.workspace = "C:/data"
arcpy.TransformFeatures_edit("source_Roads.shp","control_Links.shp",
                             "AFFINE")

TransformFeatures example 2 (stand-alone script)

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

import arcpy
import os

# Set geoprocessing environments
arcpy.env.overwriteOutput = True

# function to convert link info in a text file to a line feature class
def CreateLinkFeatures(in_text_file, in_data):

    sr = arcpy.Describe(in_data).spatialReference
    features = []  # a list to hold polyline geometry objects

    f = open(in_text_file, "r")
    
    for line in f.readlines():

        # take start/end blank spaces off
        # separate the start and end point coordinates
        points = line.strip().split()   
        
        point1 = arcpy.Point(float(points[1]), float(points[2]))
        point2 = arcpy.Point(float(points[3]), float(points[4]))
        
        features.append(arcpy.Polyline(arcpy.Array([point1, point2]), sr))
        
    f.close()   # close the text file

    # copy the geometry objects into a feature class named Links
    result = arcpy.CopyFeatures_management(features, in_data + "_links")

    return result.getOutput(0)
    
if __name__ == "__main__":

    # Make a copy of the data because
    # TransformFeatures tool modifies the input data
    arcpy.CopyFeatures_management(r"C:\data\Tutorial.gdb\Parcels", r"C:\data\Tutorial.gdb\Parcels_copy")

    links_file = r"C:\data\TF_links.txt"
    tf_link_features = CreateLinkFeatures(links_file, r"C:\data\Tutorial.gdb\Parcels")
    
    try:
        arcpy.TransformFeatures_edit(r"C:\data\Tutorial.gdb\Parcels_copy", tf_link_features)
        print(arcpy.GetMessages())
        
    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