Up
noaa.gov
Vertical Datum Transformation
Integrating America's Elevation Data

VDatum Command-line User Guide

This User Guide describes how-to run VDatum version 4.x without the graphical user interface.

Once you download VDatum software and its transformation grids, your computer is ready to transform geospatial data among several horizontal and vertical datums.

On This Page

down arrow  Point Conversion

down arrow  File Conversion

General syntax:

About Java Home:

Georeferencing Parameters

Syntax:

ihorz:<source horizontal datum>[:<coordinate system>:<unit>:<zone>] [ivert:<source vertical datum>[:<unit>:[<height/sounding>[:<geoid>]]]] ohorz:<target horizontal datum>[:<coordinate system>:<unit>:<zone>] [overt:<target vertical datum>[:<unit>[:<height/sounding>[:<geoid>]]]]

where:

Parameter Description
ihorz

Provides details about horizontal information of the source data.

ivert

Provides details about vertical information of the source data. If omitted, the transform is considered to be 2-dimension.

ohorz

Provides details about target horizontal information. If omitted, result will be horizontally referenced in NAD83_2011, geographic coordinates.

When specify ohorz:ihorz, results are considered to be horizontally referenced exactly as source. This is especially for LiDAR conversion with source and target data are in State Plane coordinate system.

overt

Provides details about vertical information of the target data. If omitted, the transform is considered to be 2-dimension.

<coordinate system>

Either geo, utm, spc or xyz, corresponding to geographic coordinates, UTM coordinates, State Plane coordinates or geocentric coordinates.

If omitted, the geographic coordinate system with horizontal coordinates in degrees (i.e., geo:deg) are used.

<unit>
  • In geographic coordinates, longitude/latitude units are deg as degrees.

  • In projected coordinates, easting/northing units are either m, ft, or us_ft corresponding to meters, (international)feet or US survey feet.

  • Height unit is either m, ft, or us_ft corresponding to meters, (international)feet or US survey feet. If omitted, vertical unit is set to m as meters.

<height/sounding>

Either height or sounding. If omitted, height is used when a vertical datum is specified.

<zone>
  • Northern UTM zone shall be 1 to 60, southern UTM zone shall be -1 to -60.

  • SPC zone shall be from 101 to 5400.

<geoid>

A GEOID model is needed when converting between orthometric datums (NAVD88, NGVD29) and ellipsoidal datums (NAD83_2011, WGS84 or ITRFxx). If omitted, the newest available GEOID model will be used when required.

Region Number

Syntax:

region_number Region Description
1 Alaska
2 South East Alaska TIDAL
3 American Samoa
4 Contiguous United States
5 Chesapeake/Delaware Bay
6 West Coast
7 West Gulf of Mexico
8 Guam and Commonwealth of Northern Mariana Islands
9 Hawaii
10 Puerto Rico and US Virgin Islands
11 Saint George Island
12 Saint Paul Island
13 Saint Lawrence Island

Point Conversion

Syntax

