TPXEV Subroutine

public subroutine TPXEV(v, v0, xi, eta, j)

In the tangent plane projection, given celestial direction cosines for a star and the tangent point, solve for the star's rectangular coordinates in the tangent plane.

Status: support routine.

Notes

1. The tangent plane projection is also called the "gnomonic projection" and the "central projection".

2. The eta axis points due north in the adopted coordinate system. If the direction cosines represent observed (RA,Dec), the tangent plane coordinates (xi,eta) are conventionally called the "standard coordinates". If the direction cosines are with respect to a right-handed triad, (xi,eta) are also right-handed. The units of (xi,eta) are, effectively, radians at the tangent point.

3. The method used is to extend the star vector to the tangent plane and then rotate the triad so that (x,y) becomes (xi,eta). Writing (a,b) for the celestial spherical coordinates of the star, the sequence of rotations is (a+pi/2) around the z-axis followed by (pi/2-b) around the x-axis.

4. If vector V0 is not of unit length, or if vector V is of zero length, the results will be wrong.

5. If V0 points at a pole, the returned (XI,ETA) will be based on the arbitrary assumption that the longitude coordinate of the tangent point is zero.

6. This routine is a member of the following set:

    spherical       vector       solve for
   
    TPXES    > TPXEV <    xi,eta
    TPSTS      TPSTV       star
    TPORS      TPORV      origin
   

References

• Calabretta M.R. & Greisen, E.W., 2002, "Representations of celestial coordinates in FITS", Astron.Astrophys. 395, 1077

• Green, R.M., "Spherical Astronomy", Cambridge University Press, 1987, Chapter 13.

History

• IAU SOFA revision: 2018 January 2

Arguments

    subroutine TPXEV ( v, v0, xi, eta, j )

    implicit none

    real(wp),dimension(3),intent(in) :: v !! direction cosines of star (Note 4)
    real(wp),dimension(3),intent(in) :: v0 !! direction cosines of tangent point (Note 4)
    real(wp),intent(out) :: xi !! tangent plane coordinates of star
    real(wp),intent(out) :: eta !! tangent plane coordinates of star
    integer,intent(out) :: j !! status:
                             !! * 0 = OK
                             !! * 1 = star too far from axis
                             !! * 2 = antistar on tangent plane
                             !! * 3 = antistar too far from axis

    real(wp),parameter :: tiny = 1.0e-6_wp

    real(wp) :: x, y, z, x0, y0, z0, r2, r, w, d

    !  Star and tangent point.
    x = v(1)
    y = v(2)
    z = v(3)
    x0 = v0(1)
    y0 = v0(2)
    z0 = v0(3)

    !  Deal with polar case.
    r2 = x0*x0 + y0*y0
    r = sqrt(r2)
    if ( r == 0.0_wp ) then
       r = 1e-20_wp
       x0 = r
    end if

    !  Reciprocal of star vector length to tangent plane.
    w = x*x0 + y*y0
    d = w + z*z0

    !  Check for error cases.
    if ( d > tiny ) then
       j = 0
    else if ( d >= 0.0_wp ) then
       j = 1
       d = tiny
    else if ( d > -tiny ) then
       j = 2
       d = -tiny
    else
       j = 3
    end if

    !  Return the tangent plane coordinates (even in dubious cases).
    d = r*d
    xi = ( y*x0 - x*y0 ) / d
    eta = ( z*r2 - z0*w ) / d

    end subroutine TPXEV