Index: trunk/doc/pslib/psLibADD.tex
===================================================================
--- trunk/doc/pslib/psLibADD.tex	(revision 1400)
+++ trunk/doc/pslib/psLibADD.tex	(revision 1548)
@@ -1,3 +1,3 @@
-%%% $Id: psLibADD.tex,v 1.23 2004-08-06 19:06:36 eugene Exp $
+%%% $Id: psLibADD.tex,v 1.24 2004-08-16 19:12:54 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -842,47 +842,134 @@
 \subsubsection{Projections}
 
-The following information is from
+We implement three types of projections, {\em zenithal} and {\em
+cylindrical} and {\em pseudocylindrical} projections.  These three
+require slightly different handling.  Our representations are based on
+the treatment of projections presented by
 \href{http://www.cv.nrao.edu/fits/documents/wcs/wcs.all.ps}{Greisen \&
 Calabretta (1995, ADASS, 4, 233)}.
 
-Let the latitude be $\phi$ and the longitude $\theta$.  The domains of
-these are $-\pi < \phi \le \pi$ and $-\pi/2 \le \theta \le \pi/2$.
+\paragraph{Zenithal Projections}
+
+The {\em zenithal} projections are defined relative to a set of
+spherical coordinates whose pole is the center of the projection
+($\alpha_p, \delta_p$, or \code{psProjection.R, psProjection.D}).  In
+this spherical coordinate system, the coordinate of longitude is
+labeled $\phi$, and has domain of $-\pi < \phi \le \pi$, while the
+latitude, measured from the pole, is labeled $\theta$ and has domain
+$0 \le \theta \le \pi$.
 
 For zenithal projections (e.g.\ Gnomonic and Orthographic) the
 following hold:
-
-\begin{eqnarray}
-x & = & R \sin (\phi) \\
-y & = & -R \cos (\phi)
-\end{eqnarray}
-
+%
+\begin{eqnarray}
+x & = & R_\theta \sin \phi \\
+y & = & -R_\theta \cos \phi
+\end{eqnarray}
+%
 and
-
-\begin{eqnarray}
-R & = & \sqrt{x^2 + y^2} \\
-\phi & = & {\rm arg} (-y,x)
-\end{eqnarray}
-
-\paragraph{Gnomonic}
-
-The Gnomonic projection (``TAN'') is a zenithal projection.
-
-\begin{eqnarray}
-R & = & \cot (\theta) 180^\circ/\pi \\
-\theta & = & \arctan (180^\circ/(\pi R))
-\end{eqnarray}
-
-\paragraph{Orthographic}
-
-The Orthographic projection (``SIN'') is a zenithal projection.
-
-\begin{eqnarray}
-R & = & \cos (\theta) 180^\circ/\pi \\
-\theta & = & \arccos (\pi R / 180^\circ)
-\end{eqnarray}
-
-\paragraph{Cartesian}
-
-The Cartesian projection (``CAR'') is a very simple cylindrical projection.
+%
+\begin{eqnarray}
+R_\theta & = & \sqrt{x^2 + y^2} \\
+\phi     & = & {\rm arg} (-y,x)
+\end{eqnarray}
+%
+The coordinates $x,y$ above are defined to be in angular units (ie,
+radians).  The plate scales ($\rho_x, \rho_y$ = \code{psProjection.Xs,
+psProjection.Ys}) are applied independently to the $x$ and $y$
+coordinates to convert them to the corresponding linear units (ie,
+pixels):
+%
+\begin{eqnarray}
+x_p & = & \rho_x x \\
+y_p & = & \rho_y y \\
+\end{eqnarray}
+
+For an arbitrary projection center, it is necessary to convert the
+spherical coordinates to be projected ($\alpha,\delta$) to the
+projection spherical coordinate system coordinates ($\phi, \theta$)
+from which $x,y$ may be calculated using the relationships above,
+given a prescription for $R_\theta$.  In practice, we construct the
+following useful trigonometric relationships between $\phi$ and
+$\theta$ which may be employed in the equations of $x,y$ above:
+%
+\begin{eqnarray}
+\sin \theta           & = & \sin \delta \sin \delta_p + \cos \delta \cos \delta_p \cos (\alpha - \alpha_p) \\
+\cos \theta \cos \phi & = & \sin \delta \cos \delta_p - \cos \delta \sin \delta_p \cos (\alpha - \alpha_p) \\
+\cos \theta \sin \phi & = & - \cos \delta \sin (\alpha - \alpha_p)
+\end{eqnarray}
+%
+For the inverse transformations, the equivalent relationships are:
+%
+\begin{eqnarray}
+\sin \delta                          & = & \sin \theta \sin \delta_p + \cos \theta \cos \delta_p \cos \phi \\
+\cos \delta \cos (\alpha - \alpha_p) & = & \sin \theta \cos \delta_p - \cos \theta \sin \delta_p \cos \phi \\
+\cos \delta \sin (\alpha - \alpha_p) & = & - \cos \theta \sin (\phi - \phi_p)
+\end{eqnarray}
+%
+From these relationships, we can calculate $\alpha, \delta$ as:
+%
+\begin{eqnarray}
+\alpha - \alpha_p & = & arg (\sin \alpha, \cos \alpha) \\
+\delta            & = & arcsin (sin \delta) \\
+\end{eqnarray}
+%
+The necessary relationships for $\phi$ are equivalent for all zenithal projections:
+%
+\begin{eqnarray}
+R_\theta  & = & \sqrt{x^2 + y^2} \\
+\sin \phi & = & x / R_\theta \\
+\cos \phi & = & -y / R_\theta \\
+\end{eqnarray}
+%
+Note that if $(x,y) = (0,0)$, then $\alpha = \alpha_p, \delta = \delta_p$.
+
+\subparagraph{Gnomonic}
+
+The Gnomonic projection (``TAN'') is a zenithal projection with
+$R_\theta = \cot \theta$.  The resulting relationships for $(x,y)$ and
+for $\sin \theta, \cos \theta$ are:
+
+\begin{eqnarray}
+x           & = & \frac{\cos \theta \sin \phi}{\sin \theta} \\
+y           & = & \frac{-\cos \theta \cos \phi}{\sin \theta} \\
+\sin \theta & = & \zeta / \sqrt (1 + \zeta^2) \\
+\cos \theta & = & 1 / \sqrt (1 + \zeta^2) \\
+\end{eqnarray}
+
+where $\zeta = 1 / R_\theta$.
+
+\subparagraph{Orthographic}
+
+The Orthographic projection (``SIN'') is a zenithal projection with
+$R_\theta = \cos \theta$.  The resulting relationships for $(x,y)$ and
+for $\sin \theta, \cos \theta$ are:
+
+\begin{eqnarray}
+x           & = & \cos \theta \sin \phi \\
+y           & = & -\cos \theta \cos \phi \\
+\sin \theta & = & \sqrt{1 - R_\theta^2} \\
+\cos \theta & = & R_\theta \\
+\end{eqnarray}
+
+\paragraph{Cylindrical and Pseudocylindrical Projections}
+
+The {\em cylindrical} and {\em pseudocylindrical} projections are
+defined relative to a set of cylindrical coordinates whose pole is
+coincident with the pole of the spherical coordinates.  These
+projections are particularly used for full-sky representations, and
+are only defined for projection centers with $\delta_c = 0$.  In this
+spherical coordinate system, the coordinate of longitude is labeled
+$\phi$, and has domain of $-\pi < \phi \le \pi$, while the latitude,
+measured from the pole, is labeled $\theta$ and has domain $0 \le
+\theta \le \pi$.  The projection center longitude, $\alpha_c$
+corresponds to $\phi = 0$, thus the value of $\phi$ is determined as
+$\alpha - \alpha_c$ for all such projections.  The terms
+$\alpha_c,\delta_c$ are equivalent to the elements
+\code{psProjection.R} and \code{psProjection.D}.
+
+\subparagraph{Cartesian}
+
+The Cartesian projection (``CAR'') is a very simple cylindrical with
+the following relationships between $x,y$ and $\phi,\theta$:
 
 \begin{eqnarray}