[Java_home]java -jar vdatum.jar <referencing_parameters> [-deg2dms] [-report-pt:<lon/east/x>,<lat/north/y>[,<height/z>] [-pt:<lon/east/x>,<lat/north/y>[,<height/z>] [epoch:<x:y>] region:<region_number>

where:

Examples:

File Conversion

Syntax

[Java_home]java -jar vdatum.jar <referencing_parameters> [-nodata-file:<File Format>:<input file #1>[<System.path.separator><input file #i>]<System.path.separator><output folder> [epoch:<x:y>] region:<region_number>

where:

Parameter Description
-nodata

If specified, all results of -999999 will not be written to the output files.

<System.path.separator>

Depends on users' OS system. This could be semi-colon [;] in Windows or colon [:] in Unix/Mac OS. Users could run the help command to get this system information.

<File Format>

Either ASCIILiDAR (LAS) or ESRI ASCII Raster (.ASC) file format. This can't be mixed.

epoch

Input and output time epochs of positional coordinates.

ASCII File Format

A plain-text file of multiple lines, separated by line breaks. Each line is a point record containing coordinates and/or other information of a point. Each record consists of fields, separated by a delimiter such as comma, tab, semi-colon or space. All records shall have an identical sequence of fields. Field index starts from 0.

Syntax:

txt:<coordinate delimitor>,<lon/easting/ECEF-X>,<lat/northing/ECEF-Y>[,<height/ECEF-Z>[,append][,skip<rows>]]

where:

<coordinate delimiter> A charactor that separates the coordinates on the coordinate lines. Either commaspacesemicolon, or tab.
<lon/easting/ECEF-X>

Longitude/Easting/ECEF-X coordinate column order, equal or greater than 0.

<lat/northing/ECEF-Y>

Latitude/Northing/ECEF-Y coordinate column order, equal or greater than 0.

<height/ECEF-Z>

Elevation column order, equal or greater than 0.

-append

If specified, each transform result will be added at the end of each coordinate line. Note: a header line will be automatically generated, displaying the column names.

skip<rows>

Number of coordinate lines to skip at the start of the file before trying to extract data. This is useful is some header lines at the start of the file should be skipped over.

Example:

File sample:

ID,longitude,latitude,elevation
H10536,-82.738573,27.602627,35.8102
H10536,-82.738625,27.602763,40.7103
H10536,-82.738678,27.603218,51.2106
H10536,-82.738661,27.603376,54.5107
H10536,-82.738628,27.603687,53.5108
H10536,-82.738620,27.604117,52.5110
H10536,-82.738594,27.604580,51.9112
H10536,-82.738600,27.605044,50.9115
H10536,-82.738633,27.605825,51.2120

Syntax (Windows):

[Java_home]java -jar vdatum.jar ihorz:NAD83_2011 ivert:navd88:m:height ohorz:NAD83_2011:geo:deg overt:mllw:m:height -file:txt:space,1,2,3,skip1:<input-file>;<output-folder> region:<region_number>

LiDAR (.LAS/.LAZ) File Format, version 1.0, 1.1, 1.2 and 1.4

The LAS file format is a public and binary file format that storing 3-dimensional LiDAR point cloud data.

Syntax:

las:las[,autosrcgeo]

where:

autosrcgeo

If specified, VDatum will automatically detect the geo-referencing information of the source file(s), stored in the LAS header.

Example (Windows):

[Java_home]java -jar vdatum.jar ihorz:NAD83_2011 ivert:NAVD88 ohorz:ihorz overt:NAD83_2011 -file:las:las,autosrcgeo:<input-file >;<output-folder>

  • Sample LAS-1.2 file download

  • Sample LAS-1.4 file download

  • Sample LAZ-1.2 file download

  • Sample LAZ-1.4 file download

  • 1) LAS:

    lib\java_home\openjdk-11.0.2\bin\java -jar vdatum.jar ihorz:NAD83_2011:utm:m:19 ivert:NAD83_2011:m:height:GEOID12B ohorz:NAD83_2011:utm:m:19 overt:LMSL:m:height:GEOID12B -file:las:las,autosrcgeo:C:\VD_Test\las_1_2_c.las;C:\VD_Test\result region:4

  • 2) LAS with classification 2 and 26:

    lib\java_home\openjdk-11.0.2\bin\java -jar vdatum.jar ihorz:NAD83_2011:utm:m:19 ivert:NAD83_2011:m:height:GEOID12B ohorz:NAD83_2011:utm:m:19 overt:LMSL:m:height:GEOID12B -file:las:las,autosrcgeo:C:\VD_Test\las_1_2_c.las;C:\VD_Test\result,2,26 region:4

  • 3) LAZ (LAZ format file can only be processed on Windows OS):

    lib\java_home\openjdk-11.0.2\bin\java -jar vdatum.jar ihorz:NAD83_2011:utm:m:19 ivert:NAD83_2011:m:height:GEOID12B ohorz:NAD83_2011:utm:m:19 overt:LMSL:m:height:GEOID12B -file:las:las,autosrcgeo:C:\VD_Test\las_1_2_ss_laz.laz;C:\VD_Test\result region:4

  • 4) LAZ with classification 2 and 64 (LAZ format file can only be processed on Windows OS):

    lib\java_home\openjdk-11.0.2\bin\java -jar vdatum.jar ihorz:NAD83_2011:utm:m:19 ivert:NAD83_2011:m:height:GEOID12B ohorz:NAD83_2011:utm:m:19 overt:LMSL:m:height:GEOID12B -file:las:las,autosrcgeo:C:\VD_Test\las_1_2_ss_laz.laz;C:\VD_Test\result,2,64 region:4

where:

  • Source georeferencing shall be extracted from the source file by VDatum;

  • Horizontal information shall be unchanged, i.e. same horizontal datum, coordinate system, zone, and unit for both source and target;

  • Target vertical datum shall be NAD83_2011:m:height.

Note that even though the source georeferencing information is specified as "ihorz:NAD83_2011 ivert:NAVD88", these information will be replaced by what extracted from the source file.

asc - ESRI ASCII Raster File Format

Syntax:

esri_asc:esri_asc

Example (Windows):

[Java_home]java -jar vdatum.jar ihorz:NAD83_2011:geo:deg ivert:NAVD88:m:height ohorz:NAD83_2011:geo:deg overt:NAD83_2011:m:height -file:esri_asc:esri_asc:<input-file >;<output-folder>