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