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

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

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

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

• This tool offers several commonly used vertical transformation methods including GEOID, Vertical Offset, and Vertical Offset with Grid. Some methods are equation based, but most methods such as GEOID or Vertical Offset with Grid require a data file. This file can be in binary or ASCII format. For performance reasons, a binary format is preferable.

  The file formats currently supported in ArcGIS Pro are as follows:

  • EGM84 and EGM96 released by National Geospatial-Intelligence Agency
  • GEOID, VDATUM, VERTCON, and VERTCON3 released by NOAA's National Geodetic Survey

• The GEOID method, which converts ellipsoidal heights to gravity-related heights, and the Vertical Offset with Grid method, which converts between two gravity-related height systems, support a simple ASCII file format. This file format is used by the NOAA's 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 set of 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

• The appropriate interpolation method must be provided when using a file-based method. There are several built-in interpolation methods available in the tool.

• If the vertical transformation uses a method that requires a file or files, place them 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 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.

• This tool only allows creation of transformation definitions that convert between ellipsoidal heights and gravity-related heights or between two gravity-related heights. It doesn't allow setting source and target vertical coordinate systems to ellipsoidal height systems at the same time. To convert between ellipsoidal height systems, use the Create Custom Geographic Transformation tool.

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 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 WKID or use the Select Coordinate System button to select a coordinate system.	Coordinate System
Vertical Transformation Method (Optional)	The vertical transformation method that will be used. 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 area 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. 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)	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 that will be used. 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 area 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.