@@ -891,5 +978,5 @@
 \end{eqnarray}
 
-\paragraph{Mercator}
+\subparagraph{Mercator}
 
 The Mercator projection (``MER'') is a cylindrical projection.
@@ -897,16 +984,16 @@
 \begin{eqnarray}
 x & = & \phi \\
-y & = & \ln \left( \tan (45^\circ + \theta/2) \right) 180^\circ/\pi \\
-{\rm and}\hspace{1cm} \theta & = & 2 \arctan \left( e^{y\pi/180^\circ} \right) - 90^\circ
-\end{eqnarray}
-
-\paragraph{Hammer-Aitoff}
-
-The Hammer-Aitoff projection is a general projection, and is defined:
-
-\begin{eqnarray}
-x & = & 2 \alpha \cos (\theta) \sin (\phi/2) \\
+y & = & \ln \left( \tan (\pi/4 + \theta/2) \right) \\
+{\rm and}\hspace{1cm} \theta & = & 2 \arctan \left( e^y \right) - \pi/2^\circ
+\end{eqnarray}
+
+\subparagraph{Hammer-Aitoff}
+
+The Hammer-Aitoff projection is a pseudocylindrical projection, and is defined:
+
+\begin{eqnarray}
+x & = & 2 \alpha \cos \theta \sin \frac{\phi}{2} \\
 y & = & \alpha \sin \theta \\
-{\rm where}\hspace{1cm} \alpha^{-1} & \equiv & (180^\circ/\pi) \sqrt{\left(1 + \cos (\theta) \cos (\phi/2) \right) / 2}
+{\rm where}\hspace{1cm} \alpha^{-1} & \equiv & \sqrt{\frac{1}{2}\left(1 + \cos \theta \cos \frac{\phi}{2} \right)}
 \end{eqnarray}
 
@@ -914,7 +1001,24 @@
 
 \begin{eqnarray}
-\phi & = & 2 {\rm arg} (2z^2 - 1, xz \pi/360^\circ) \\
-\theta & = & \arcsin (yz\pi/180^\circ) \\
-{\rm where}\hspace{1cm} z & \equiv & \sqrt{1 - (x\pi/720^\circ)^2 - (y\pi/360^\circ)^2}
+\phi & = & 2 {\rm arg} (2z^2 - 1, x z) \\
+\theta & = & \arcsin (yz) \\
+{\rm where}\hspace{1cm} z & \equiv & \sqrt{1 - (x/2)^2 - y^2}
+\end{eqnarray}
+
+\subparagraph{Parabolic}
+
+The Parabolic projection (``PAR'') is a pseudocylindrical projection, and is defined:
+
+\begin{eqnarray}
+x & = & \phi \left( 2 \cos \frac{2 \theta}{3} - 1 \right) \\
+y & = & \pi \sin \frac{\theta}{3} \\
+\end{eqnarray}
+
+And in reverse:
+
+\begin{eqnarray}
+\theta & = & 3 \sin^{-1} \rho \\
+\phi   & = & \frac{x}{1 - 4\rho^2} \\
+{\rm where}\hspace{1cm} \rho & \equiv & y/\pi \\
 \end{eqnarray}