Create Custom Vertical Transformation (Data Management)

Summary

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

Usage

• All custom vertical transformation files are saved with the .vtf 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 vertical transformations will inspect all custom transformations in the default storage location and present them as options for a transformation parameter. The Transformations dialog box displays combined geographic and vertical transformation paths if supported. 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 vertical transformation and overwrite the existing file.

• Files must be placed in one of the 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\Vertical 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\Vertical folder.
  • If ArcGIS Coordinate Systems Data is not installed, copy the file or files to the ArcGIS AllSource pedata folder at C:\Program Files\ArcGIS\Pro\Resources\pedata if ArcGIS AllSource is installed on a per-machine (for everyone) basis.
  • If ArcGIS AllSource is installed on a per user basis, copy the file or files to the ArcGIS AllSource pedate folder at C:\Users\username\AppData\Local\Programs\ArcGIS\Pro\Resources\pedata.

  If you didn't use the default installation locations for ArcGIS AllSource 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.

• Most files are in binary format for performance reasons. The GEOID method, which converts from ellipsoidal heights to geoidal (or other gravity-related) heights, supports a simple ASCII file format. This file format is used by the United States National Geodetic Survey. The header line contains the lower left corner: minimum latitude followed by the minimum longitude in decimal degrees. You do not have to use the 0-360 longitude range (as shown below). The latitude and longitude point separations are next, also in decimal degrees. The next values are the number of points in a row and column. The last value is a check digit and is always 1. The offset, or separation, values are floats and in meters. The first row starts at the minimum latitude and longitude values. The first three lines below show that a row of values does not have to be a single line.

      15.000000000000    291.00000000000    0.1666666666667E-01    0.1666666666665E-01    361   301  1
    -29.2936  -29.3314  -29.3710  -29.4121  -29.4540  -29.4965  -29.5382  -29.5807
    -29.6233  -29.6660  -29.7090  -29.7522  -29.7956  -29.8397  -29.8846  -29.9301

• Do not set both vertical coordinate systems to ellipsoidal heights. This behavior will be blocked in a future release. Convert ellipsoidal heights as part of a geographic (datum) transformation instead.

Parameters

Dialog

Label	Explanation	Data Type
Vertical Transformation Name	The name of the custom transformation definition.	String
Source Vertical Coordinate System	The starting vertical coordinate system. Provide a well known ID (WKID) or use the Select Coordinate System button to select a coordinate system.	String
Target Vertical Coordinate System	The final vertical coordinate system. Provide a well known ID (WKID) or use the Select Coordinate System button to select a coordinate system.	String
Interpolation Geographic Coordinate System (Optional)	The interpolation geographic coordinate system. This parameter is only active if a vertical transformation method requires it. The geographic coordinate system is used when interpolating the offset values from a file, or latitude and longitude coordinates are required by the method. The methods that do not require an interpolation geographic coordinate system are Null, Unit Change, Height Depth Reversal, and Vertical Offset. Provide a well known ID (WKID) or use the Select Coordinate System button to select a coordinate system.	Coordinate System
Vertical Transformation Method (Optional)	The vertical transformation method. From the drop-down list, choose the transformation method that will be used to transform the data from the input vertical coordinate system to the output vertical coordinate system. Once chosen, its parameters will appear in the table for editing. A list of the methods and parameters is available in the Geographic and Vertical Transformations pdf. If using a method that requires a file, see the Usage Notes for where to put the file or files.	String
Extent (Optional)	The extent where the transformation is applicable. Use WGS84 (WKID: 4326) or another GNSS-based geographic coordinate system such as NAD 1983 or GDA2020 for the extent coordinate system. If a projected coordinate system or a layer that has a projected coordinate system is provided, the values will be converted to latitude and longitude. Current Display Extent —The extent will be based on the active map or scene. This option is only available when there is an active map. Draw Extent —The extent will be based on a rectangle drawn on the map or scene. This option will create a feature class in the project geodatabase and add a layer to the map. The feature class will have the same coordinate system as the map. Note: This option is not available in the Environments dialog box. It is only available from a tool parameter with an extent data type or from the Environments tab on a tool dialog box. Note: When the Enable and disable editing from the Edit tab editing option is checked, you must enable editing on the Edit ribbon tab to draw the extent. Extent of a Layer —The extent will be based on an active map layer. Use the drop-down list to choose an available layer or use the Extent of data in all layers option to get the combined extent of all active map layers, excluding the basemap. This option is only available when there is an active map with layers. Each map layer has the following options: All Features —The extent of all features in the layer. Selected Features —The extent of the selected features in the layer. Visible Features —The extent of the visible features in the layer. Note: The extents from the Selected Features and Visible Features options are only available for feature layers. Browse —The extent will be based on an existing dataset. Clipboard —The extent can be copied to and pasted from the clipboard. Copy Extent —Copies the extent coordinates and coordinate system to the clipboard. Use Paste Extent —Pastes the extent coordinates and, optionally, the coordinate system from the clipboard. If the clipboard values do not include a coordinate system, the extent will use the map’s coordinate system. Note: The extent coordinates are copied to and pasted from the clipboard using the same formatting and order as the ArcPy Extent object: x-min, y-min, x-max, y-max, and the spatial reference. Reset Extent —The extent will be reset to the default value. Manually entered coordinates—The coordinates must be numeric values and in the active map's coordinate system. Caution: The map may use different display units than the entered coordinates. The use of a cardinal direction (N, S, E, W) is not supported. Use a negative value sign for south and west coordinates.	Extent
Accuracy (Optional)	A general statement of accuracy in meters.	Double

