TPORV Subroutine

public subroutine TPORV(xi, eta, v, v01, v02, n)

In the tangent plane projection, given the rectangular coordinates of a star and its direction cosines, determine the direction cosines of the tangent point.

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 vector V must be of unit length or the result will be wrong.

4. Cases where there is no solution can arise only near the poles. For example, it is clearly impossible for a star at the pole itself to have a non-zero xi value, and hence it is meaningless to ask where the tangent point would have to be.

5. Also near the poles, cases can arise where there are two useful solutions. The returned value N indicates whether the second of the two solutions returned is useful; N=1 indicates only one useful solution, the usual case.

6. The basis of the algorithm is to solve the spherical triangle PSC, where P is the north celestial pole, S is the star and C is the tangent point. Calling the celestial spherical coordinates of the star and tangent point (a,b) and (a0,b0) respectively, and writing rho^2 = (xi^2+eta^2) and r^2 = (1+rho^2), and transforming the vector V into (a,b) in the normal way, side c is then (pi/2-b), side p is sqrt(xi^2+eta^2) and side s (to be found) is (pi/2-b0), while angle C is given by sin(C) = xi/rho and cos(C) = eta/rho; angle P (to be found) is (a-a0). After solving the spherical triangle, the result (a0,b0) can be expressed in vector form as V0.

7. 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 TPORV ( xi, eta, v, v01, v02, n )

    implicit none

    real(wp),intent(in) :: xi !! rectangular coordinates of star image (Note 2)
    real(wp),intent(in) :: eta !! rectangular coordinates of star image (Note 2)
    real(wp),dimension(3),intent(in) :: v !! star's direction cosines (Note 3)
    real(wp),dimension(3),intent(out) :: v01 !! tangent point's direction cosines, Solution 1
    real(wp),dimension(3),intent(out) :: v02 !! tangent point's direction cosines, Solution 2
    integer,intent(out) :: n !! number of solutions:
                             !! * 0 = no solutions returned (Note 4)
                             !! * 1 = only the first solution is useful (Note 5)
                             !! * 2 = both solutions are useful (Note 5)

    real(wp) :: x, y, z, rxy2, xi2, eta2p1, r, rsb, rcb, w2, w, c

    x = v(1)
    y = v(2)
    z = v(3)
    rxy2 = x*x+y*y
    xi2 = xi*xi
    eta2p1 = eta*eta+1.0_wp
    r = sqrt(xi2+eta2p1)
    rsb = r*z
    rcb = r*sqrt(x*x+y*y)
    w2 = rcb*rcb-xi2
    if ( w2 > 0.0_wp ) then
       w = sqrt(w2)
       c = (rsb*eta+w) / (eta2p1*sqrt(rxy2*(w2+xi2)))
       v01(1) = c * (x*w+y*xi)
       v01(2) = c * (y*w-x*xi)
       v01(3) = (rsb-eta*w) / eta2p1
       w = -w
       c = (rsb*eta+w) / (eta2p1*sqrt(rxy2*(w2+xi2)))
       v02(1) = c * (x*w+y*xi)
       v02(2) = c * (y*w-x*xi)
       v02(3) = (rsb-eta*w) / eta2p1
       if ( abs(rsb) < 1.0_wp ) then
          n = 1
       else
          n = 2
       end if
    else
       n = 0
    end if

    end subroutine TPORV