/*!
  \file lib/gis/radii.c

  \brief GIS Library - Calculating the Meridional Radius of Curvature
  
  \todo Suggestion: all "lon"s in the file "radii.c" should read as "lat"
  
  Comments:
  on page http://www.mentorsoftwareinc.com/cc/gistips/TIPS0899.HTM
  down where it says "Meridional Radius of Curvature" is the exact formula
  out of "radii.c".
  Quote: "essentially, the radius of curvature, at a specific latitude ...".
  
  See also http://williams.best.vwh.net/ellipsoid/node1.html which has a nice
  picture showning the parametric latitude and phi, the geodetic latitude.
  On the next page,
  http://williams.best.vwh.net/ellipsoid/node2.html, in equation 3, the
  Meridional Radius of Curvature shows up.
  
  So, it looks like you are calculating the Meridional Radius of Curvature
  as a function of GEODETIC LATITUDE.

 Various formulas for the ellipsoid.
 Reference: Map Projections by Peter Richardus and Ron K. Alder
	    University of Illinois Library Call Number: 526.8 R39m
 Parameters are:
  - lon = longitude of the meridian
  - a   = ellipsoid semi-major axis
  - e2  = ellipsoid eccentricity squared


  meridional radius of curvature (p. 16)
  \verbatim
                        2
               a ( 1 - e )
       M = ------------------
                 2   2    3/2
           (1 - e sin lon)
  \endverbatim
  transverse radius of curvature (p. 16)
  \verbatim
                    a
       N = ------------------
                 2   2    1/2
           (1 - e sin lon)
  \endverbatim
  radius of the tangent sphere onto which angles are mapped
  conformally (p. 24)
  \verbatim
       R = sqrt ( N * M )
  \endverbatim
  
  (C) 2001-2009 by the GRASS Development Team

  This program is free software under the GNU General Public License
  (>=v2).  Read the file COPYING that comes with GRASS for details.

  \author CERL
 */

#include <math.h>
#include <grass/gis.h>
#include "pi.h"

/*!
 * \brief Meridional radius of curvature
 *
 * Returns the meridional radius of curvature at a given longitude:
 *
 \f$
 \rho = \frac{a (1-e^2)}{(1-e^2\sin^2 lon)^{3/2}}
 \f$
 *
 *  \param lon longitude
 *  \param a ellipsoid semi-major axis
 *  \param e2 ellipsoid eccentricity squared
 *
 *  \return radius value
 */
double G_meridional_radius_of_curvature(double lon, double a, double e2)
{
    double x;
    double s;

    s = sin(Radians(lon));
    x = 1 - e2 * s * s;

    return a * (1 - e2) / (x * sqrt(x));
}

/*!
 * \brief Transverse radius of curvature
 *
 * Returns the transverse radius of curvature at a given longitude:
 *
 \f$
 \nu = \frac{a}{(1-e^2\sin^2 lon)^{1/2}}
 \f$
 * 
 *  \param lon longitude
 *  \param a ellipsoid semi-major axis
 *  \param e2 ellipsoid eccentricity squared
 *
 *  \return radius value
 */
double G_transverse_radius_of_curvature(double lon, double a, double e2)
{
    double x;
    double s;

    s = sin(Radians(lon));
    x = 1 - e2 * s * s;

    return a / sqrt(x);
}

/*!
 * \brief Radius of conformal tangent sphere
 *
 * Returns the radius of the conformal sphere tangent to ellipsoid at
 * a given longitude:
 *
 \f$
 r = \frac{a (1-e^2)^{1/2}}{(1-e^2\sin^2 lon)}
 \f$
 * 
 *  \param lon longitude
 *  \param a ellipsoid semi-major axis
 *  \param e2 ellipsoid eccentricity squared
 *
 *  \return radius value
 */
double G_radius_of_conformal_tangent_sphere(double lon, double a, double e2)
{
    double x;
    double s;

    s = sin(Radians(lon));
    x = 1 - e2 * s * s;

    return a * sqrt(1 - e2) / x;
}