NETGeographicLib  1.43
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Pages
AlbersEqualArea.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/AlbersEqualArea.h
4  * \brief Header for NETGeographicLib::AlbersEqualArea class
5  *
6  * NETGeographicLib is copyright (c) Scott Heiman (2013)
7  * GeographicLib is Copyright (c) Charles Karney (2010-2012)
8  * <charles@karney.com> and licensed under the MIT/X11 License.
9  * For more information, see
10  * http://geographiclib.sourceforge.net/
11  **********************************************************************/
12 
13 namespace NETGeographicLib
14 {
15  /**
16  * \brief .NET Wrapper for GeographicLib::AlbersEqualArea.
17  *
18  * This class allows .NET applications to access
19  * GeographicLib::AlbersEqualArea
20  *
21  * Implementation taken from the report,
22  * - J. P. Snyder,
23  * <a href="http://pubs.er.usgs.gov/usgspubs/pp/pp1395"> Map Projections: A
24  * Working Manual</a>, USGS Professional Paper 1395 (1987),
25  * pp. 101--102.
26  *
27  * This is a implementation of the equations in Snyder except that divided
28  * differences will be [have been] used to transform the expressions into
29  * ones which may be evaluated accurately. [In this implementation, the
30  * projection correctly becomes the cylindrical equal area or the azimuthal
31  * equal area projection when the standard latitude is the equator or a
32  * pole.]
33  *
34  * The ellipsoid parameters, the standard parallels, and the scale on the
35  * standard parallels are set in the constructor. Internally, the case with
36  * two standard parallels is converted into a single standard parallel, the
37  * latitude of minimum azimuthal scale, with an azimuthal scale specified on
38  * this parallel. This latitude is also used as the latitude of origin which
39  * is returned by AlbersEqualArea::OriginLatitude. The azimuthal scale on
40  * the latitude of origin is given by AlbersEqualArea::CentralScale. The
41  * case with two standard parallels at opposite poles is singular and is
42  * disallowed. The central meridian (which is a trivial shift of the
43  * longitude) is specified as the \e lon0 argument of the
44  * AlbersEqualArea::Forward and AlbersEqualArea::Reverse functions.
45  * AlbersEqualArea::Forward and AlbersEqualArea::Reverse also return the
46  * meridian convergence, &gamma;, and azimuthal scale, \e k. A small square
47  * aligned with the cardinal directions is projected to a rectangle with
48  * dimensions \e k (in the E-W direction) and 1/\e k (in the N-S direction).
49  * The E-W sides of the rectangle are oriented &gamma; degrees
50  * counter-clockwise from the \e x axis. There is no provision in this class
51  * for specifying a false easting or false northing or a different latitude
52  * of origin.
53  *
54  * C# Example:
55  * \include example-AlbersEqualArea.cs
56  * Managed C++ Example:
57  * \include example-AlbersEqualArea.cpp
58  * Visual Basic Example:
59  * \include example-AlbersEqualArea.vb
60  *
61  * <B>INTERFACE DIFFERENCES:</B><BR>
62  * A constructor has been provided that creates the standard projections.
63  *
64  * The MajorRadius, Flattening, OriginLatitude, and CentralScale functions
65  * are implemented as properties.
66  **********************************************************************/
67  public ref class AlbersEqualArea
68  {
69  private:
70  // pointer to the unmanaged GeographicLib::AlbersEqualArea
71  GeographicLib::AlbersEqualArea* m_pAlbersEqualArea;
72 
73  // Frees the unmanaged m_pAlbersEqualArea when object is destroyed.
74  !AlbersEqualArea();
75  public:
76  /**
77  Standard AlbersEqualAreaProjections that assume the WGS84 ellipsoid.
78  *********************************************************************/
79  enum class StandardTypes
80  {
81  CylindricalEqualArea, //!< cylindrical equal area projection (stdlat = 0, and \e k0 = 1)
82  AzimuthalEqualAreaNorth, //!< Lambert azimuthal equal area projection (stdlat = 90&deg;, and \e k0 = 1)
83  AzimuthalEqualAreaSouth //!< Lambert azimuthal equal area projection (stdlat = &minus;90&deg;, and \e k0 = 1)
84  };
85 
86  //! \brief Destructor
88 
89  /**!
90  * Constructor for one of the standard types.
91  * @param[in] type The desired standard type.
92  **********************************************************************/
94 
95  /**
96  * Constructor with a single standard parallel.
97  *
98  * @param[in] a equatorial radius of ellipsoid (meters).
99  * @param[in] f flattening of ellipsoid. Setting \e f = 0 gives a sphere.
100  * Negative \e f gives a prolate ellipsoid. If \e f > 1, set flattening
101  * to 1/\e f.
102  * @param[in] stdlat standard parallel (degrees), the circle of tangency.
103  * @param[in] k0 azimuthal scale on the standard parallel.
104  * @exception GeographicErr if \e a, (1 &minus; \e f ) \e a, or \e k0 is
105  * not positive.
106  * @exception GeographicErr if \e stdlat is not in [&minus;90&deg;,
107  * 90&deg;].
108  **********************************************************************/
109  AlbersEqualArea(double a, double f, double stdlat, double k0);
110 
111  /**
112  * Constructor with two standard parallels.
113  *
114  * @param[in] a equatorial radius of ellipsoid (meters).
115  * @param[in] f flattening of ellipsoid. Setting \e f = 0 gives a sphere.
116  * Negative \e f gives a prolate ellipsoid. If \e f > 1, set flattening
117  * to 1/\e f.
118  * @param[in] stdlat1 first standard parallel (degrees).
119  * @param[in] stdlat2 second standard parallel (degrees).
120  * @param[in] k1 azimuthal scale on the standard parallels.
121  * @exception GeographicErr if \e a, (1 &minus; \e f ) \e a, or \e k1 is
122  * not positive.
123  * @exception GeographicErr if \e stdlat1 or \e stdlat2 is not in
124  * [&minus;90&deg;, 90&deg;], or if \e stdlat1 and \e stdlat2 are
125  * opposite poles.
126  **********************************************************************/
127  AlbersEqualArea(double a, double f, double stdlat1, double stdlat2, double k1);
128 
129  /**
130  * Constructor with two standard parallels specified by sines and cosines.
131  *
132  * @param[in] a equatorial radius of ellipsoid (meters).
133  * @param[in] f flattening of ellipsoid. Setting \e f = 0 gives a sphere.
134  * Negative \e f gives a prolate ellipsoid. If \e f > 1, set flattening
135  * to 1/\e f.
136  * @param[in] sinlat1 sine of first standard parallel.
137  * @param[in] coslat1 cosine of first standard parallel.
138  * @param[in] sinlat2 sine of second standard parallel.
139  * @param[in] coslat2 cosine of second standard parallel.
140  * @param[in] k1 azimuthal scale on the standard parallels.
141  * @exception GeographicErr if \e a, (1 &minus; \e f ) \e a, or \e k1 is
142  * not positive.
143  * @exception GeographicErr if \e stdlat1 or \e stdlat2 is not in
144  * [&minus;90&deg;, 90&deg;], or if \e stdlat1 and \e stdlat2 are
145  * opposite poles.
146  *
147  * This allows parallels close to the poles to be specified accurately.
148  * This routine computes the latitude of origin and the azimuthal scale at
149  * this latitude. If \e dlat = abs(\e lat2 &minus; \e lat1) &le; 160&deg;,
150  * then the error in the latitude of origin is less than 4.5 &times;
151  * 10<sup>&minus;14</sup>d;.
152  **********************************************************************/
153  AlbersEqualArea(double a, double f,
154  double sinlat1, double coslat1,
155  double sinlat2, double coslat2,
156  double k1);
157 
158  /**
159  * Set the azimuthal scale for the projection.
160  *
161  * @param[in] lat (degrees).
162  * @param[in] k azimuthal scale at latitude \e lat (default 1).
163  * @exception GeographicErr \e k is not positive.
164  * @exception GeographicErr if \e lat is not in (&minus;90&deg;,
165  * 90&deg;).
166  *
167  * This allows a "latitude of conformality" to be specified.
168  **********************************************************************/
169  void SetScale(double lat, double k);
170 
171  /**
172  * Forward projection, from geographic to Lambert conformal conic.
173  *
174  * @param[in] lon0 central meridian longitude (degrees).
175  * @param[in] lat latitude of point (degrees).
176  * @param[in] lon longitude of point (degrees).
177  * @param[out] x easting of point (meters).
178  * @param[out] y northing of point (meters).
179  * @param[out] gamma meridian convergence at point (degrees).
180  * @param[out] k azimuthal scale of projection at point; the radial
181  * scale is the 1/\e k.
182  *
183  * The latitude origin is given by AlbersEqualArea::LatitudeOrigin(). No
184  * false easting or northing is added and \e lat should be in the range
185  * [&minus;90&deg;, 90&deg;]; \e lon and \e lon0 should be in the
186  * range [&minus;540&deg;, 540&deg;). The values of \e x and \e y
187  * returned for points which project to infinity (i.e., one or both of the
188  * poles) will be large but finite.
189  **********************************************************************/
190  void Forward(double lon0, double lat, double lon,
191  [System::Runtime::InteropServices::Out] double% x,
192  [System::Runtime::InteropServices::Out] double% y,
193  [System::Runtime::InteropServices::Out] double% gamma,
194  [System::Runtime::InteropServices::Out] double% k);
195 
196  /**
197  * Reverse projection, from Lambert conformal conic to geographic.
198  *
199  * @param[in] lon0 central meridian longitude (degrees).
200  * @param[in] x easting of point (meters).
201  * @param[in] y northing of point (meters).
202  * @param[out] lat latitude of point (degrees).
203  * @param[out] lon longitude of point (degrees).
204  * @param[out] gamma meridian convergence at point (degrees).
205  * @param[out] k azimuthal scale of projection at point; the radial
206  * scale is the 1/\e k.
207  *
208  * The latitude origin is given by AlbersEqualArea::LatitudeOrigin(). No
209  * false easting or northing is added. \e lon0 should be in the range
210  * [&minus;540&deg;, 540&deg;). The value of \e lon returned is in
211  * the range [&minus;180&deg;, 180&deg;). The value of \e lat
212  * returned is in the range [&minus;90&deg;, 90&deg;]. If the
213  * input point is outside the legal projected space the nearest pole is
214  * returned.
215  **********************************************************************/
216  void Reverse(double lon0, double x, double y,
217  [System::Runtime::InteropServices::Out] double% lat,
218  [System::Runtime::InteropServices::Out] double% lon,
219  [System::Runtime::InteropServices::Out] double% gamma,
220  [System::Runtime::InteropServices::Out] double% k);
221 
222  /**
223  * AlbersEqualArea::Forward without returning the convergence and
224  * scale.
225  **********************************************************************/
226  void Forward(double lon0, double lat, double lon,
227  [System::Runtime::InteropServices::Out] double% x,
228  [System::Runtime::InteropServices::Out] double% y);
229 
230  /**
231  * AlbersEqualArea::Reverse without returning the convergence and
232  * scale.
233  **********************************************************************/
234  void Reverse(double lon0, double x, double y,
235  [System::Runtime::InteropServices::Out] double% lat,
236  [System::Runtime::InteropServices::Out] double% lon);
237 
238  /** \name Inspector functions
239  **********************************************************************/
240  ///@{
241  /**
242  * @return \e a the equatorial radius of the ellipsoid (meters). This is
243  * the value used in the constructor.
244  **********************************************************************/
245  property double MajorRadius { double get(); }
246 
247  /**
248  * @return \e f the flattening of the ellipsoid. This is the value used in
249  * the constructor.
250  **********************************************************************/
251  property double Flattening { double get(); }
252 
253  /**
254  * @return latitude of the origin for the projection (degrees).
255  *
256  * This is the latitude of minimum azimuthal scale and equals the \e stdlat
257  * in the 1-parallel constructor and lies between \e stdlat1 and \e stdlat2
258  * in the 2-parallel constructors.
259  **********************************************************************/
260  property double OriginLatitude { double get(); }
261 
262  /**
263  * @return central scale for the projection. This is the azimuthal scale
264  * on the latitude of origin.
265  **********************************************************************/
266  property double CentralScale { double get(); }
267  ///@}
268  };
269 } // namespace NETGeographic
void Forward(double lon0, double lat, double lon, [System::Runtime::InteropServices::Out] double% x, [System::Runtime::InteropServices::Out] double% y, [System::Runtime::InteropServices::Out] double% gamma, [System::Runtime::InteropServices::Out] double% k)
void SetScale(double lat, double k)
cylindrical equal area projection (stdlat = 0, and k0 = 1)
.NET Wrapper for GeographicLib::AlbersEqualArea.
Lambert azimuthal equal area projection (stdlat = 90°, and k0 = 1)
void Reverse(double lon0, double x, double y, [System::Runtime::InteropServices::Out] double% lat, [System::Runtime::InteropServices::Out] double% lon, [System::Runtime::InteropServices::Out] double% gamma, [System::Runtime::InteropServices::Out] double% k)
AlbersEqualArea(StandardTypes type)
Lambert azimuthal equal area projection (stdlat = −90°, and k0 = 1)