Create Custom Geographic Transformation (Data Management)

Summary

Creates a transformation definition for converting data between two geographic coordinate systems or datums. The output of this tool can be used as a transformation for any tool with a parameter that requires a geographic transformation.

Usage

• All custom geographic transformation files are saved with the .gtf extension and stored in the Esri\ArcGISPro\ArcToolbox\CustomTransformations folder in your application data folder.

  • In all Windows operating systems, the AppData folder is in %appdata% and the temp folder is in %temp%. Entering %appdata% in a command window returns the AppData folder location. Entering %temp% returns the temp folder location.
  • In UNIX systems, the tmp and application data folders are located in your home directory, under $TMP and $HOME, respectively. Typing /tmp in a terminal returns the location.

• Any geoprocessing tool that uses geographic transformations will inspect all custom transformations in the default storage location and present them as options in the transformation parameter's drop-down list. The transformations will also be available to the Geographic Transformations environment.

• You cannot edit custom transformation files. They are binary files that store version and string length information that may be corrupted if modified. To update a transformation file, create a new custom geographic transformation and overwrite the existing file.

• Transformation methods are divided into two groups: equation based and file based. Equation-based methods do not need external information. File-based methods require a file or files that are stored on disk to calculate the coordinate offset values. The files are similar to rasters— with regularly spaced points—and an offset for a location is calculated using an interpolation method and values from surrounding points.

• Files must be placed in one of following locations:

  • If ArcGIS Coordinate Systems Data is installed on a per-machine (for everyone) basis, copy the file or files to the C:\Program Files (x86)\ArcGIS\CoordinateSystemsData\pedata\Geographic folder.
  • If ArcGIS Coordinate Systems Data is installed on a per-user basis, copy the file or files to the C:\Users\username\AppData\Local\Programs\ArcGIS\CoordinateSystemsData\pedata\Geographic folder.
  • If ArcGIS Coordinate Systems Data is not installed, copy the file or files to the ArcGIS Pro pedata folder at C:\Program Files\ArcGIS\Pro\Resources\pedata if ArcGIS Pro is installed on a per-machine (for everyone) basis.
  • If ArcGIS Pro is installed on a per-user basis, copy the file or files to the ArcGIS Pro pedate folder at C:\Users\username\AppData\Local\Programs\ArcGIS\Pro\Resources\pedata.

  If you didn't use the default installation locations for ArcGIS Pro or the ArcGIS Coordinate Systems Data, copy the files to the equivalent pedata folder. If these locations are not available because of permission restrictions or are hidden, ask your system administrator to help you.

Parameters

Dialog

Label	Explanation	Data Type
Geographic Transformation Name	The name of the custom transformation definition.	String
Input Geographic Coordinate System	The starting geographic coordinate system. Provide a well known ID (WKID) or use the Select Coordinate System button to select a coordinate system.	Coordinate System
Output Geographic Coordinate System	The final geographic coordinate system. Provide a WKID or use the Select Coordinate System button to select a coordinate system.	Coordinate System
Custom Geographic Transformation	The custom transformation method that will be used. A list of the methods and parameters is available in the Geographic and Vertical Transformations pdf. From the drop-down list, choose the transformation method that will be used to transform the data from the input geographic coordinate system to the output geographic coordinate system. Once chosen, additional options will appear below the transformation method.	String
Extent (Optional)	The geographic area where the transformation is applicable. Transformed data within the provided extent is guaranteed to be converted with the specified level of accuracy Current Display Extent —The extent will be based on the active map or scene. Draw Extent —The extent will be based on a rectangle drawn on the map or scene. Extent of a Layer —The extent will be based on an active map layer. Choose an available layer or use the Extent of data in all layers option. Each map layer has the following options: All Features —The extent of all features. Selected Features —The extent of the selected features. Visible Features —The extent of visible features. Browse —The extent will be based on a dataset. Clipboard —The extent can be copied to and from the clipboard. Copy Extent —Copies the extent and coordinate system to the clipboard. Paste Extent —Pastes the extent and coordinate system from the clipboard. If the clipboard does not include a coordinate system, the extent will use the map’s coordinate system. Reset Extent —The extent will be reset to the default value. When coordinates are manually provided, the coordinates must be numeric values and in the active map's coordinate system. The map may use different display units than the provided coordinates. Use a negative value sign for south and west coordinates.	Extent
Accuracy (Optional)	The expected difference between transformed (output) coordinates and their true values. Because any transformation in general degrades the quality of the dataset, the accuracy value is always the maximum absolute expected error in meters.	Double

Derived Output

Label	Explanation	Data Type
Output Transformation	The output transformation.	Value Table

Python

arcpy.management.CreateCustomGeoTransformation(geot_name, in_coor_system, out_coor_system, custom_geot, {extent}, {accuracy})

Name	Explanation	Data Type
geot_name	The name of the custom transformation definition.	String
in_coor_system	The starting geographic coordinate system.	Coordinate System
out_coor_system	The final geographic coordinate system.	Coordinate System
custom_geot	The custom transformation method that will be used. A list of the methods and parameters is available in the Geographic and Vertical Transformations pdf. Set the METHOD and PARAMETER values wrapped in a string for custom transformation GEOGTRAN. Set the name of the method from the available methods of Geocentric_Translation, Molodensky, Molodensky_Abridged, Position_Vector, Coordinate_Frame, Molodensky_Badekas, NADCON, HARN, NTV2, Longitude_Rotation, Unit_Change, and Geographic_2D_Offset. Each method has a set of parameters. You can edit the option values by entering text next to the name of the parameter within the whole string representation of the custom geographic transformation. See examples in the Python sample below.	String
extent (Optional)	The geographic area where the transformation is applicable. Transformed data within the provided extent is guaranteed to be converted with the specified level of accuracy	Extent
accuracy (Optional)	The expected difference between transformed (output) coordinates and their true values. Because any transformation in general degrades the quality of the dataset, the accuracy value is always the maximum absolute expected error in meters.	Double

Derived Output

Name	Explanation	Data Type
out_transformation	The output transformation.	Value Table

Code sample

CreateCustomGeoTransformation example (stand-alone script)

The following stand-alone script uses the CreateCustomGeoTransformation function to create a custom transformation.

# Name: CreateCustomGeographicTransformation.py
# Description: Create a custom geographic transformation in the default directory.

# import system modules
import arcpy

# set the variables
geoTransfmName = "cgt_geocentric2"

# create a spatial reference object for GCS_Tokyo
inGCS = arcpy.SpatialReference("Tokyo")

# create a spatial reference object for GCS_WGS_1984
outGCS = arcpy.SpatialReference("WGS 1984")

customGeoTransfm = "GEOGTRAN[METHOD['Geocentric_Translation'],PARAMETER['X_Axis_Translation',''],PARAMETER['Y_Axis_Translation',''],PARAMETER['Z_Axis_Translation','']]"

arcpy.management.CreateCustomGeoTransformation(geoTransfmName, inGCS, outGCS, customGeoTransfm)

Environments

This tool does not use any geoprocessing environments.