NETGeographicLib  1.51
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
.NET Wrapper for GeographicLib::AlbersEqualArea.
void SetScale(double lat, double k)
AlbersEqualArea(StandardTypes type)
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)
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)
AlbersEqualArea(double a, double f, double sinlat1, double coslat1, double sinlat2, double coslat2, double k1)
AlbersEqualArea(double a, double f, double stdlat1, double stdlat2, double k1)
void Forward(double lon0, double lat, double lon, [System::Runtime::InteropServices::Out] double% x, [System::Runtime::InteropServices::Out] double% y)
AlbersEqualArea(double a, double f, double stdlat, double k0)
@ AzimuthalEqualAreaNorth
Lambert azimuthal equal area projection (stdlat = 90°, and k0 = 1)
@ CylindricalEqualArea
cylindrical equal area projection (stdlat = 0, and k0 = 1)
@ AzimuthalEqualAreaSouth
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)