User's guide for the tran transformation program

Disclaimer

This is work in progress, recently started, and presented here in order to initiate discussion on the proj.4 discussion forum.

The authors and copyright holders disclaim all liability (cf. the licence), and you should use this code for testing purposes only.

Despite the title of the document, this is not really a user's guide. Rather, it's a brief rationale, followed by a few examples — just enough to get you going, but not at all in depth (basically, because there is not yet that much depth to get into).

If you find tran potentially useful, intriguing, or just plain annoying, please take part and air your opinion on the proj forum: Then tran and it's underlying proj library functionality will improve and take shape from your input.

Why tran?

The tran transformation program provides somewhat similar functionality as the cs2cs program of the proj.4 system, which carries out geodetic transformations between different reference frames (datums), using WGS84 as pivot datum.

But historically, transformations have often been introduced as direct gateways (i.e. not taking the detour through a pivot datum) from one system to another, e.g. when national reference systems have been updated or redefined.

Typically, a transformation consists of a number of steps, e.g. first going from a projected coordinate system to a geographic, then from geographic to 3D cartesian, then through a Helmert shift / polynomial correction / nadcon style grid interpolation, and finally back again to projected coordinates using the conjugate operations.

Hence, a transformation can often be described as a number of pipeline style cascaded steps, each doing a single part of the transformation, which is well defined and easily described, whereas the overall transformation may be much harder to describe in terms of metadata.

To take advantage of this typical characteristic of geodetic transformations, tran introduces the pipeline projection, the +step keyword and the +inv qualifier.

pipeline
+proj=pipeline introduces a pipeline consisting of multiple steps.
+step
Each step starts with the +step keyword.
+inv
The +inv qualifier indicates that the corresponding step should be carried out using its inverse method.


Examples

In its simplest configuration, tran reads coordinate triplets in easting, northing, height / longitude, latitude, height order, e.g. 610000 6100000 61 or 12 55 67.

Example 1: From UTM to geocentic cartesian

tran -v +proj=pipeline +ellps=GRS80 +zone=32 \
        +step +proj=utm +inv \
        +step +proj=cart

The options following immediately after +proj=pipeline are global: They are made available to all following steps, which may use, ignore, or overwrite them.

+proj=utm +inv asks utm to run in reverse, reading projected coordinates, and providing geographical.

+proj=cart converts geodetic coordinates to cartesian.

Example 2: From UTM to geocentric cartesian and back again

tran -v +proj=pipeline +ellps=GRS80 +zone=32 \
        +step +proj=utm +inv \
        +step +proj=cart \
        +step +proj=cart +inv \
        +step +proj=utm

Example 3: From UTM to geocentric cartesian and back again in a different datum

tran -v +proj=pipeline +ellps=GRS80 +zone=32 \
        +step +proj=utm +inv \
        +step +proj=cart \
        +step +proj=helmert +x=102 +y=102 +z=129 +rx=-400 +ry=200 +rz=-400 +s=-2.5 \
        +step +proj=cart +ellps=intl +inv \
        +step +proj=utm +ellps=intl

Here the last two steps introduce a new ellipsoid, hence overwrites the GRS80 provided in the global options.