TPM Coordinate Conversion program

Location and Time Inputs
Shell Scripts
More Information


I have a unix program called tpm that can convert a pair of astronomical coordinates from any reference frame (equatorial, galactic, alt/az, etc.) to any other. This state diagram shows 21 different reference frames, and how they relate to each other.


It's easy to use. You give it two angles (they could be RA and Dec, or ecliptic longitude and latitude, for example), you tell it what state you're starting in, and what state you want to end up in. For example, to go from Equatorial coordinates to Ecliptic longitude and latitude, you'd type

tpm -s1 6 -s2 3 -x 3 12 21 -y +47 28 16

Let's pick apart this command line and see what's what. You have a start state, s1, and an end state, s2. We started here in state 6 (you get the numbers from the state diagram or by typing "tpm -help"), and we wanted to end in state 3 (ecliptic). What about the angles? We have a problem with what to call them on the command line. We can't call them "RA" and "Dec", as they may not be! They could also be galactic longitude and latitude or topocentric azimuth and elevation, for example. We fall back to a very generic "x" to mean the longitudinal angle (RA, longitude, azimuth) and "y" to mean the latitudinal angle (Declination, latitude, elevation). Here we're giving an RA of 3 hours 12 minutes 21 seconds, and a Dec of 47 degrees 28 arc minutes 16 arc seconds.

The output of the command above is

2452586.405646 03H 56M 25.489S +28D 25' 37.055"

which gives the Julian date (the default date is the current time), and the ecliptic longitude and latitude.

Always give the angles in 3-part notation: hours, minutes and seconds of time for the longitudinal angle, and degrees, arc minutes, and arc seconds for the latitudinal angle. You can include or omit the H,M,S suffixes; be careful about unescaped single and double quotes.

Location and Time Inputs

Some conversions don't need the time or your location on Earth (e.g. Galactic to FK5 Heliocentric Equatorial). For those that do (az/el or HA/Dec for example), you use the -lon, -lat, and -alt command line arguments to specify your location (the default location is WIYN).

There are two ways to specify time: a single instant in time, or a start/stop/increment to specify a range in time. tpm will loop through the time range with the desired increment. Times are given with 6 numbers: year, month, day, hour, minute, second, and represent UTC.

Suppose you want to look at a target's topocentric refracted elevation at WIYN.

Single instant of time:

tpm -s1 6 -s2 19 -x 16 28 41 -y 45 53 59 -utc 2002 11 7 14 53 01

The output is:

2452586.120150 03H 16M 30.935S +23D 05' 05.343"

Range of time:

tpm -s1 6 -s2 19 -x 16 28 41 -y 45 53 59 -from 2002 11 7 0 0 0 to 2002 11 8 0 0 0 -dt 60

The output is:

2452585.500000 20H 20M 24.791S +51D 21' 39.984"
2452585.541667 20H 21M 37.281S +40D 54' 59.781"
2452585.583333 20H 31M 33.908S +30D 40' 05.086"
2452585.625000 20H 47M 41.823S +20D 52' 47.335"
2452585.666667 21H 09M 09.800S +11D 48' 55.559"
2452585.708333 21H 35M 47.939S +03D 49' 05.990"
2452585.750000 22H 07M 35.986S -03D 21' 47.975"
2452585.791667 22H 44M 16.665S -08D 22' 44.607"
2452585.833333 23H 24M 50.800S -11D 25' 06.842"
2452585.875000 00H 07M 25.994S -12D 11' 15.566"
2452585.916667 00H 49M 34.840S -10D 36' 35.230"
2452585.958333 01H 28M 57.993S -06D 50' 30.657"
2452586.000000 02H 04M 01.194S -01D 46' 57.659"
2452586.041667 02H 34M 02.173S +06D 26' 48.874"
2452586.083333 02H 58M 52.586S +14D 51' 42.568"
2452586.125000 03H 18M 31.879S +24D 12' 36.908"
2452586.166667 03H 32M 40.082S +34D 11' 12.097"
2452586.208333 03H 40M 00.361S +44D 32' 08.311"
2452586.250000 03H 36M 55.752S +54D 58' 16.324"
2452586.291667 03H 13M 19.782S +65D 00' 20.512"
2452586.333333 02H 00M 11.306S +73D 17' 48.345"
2452586.375000 23H 24M 30.975S +75D 51' 36.628"
2452586.416667 21H 20M 23.998S +70D 15' 28.229"
2452586.458333 20H 33M 14.834S +60D 57' 52.344"
2452586.500000 20H 20M 07.532S +50D 40' 36.921"

Shell Scripts

You can customize this with shell scripts. If you don't want to keep typing, say, your location at PBO each time you run tpm, put this in a shell script:

tpm -lon -5 58 41 -lat 43 4 39.7 -alt 359 $*

More Information

tpm lives in ~jwp/bin/Linux or ~jwp/bin/ppc on the Astronomy and SAL machines. PleaseCredit me if you use these.

tpm uses Jeff Percival's mighty table-driven state machine. This uses the same astrometric kernel that points the WIYN and SALT telescopes, and its results match those of the Naval Observatory's NOVAS code and those of Patrick Wallace's SLALIB code to about 5-10 milliarcseconds. The error is largely due to LSB effects in the floating point processor of the machine I used for the comparison.

tpm does not use spherical trigonometry in any of its calculations. It is a vector-based code, and is both fast and compact. See page 6 of the TPM document for a comparison of a vector-based algorithm to a spherical trig algorithm.

The very detailed TPM document is here.

The TPM state diagram is here.

The TPM data relationships are here.

Time relationships are here.

Comments are welcome; contact Jeff Percival.