NETGeographicLib  1.50.1
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  * https://geographiclib.sourceforge.io/
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 EquatorialRadius, 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.
101  * @param[in] stdlat standard parallel (degrees), the circle of tangency.
102  * @param[in] k0 azimuthal scale on the standard parallel.
103  * @exception GeographicErr if \e a, (1 &minus; \e f ) \e a, or \e k0 is
104  * not positive.
105  * @exception GeographicErr if \e stdlat is not in [&minus;90&deg;,
106  * 90&deg;].
107  **********************************************************************/
108  AlbersEqualArea(double a, double f, double stdlat, double k0);
109 
110  /**
111  * Constructor with two standard parallels.
112  *
113  * @param[in] a equatorial radius of ellipsoid (meters).
114  * @param[in] f flattening of ellipsoid. Setting \e f = 0 gives a sphere.
115  * Negative \e f gives a prolate ellipsoid.
116  * @param[in] stdlat1 first standard parallel (degrees).
117  * @param[in] stdlat2 second standard parallel (degrees).
118  * @param[in] k1 azimuthal scale on the standard parallels.
119  * @exception GeographicErr if \e a, (1 &minus; \e f ) \e a, or \e k1 is
120  * not positive.
121  * @exception GeographicErr if \e stdlat1 or \e stdlat2 is not in
122  * [&minus;90&deg;, 90&deg;], or if \e stdlat1 and \e stdlat2 are
123  * opposite poles.
124  **********************************************************************/
125  AlbersEqualArea(double a, double f, double stdlat1, double stdlat2, double k1);
126 
127  /**
128  * Constructor with two standard parallels specified by sines and cosines.
129  *
130  * @param[in] a equatorial radius of ellipsoid (meters).
131  * @param[in] f flattening of ellipsoid. Setting \e f = 0 gives a sphere.
132  * Negative \e f gives a prolate ellipsoid.
133  * @param[in] sinlat1 sine of first standard parallel.
134  * @param[in] coslat1 cosine of first standard parallel.
135  * @param[in] sinlat2 sine of second standard parallel.
136  * @param[in] coslat2 cosine of second standard parallel.
137  * @param[in] k1 azimuthal scale on the standard parallels.
138  * @exception GeographicErr if \e a, (1 &minus; \e f ) \e a, or \e k1 is
139  * not positive.
140  * @exception GeographicErr if \e stdlat1 or \e stdlat2 is not in
141  * [&minus;90&deg;, 90&deg;], or if \e stdlat1 and \e stdlat2 are
142  * opposite poles.
143  *
144  * This allows parallels close to the poles to be specified accurately.
145  * This routine computes the latitude of origin and the azimuthal scale at
146  * this latitude. If \e dlat = abs(\e lat2 &minus; \e lat1) &le; 160&deg;,
147  * then the error in the latitude of origin is less than 4.5 &times;
148  * 10<sup>&minus;14</sup>d;.
149  **********************************************************************/
150  AlbersEqualArea(double a, double f,
151  double sinlat1, double coslat1,
152  double sinlat2, double coslat2,
153  double k1);
154 
155  /**
156  * Set the azimuthal scale for the projection.
157  *
158  * @param[in] lat (degrees).
159  * @param[in] k azimuthal scale at latitude \e lat (default 1).
160  * @exception GeographicErr \e k is not positive.
161  * @exception GeographicErr if \e lat is not in (&minus;90&deg;,
162  * 90&deg;).
163  *
164  * This allows a "latitude of conformality" to be specified.
165  **********************************************************************/
166  void SetScale(double lat, double k);
167 
168  /**
169  * Forward projection, from geographic to Lambert conformal conic.
170  *
171  * @param[in] lon0 central meridian longitude (degrees).
172  * @param[in] lat latitude of point (degrees).
173  * @param[in] lon longitude of point (degrees).
174  * @param[out] x easting of point (meters).
175  * @param[out] y northing of point (meters).
176  * @param[out] gamma meridian convergence at point (degrees).
177  * @param[out] k azimuthal scale of projection at point; the radial
178  * scale is the 1/\e k.
179  *
180  * The latitude origin is given by AlbersEqualArea::LatitudeOrigin().
181  * No false easting or northing is added and \e lat should be in the
182  * range [&minus;90&deg;, 90&deg;]. The values of \e x and \e y
183  * returned for points which project to infinity (i.e., one or both of
184  * the poles) will be large but finite.
185  **********************************************************************/
186  void Forward(double lon0, double lat, double lon,
187  [System::Runtime::InteropServices::Out] double% x,
188  [System::Runtime::InteropServices::Out] double% y,
189  [System::Runtime::InteropServices::Out] double% gamma,
190  [System::Runtime::InteropServices::Out] double% k);
191 
192  /**
193  * Reverse projection, from Lambert conformal conic to geographic.
194  *
195  * @param[in] lon0 central meridian longitude (degrees).
196  * @param[in] x easting of point (meters).
197  * @param[in] y northing of point (meters).
198  * @param[out] lat latitude of point (degrees).
199  * @param[out] lon longitude of point (degrees).
200  * @param[out] gamma meridian convergence at point (degrees).
201  * @param[out] k azimuthal scale of projection at point; the radial
202  * scale is the 1/\e k.
203  *
204  * The latitude origin is given by AlbersEqualArea::LatitudeOrigin().
205  * No false easting or northing is added. The value of \e lon returned
206  * is in the range [&minus;180&deg;, 180&deg;). The value of \e lat
207  * returned is in the range [&minus;90&deg;, 90&deg;]. If the input
208  * point is outside the legal projected space the nearest pole is
209  * returned.
210  **********************************************************************/
211  void Reverse(double lon0, double x, double y,
212  [System::Runtime::InteropServices::Out] double% lat,
213  [System::Runtime::InteropServices::Out] double% lon,
214  [System::Runtime::InteropServices::Out] double% gamma,
215  [System::Runtime::InteropServices::Out] double% k);
216 
217  /**
218  * AlbersEqualArea::Forward without returning the convergence and
219  * scale.
220  **********************************************************************/
221  void Forward(double lon0, double lat, double lon,
222  [System::Runtime::InteropServices::Out] double% x,
223  [System::Runtime::InteropServices::Out] double% y);
224 
225  /**
226  * AlbersEqualArea::Reverse without returning the convergence and
227  * scale.
228  **********************************************************************/
229  void Reverse(double lon0, double x, double y,
230  [System::Runtime::InteropServices::Out] double% lat,
231  [System::Runtime::InteropServices::Out] double% lon);
232 
233  /** \name Inspector functions
234  **********************************************************************/
235  ///@{
236  /**
237  * @return \e a the equatorial radius of the ellipsoid (meters). This is
238  * the value used in the constructor.
239  **********************************************************************/
240  property double EquatorialRadius { double get(); }
241 
242  /**
243  * @return \e f the flattening of the ellipsoid. This is the value used in
244  * the constructor.
245  **********************************************************************/
246  property double Flattening { double get(); }
247 
248  /**
249  * @return latitude of the origin for the projection (degrees).
250  *
251  * This is the latitude of minimum azimuthal scale and equals the \e stdlat
252  * in the 1-parallel constructor and lies between \e stdlat1 and \e stdlat2
253  * in the 2-parallel constructors.
254  **********************************************************************/
255  property double OriginLatitude { double get(); }
256 
257  /**
258  * @return central scale for the projection. This is the azimuthal scale
259  * on the latitude of origin.
260  **********************************************************************/
261  property double CentralScale { double get(); }
262  ///@}
263  };
264 } // 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)