1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
/// 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 function.
///
/// Given:
/// xi,eta f64 rectangular coordinates of star image (Note 2)
/// v [f64; 3] star's direction cosines (Note 3)
///
/// Returned:
/// v01 [f64; 3] tangent point's direction cosines, Solution 1
/// v02 [f64; 3] tangent point's direction cosines, Solution 2
/// count i32 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)
///
/// 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 return value indicates whether the second of the
/// two solutions returned is useful; 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 function 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.