Derived Output

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

Python

arcpy.management.CreateCustomVerticalTransformation(vt_name, source_vt_coor_system, target_vt_coor_system, {interpolation_gcs}, {custom_vt}, {extent}, {accuracy})

Name	Explanation	Data Type
vt_name	The name of the custom transformation definition.	String
source_vt_coor_system	The starting vertical coordinate system.	String
target_vt_coor_system	The final vertical coordinate system.	String
interpolation_gcs (Optional)	The interpolation geographic coordinate system. This parameter is only active if a vertical transformation method requires it. The geographic coordinate system is used when interpolating the offset values from a file, or latitude and longitude coordinates are required by the method. The methods that do not require an interpolation geographic coordinate system are Null, Unit Change, Height Depth Reversal, and Vertical Offset.	Coordinate System
custom_vt (Optional)	The vertical transformation method. From the drop-down list, choose the transformation method that will be used to transform the data from the input vertical coordinate system to the output vertical coordinate system. Once chosen, its parameters will appear in the table for editing. A list of the methods and parameters is available in the Geographic and Vertical Transformations pdf. If using a method that requires a file, see the Usage Notes for where to put the file or files.	String
extent (Optional)	The extent where the transformation is applicable. Use WGS84 (WKID: 4326) or another GNSS-based geographic coordinate system such as NAD 1983 or GDA2020 for the extent coordinate system. If a projected coordinate system or a layer that has a projected coordinate system is provided, the values will be converted to latitude and longitude. MAXOF—The maximum extent of all inputs will be used. MINOF—The minimum area common to all inputs will be used. DISPLAY—The extent is equal to the visible display. Layer name—The extent of the specified layer will be used. Extent object—The extent of the specified object will be used. Space delimited string of coordinates—The extent of the specified string will be used. Coordinates are expressed in the order of x-min, y-min, x-max, y-max.	Extent
accuracy (Optional)	A general statement of accuracy in meters.	Double

Derived Output

Name	Explanation	Data Type
out_transformation	The output transformation.	Value Table

Code sample

CreateCustomVerticalTransformation example (Python window)

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

import arcpy
arcpy.management.CreateCustomVerticalTransformation(
    vt_name="NAD_1983_2011_ellipsoid_to_GEOID18b",
    source_vt_coor_system='VERTCS["NAD_1983_2011",DATUM["D_NAD_1983_2011",SPHEROID["GRS_1980",6378137.0,298.257222101]],PARAMETER["Vertical_Shift",0.0],PARAMETER["Direction",1.0],UNIT["Meter",1.0]]',
    target_vt_coor_system='VERTCS["NAVD88_height_(ftIntl)",VDATUM["North_American_Vertical_Datum_1988"],PARAMETER["Vertical_Shift",0.0],PARAMETER["Direction",1.0],UNIT["Foot",0.3048]]',
    interpolation_gcs='GEOGCS["GCS_NAD_1983_2011",DATUM["D_NAD_1983_2011",SPHEROID["GRS_1980",6378137.0,298.257222101]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]]',
    custom_vt="GEOID|g2018u0.bin|Bilinear",
    extent='-110 30 -80 40 GEOGCS["GCS_North_American_1983",DATUM["D_North_American_1983",SPHEROID["GRS_1980",6378137.0,298.257222101]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]]',
    accuracy=0.5
)

Environments

This tool does not use any geoprocessing environments.