GeographicLib: CassiniSoldner.hpp Source File

GeographicLib 2.7

Loading...
Searching...
No Matches
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-2022) <karney@alum.mit.edu> and licensed
6 * under the MIT/X11 License. For more information, see
7 * https://geographiclib.sourceforge.io/
8 **********************************************************************/
9
10#if !defined(GEOGRAPHICLIB_CASSINISOLDNER_HPP)
11#define GEOGRAPHICLIB_CASSINISOLDNER_HPP 1
12
13#include <GeographicLib/Geodesic.hpp>
14#include <GeographicLib/GeodesicLine.hpp>
15#include <GeographicLib/Constants.hpp>
16
17namespace 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
69 class GEOGRAPHICLIB_EXPORT CassiniSoldner {
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 **********************************************************************/
178 Math::real LatitudeOrigin() const
179 { return _meridian.Latitude(); }
180
181 /**
182 * @return \e lon0 the longitude of origin (degrees).
183 **********************************************************************/
184 Math::real LongitudeOrigin() const
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 EquatorialRadius() const { return _earth.EquatorialRadius(); }
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 };
201
202} // namespace GeographicLib
203
204#endif // GEOGRAPHICLIB_CASSINISOLDNER_HPP
Constants.hpp
Header for GeographicLib::Constants class.
GEOGRAPHICLIB_EXPORT
#define GEOGRAPHICLIB_EXPORT
Definition Constants.hpp:59
GeodesicLine.hpp
Header for GeographicLib::GeodesicLine class.
Geodesic.hpp
Header for GeographicLib::Geodesic class.
GeographicLib::CassiniSoldner::LatitudeOrigin
Math::real LatitudeOrigin() const
Definition CassiniSoldner.hpp:178
GeographicLib::CassiniSoldner::CassiniSoldner
CassiniSoldner(const Geodesic &earth=Geodesic::WGS84())
Definition CassiniSoldner.cpp:16
GeographicLib::CassiniSoldner::Reverse
void Reverse(real x, real y, real &lat, real &lon) const
Definition CassiniSoldner.hpp:161
GeographicLib::CassiniSoldner::Init
bool Init() const
Definition CassiniSoldner.hpp:173
GeographicLib::CassiniSoldner::EquatorialRadius
Math::real EquatorialRadius() const
Definition CassiniSoldner.hpp:191
GeographicLib::CassiniSoldner::Flattening
Math::real Flattening() const
Definition CassiniSoldner.hpp:197
GeographicLib::CassiniSoldner::Forward
void Forward(real lat, real lon, real &x, real &y) const
Definition CassiniSoldner.hpp:152
GeographicLib::CassiniSoldner::LongitudeOrigin
Math::real LongitudeOrigin() const
Definition CassiniSoldner.hpp:184
GeographicLib::CassiniSoldner::Reverse
void Reverse(real x, real y, real &lat, real &lon, real &azi, real &rk) const
Definition CassiniSoldner.cpp:79
GeographicLib::CassiniSoldner::Forward
void Forward(real lat, real lon, real &x, real &y, real &azi, real &rk) const
Definition CassiniSoldner.cpp:34
GeographicLib::CassiniSoldner::Reset
void Reset(real lat0, real lon0)
Definition CassiniSoldner.cpp:23
GeographicLib::GeodesicLine
A geodesic line.
Definition GeodesicLine.hpp:74
GeographicLib::Geodesic
Geodesic calculations
Definition Geodesic.hpp:175
GeographicLib::Geodesic::WGS84
static const Geodesic & WGS84()
Definition Geodesic.cpp:94
GeographicLib::Math::real
double real
Definition Math.hpp:115
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12