GeographicLib  1.44
CassiniSoldner.hpp
Go to the documentation of this file.
1 /**
2  * \file CassiniSoldner.hpp
3  * \brief Header for GeographicLib::CassiniSoldner class
4  *
5  * Copyright (c) Charles Karney (2009-2015) <charles@karney.com> and licensed
6  * under the MIT/X11 License. For more information, see
7  * http://geographiclib.sourceforge.net/
8  **********************************************************************/
9 
10 #if !defined(GEOGRAPHICLIB_CASSINISOLDNER_HPP)
11 #define GEOGRAPHICLIB_CASSINISOLDNER_HPP 1
12 
16 
17 namespace GeographicLib {
18 
19  /**
20  * \brief Cassini-Soldner projection
21  *
22  * Cassini-Soldner projection centered at an arbitrary position, \e lat0, \e
23  * lon0, on the ellipsoid. This projection is a transverse cylindrical
24  * equidistant projection. The projection from (\e lat, \e lon) to easting
25  * and northing (\e x, \e y) is defined by geodesics as follows. Go north
26  * along a geodesic a distance \e y from the central point; then turn
27  * clockwise 90&deg; and go a distance \e x along a geodesic.
28  * (Although the initial heading is north, this changes to south if the pole
29  * is crossed.) This procedure uniquely defines the reverse projection. The
30  * forward projection is constructed as follows. Find the point (\e lat1, \e
31  * lon1) on the meridian closest to (\e lat, \e lon). Here we consider the
32  * full meridian so that \e lon1 may be either \e lon0 or \e lon0 +
33  * 180&deg;. \e x is the geodesic distance from (\e lat1, \e lon1) to
34  * (\e lat, \e lon), appropriately signed according to which side of the
35  * central meridian (\e lat, \e lon) lies. \e y is the shortest distance
36  * along the meridian from (\e lat0, \e lon0) to (\e lat1, \e lon1), again,
37  * appropriately signed according to the initial heading. [Note that, in the
38  * case of prolate ellipsoids, the shortest meridional path from (\e lat0, \e
39  * lon0) to (\e lat1, \e lon1) may not be the shortest path.] This procedure
40  * uniquely defines the forward projection except for a small class of points
41  * for which there may be two equally short routes for either leg of the
42  * path.
43  *
44  * Because of the properties of geodesics, the (\e x, \e y) grid is
45  * orthogonal. The scale in the easting direction is unity. The scale, \e
46  * k, in the northing direction is unity on the central meridian and
47  * increases away from the central meridian. The projection routines return
48  * \e azi, the true bearing of the easting direction, and \e rk = 1/\e k, the
49  * reciprocal of the scale in the northing direction.
50  *
51  * The conversions all take place using a Geodesic object (by default
52  * Geodesic::WGS84()). For more information on geodesics see \ref geodesic.
53  * The determination of (\e lat1, \e lon1) in the forward projection is by
54  * solving the inverse geodesic problem for (\e lat, \e lon) and its twin
55  * obtained by reflection in the meridional plane. The scale is found by
56  * determining where two neighboring geodesics intersecting the central
57  * meridian at \e lat1 and \e lat1 + \e dlat1 intersect and taking the ratio
58  * of the reduced lengths for the two geodesics between that point and,
59  * respectively, (\e lat1, \e lon1) and (\e lat, \e lon).
60  *
61  * Example of use:
62  * \include example-CassiniSoldner.cpp
63  *
64  * <a href="GeodesicProj.1.html">GeodesicProj</a> is a command-line utility
65  * providing access to the functionality of AzimuthalEquidistant, Gnomonic,
66  * and CassiniSoldner.
67  **********************************************************************/
68 
70  private:
71  typedef Math::real real;
72  Geodesic _earth;
73  GeodesicLine _meridian;
74  real _sbet0, _cbet0;
75  static const unsigned maxit_ = 10;
76 
77  public:
78 
79  /**
80  * Constructor for CassiniSoldner.
81  *
82  * @param[in] earth the Geodesic object to use for geodesic calculations.
83  * By default this uses the WGS84 ellipsoid.
84  *
85  * This constructor makes an "uninitialized" object. Call Reset to set the
86  * central latitude and longitude, prior to calling Forward and Reverse.
87  **********************************************************************/
88  explicit CassiniSoldner(const Geodesic& earth = Geodesic::WGS84());
89 
90  /**
91  * Constructor for CassiniSoldner specifying a center point.
92  *
93  * @param[in] lat0 latitude of center point of projection (degrees).
94  * @param[in] lon0 longitude of center point of projection (degrees).
95  * @param[in] earth the Geodesic object to use for geodesic calculations.
96  * By default this uses the WGS84 ellipsoid.
97  *
98  * \e lat0 should be in the range [&minus;90&deg;, 90&deg;].
99  **********************************************************************/
100  CassiniSoldner(real lat0, real lon0,
101  const Geodesic& earth = Geodesic::WGS84());
102 
103  /**
104  * Set the central point of the projection
105  *
106  * @param[in] lat0 latitude of center point of projection (degrees).
107  * @param[in] lon0 longitude of center point of projection (degrees).
108  *
109  * \e lat0 should be in the range [&minus;90&deg;, 90&deg;].
110  **********************************************************************/
111  void Reset(real lat0, real lon0);
112 
113  /**
114  * Forward projection, from geographic to Cassini-Soldner.
115  *
116  * @param[in] lat latitude of point (degrees).
117  * @param[in] lon longitude of point (degrees).
118  * @param[out] x easting of point (meters).
119  * @param[out] y northing of point (meters).
120  * @param[out] azi azimuth of easting direction at point (degrees).
121  * @param[out] rk reciprocal of azimuthal northing scale at point.
122  *
123  * \e lat should be in the range [&minus;90&deg;, 90&deg;]. A call to
124  * Forward followed by a call to Reverse will return the original (\e lat,
125  * \e lon) (to within roundoff). The routine does nothing if the origin
126  * has not been set.
127  **********************************************************************/
128  void Forward(real lat, real lon,
129  real& x, real& y, real& azi, real& rk) const;
130 
131  /**
132  * Reverse projection, from Cassini-Soldner to geographic.
133  *
134  * @param[in] x easting of point (meters).
135  * @param[in] y northing of point (meters).
136  * @param[out] lat latitude of point (degrees).
137  * @param[out] lon longitude of point (degrees).
138  * @param[out] azi azimuth of easting direction at point (degrees).
139  * @param[out] rk reciprocal of azimuthal northing scale at point.
140  *
141  * A call to Reverse followed by a call to Forward will return the original
142  * (\e x, \e y) (to within roundoff), provided that \e x and \e y are
143  * sufficiently small not to "wrap around" the earth. The routine does
144  * nothing if the origin has not been set.
145  **********************************************************************/
146  void Reverse(real x, real y,
147  real& lat, real& lon, real& azi, real& rk) const;
148 
149  /**
150  * CassiniSoldner::Forward without returning the azimuth and scale.
151  **********************************************************************/
152  void Forward(real lat, real lon,
153  real& x, real& y) const {
154  real azi, rk;
155  Forward(lat, lon, x, y, azi, rk);
156  }
157 
158  /**
159  * CassiniSoldner::Reverse without returning the azimuth and scale.
160  **********************************************************************/
161  void Reverse(real x, real y,
162  real& lat, real& lon) const {
163  real azi, rk;
164  Reverse(x, y, lat, lon, azi, rk);
165  }
166 
167  /** \name Inspector functions
168  **********************************************************************/
169  ///@{
170  /**
171  * @return true if the object has been initialized.
172  **********************************************************************/
173  bool Init() const { return _meridian.Init(); }
174 
175  /**
176  * @return \e lat0 the latitude of origin (degrees).
177  **********************************************************************/
179  { return _meridian.Latitude(); }
180 
181  /**
182  * @return \e lon0 the longitude of origin (degrees).
183  **********************************************************************/
185  { return _meridian.Longitude(); }
186 
187  /**
188  * @return \e a the equatorial radius of the ellipsoid (meters). This is
189  * the value inherited from the Geodesic object used in the constructor.
190  **********************************************************************/
191  Math::real MajorRadius() const { return _earth.MajorRadius(); }
192 
193  /**
194  * @return \e f the flattening of the ellipsoid. This is the value
195  * inherited from the Geodesic object used in the constructor.
196  **********************************************************************/
197  Math::real Flattening() const { return _earth.Flattening(); }
198  ///@}
199 
200  /// \cond SKIP
201  /**
202  * <b>DEPRECATED</b>
203  * @return \e r the inverse flattening of the ellipsoid.
204  **********************************************************************/
205  Math::real InverseFlattening() const
206  { return _earth.InverseFlattening(); }
207  /// \endcond
208  };
209 
210 } // namespace GeographicLib
211 
212 #endif // GEOGRAPHICLIB_CASSINISOLDNER_HPP
Header for GeographicLib::GeodesicLine class.
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:90
Math::real LatitudeOrigin() const
void Reverse(real x, real y, real &lat, real &lon) const
GeographicLib::Math::real real
Definition: GeodSolve.cpp:32
static const Geodesic & WGS84()
Definition: Geodesic.cpp:89
Cassini-Soldner projection.
Math::real MajorRadius() const
Definition: Geodesic.hpp:852
Header for GeographicLib::Geodesic class.
Math::real Longitude() const
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
Math::real Latitude() const
Math::real Flattening() const
Math::real MajorRadius() const
Header for GeographicLib::Constants class.
Math::real Flattening() const
Definition: Geodesic.hpp:858
void Forward(real lat, real lon, real &x, real &y) const
Geodesic calculations
Definition: Geodesic.hpp:171
Math::real LongitudeOrigin() const