Remarks

A GridFileDatumShift transforms coordinates from one GeodeticDatum to another by rubber-sheeting: a method that can handle the local distortions that occur in geodetic datums. This is often the officially recommended method to handle national datums, because of its high accuracy.

The method needs one or more files that contain a regular grid of correction vectors. To transform a point in the forward direction, Carmenta Engine looks up the four nearest correction vectors in the grid, and uses bilinear interpolation to compute the best correction vector for the point. To transform in the inverse direction, the correction vectors are reversed, and some iteration is also needed.

If a GridFileDatumShift has been attached directly to a GeodeticDatum, and a point is outside the coverage of the grid files, then an exception will be thrown. Since this behavior is often too rigid, you can use a GridFileDatumShift as one of the alternatives of a FallbackDatumShift, which means, for points outside the coverage, that the next alternative would be tried instead.

If you need a grid shift file you must usually find it yourself, since it would normally not be included as part of Carmenta Engine. The only exception is a grid shift file for the British datum OSGB36 that is built-in for easy usage; see DatumShiftChoice.

The GridFileDatumShift can read four formats for grid shift files: NTv1, NTv2, CTable2, and Geodetic Tiff Grids.

The Canadian NTv1 Format

This format, National Transformation version 1, is now deprecated.

The Canadian NTv2 Format

This format is becoming a de facto international standard. The abbreviation NTv2 stands for National Transformation version 2. The Canadians use the term for their official grid file, while other countries use the term for the file format in general. The file extension for NTv2 files is .gsb, which stands for Grid Shift Binary. There are also text versions of the format, often using the extension .gsa (Grid Shift ASCII) or .asc (ASCII), but Carmenta Engine can only use the binary version.

The NTv2 format is both simple and expressive. A single grid file can contain a hierarchical structure of grids, where a smaller, denser subgrid has priority over its coarser parent grid. It is possible to store local error estimates in the files, but not all producers of NTv2 files do that, and Carmenta Engine does not use the error estimates.

Some NTv2 files can be found here:

• Australia

• Canada

• Great Britain

• Hungary

• South Africa

• Spain

• Switzerland

• USA These files transform from NAD83(HARN) to NAD83(86).

Since it can sometimes be difficult to find these files at primary sources (national mapping agencies), the Proj Library used to collect and republish grid files as zipped collections; see http://download.osgeo.org/proj/ where you can find for example proj-datumgrid-1.8.zip, proj-datumgrid-europe-1.6.zip, proj-datumgrid-north-america-1.4.zip, proj-datumgrid-oceania-1.2.zip, and proj-datumgrid-world-1.0.zip. However, the latest of these were published in March 2020 and they will not be updated further, since the PROJ Library now prefers to republish grid shift files in a different way and format; see the section on Geodetic TIFF Grids below.

The CTable2 Format, Usually Representing NADCON Data

The NADCON format is used in the USA; see NADCON - North American Datum Conversion Utility and Donald M. Mulcare, NGS Toolkit, Part 8: The National Geodetic Survey NADCON Tool, Professional Surveyor Magazine, Feb. 2004.

Carmenta Engine does not read the NADCON format, but most of the NADCON grids are also available in the CTable2 format developed for the PROJ Library. (There was a version 1 of the CTable format, but it was different in 32-bit and 64-bit architectures and is rarely seen today.) You can find NADCON files converted to CTable2 in the file https://download.osgeo.org/proj/proj-datumgrid-1.8.zip. A CTable2 file often lacks a file extension but may have the extension .ct2, and its contents should start with CTABLE V2.0.

NADCON from older datums to NAD83(86)

Some of the NADCON files (the original ones) transform longitude and latitude from older datums to NAD83(86). If your application can regard NAD83(86) as equivalent to WGS84 (the difference can be up to about 1 meter), then you do not need to apply further transformations.

These older datums are NAD27 (on the North American continent), the Old Hawaiian Datum, the Puerto Rico Datum, and a few datums for islands in the Bering Sea. The corresponding file names are:

In the conterminous United States, the accuracy of transformation from NAD27 to NAD83(86) is typically 12 to 18 cm.

NADCON from NAD83(86) to NAD83(HARN)

The NAD83(86) datum is not quite the same as the newer NAD83(HARN), also known as NAD83(HPGN): the coordinates differ by about 0.2 to 1.0 meter. So if you need submeter accuracy, you will need to transform from NAD83(86) to NAD83(HARN), and there are other NADCON files that do so, with a typical accuracy of 5 to 6 cm. These files have six-letter names that start with a two-letter abbreviation and end with hpgn, for example flhpgn for Florida, and mdhpgn for Maryland and Delaware.

The files have been republished here in the NTv2 format, but going in the reverse direction, from NAD83(HARN) to NAD83(86).

Note: if you use these files in Carmenta Engine, you should put them in a different directory than those that transform from NAD27 to NAD83(86).

Converting to HARN: controlling the file order

If NAD83(HARN) is understood as a specification for a geodetic datum, it can be regarded as a single datum. But the realization of NAD83(HARN) consists of about 30 state-wide or regional HARNs (High Accuracy Regional Networks) – usually named NAD83(yyyy) where yyyy is a year in the 1990s – and a problem is that these regional realizations disagree slightly where they meet. For example, differences up to 0.68 meters have been reported between the HARN for Washington/Oregon and the HARN for Idaho/Montana (West). The NADCON file for each state or region must cover a rectangular area, so it must extrapolate its own HARN into neighboring regions, and overlaps are created (often larger than necessary). This means that you may need to control the order in which these NADCON files are used: if you work in a particular state, then the NADCON file for that state should have priority over the files for neighboring states. Such a file order cannot be specified by a single GridFileDatumShift object. So you must create a FallbackDatumShift, whose preferred DatumShift is a GridFileDatumShift that uses only the NADCON file for you own state, and the first fallback is another GridFileDatumShift that uses a wildcard filename *hpgn* that matches all NADCON files in the directory.

What about the latest versions of NAD83?

The latest versions of NAD83 are called NAD83(NSRS2007) and NAD83(NSRS2011). There are NADCON files (version 5) that can convert to these datums, but they are not yet available in any format that Carmenta Engine can read, as far as we know. For more details, see these links:

• NGS Coordinate Conversion and Transformation Tool (NCAT)

• The NGS GEOCON11 Page v1.1

• NGS Tools

• NOAA: The National Spatial Reference System "takes flight": 1987 - 2007.

• http://trac.osgeo.org/csmap/wiki/CsMapRfc7

Geodetic TIFF Grids

Finally, GridFileDatumShift can read Geodetic TIFF Grids, a profile of TIFF developed for the PROJ library. Since a TIFF grid can use compression, it is often much smaller than the corresponding NTv2 or CTable2 file.

• PROJ: Geodetic TIFF grids (GTG)

The PROJ developers have published many such TIFF grids in their proj-data package that is available for download or for online use; see

• PROJ: Resource files: proj-data

Note that a GridFileDatumShift can transform only the horizontal coordinates, so some of the TIFF grids in proj-data cannot be used because they define a height transformation instead. For more about height transformations, see the article Types of vertical coordinates.