UNCLASSIFIED

GeographicTranslator
 All Classes Namespaces Functions Enumerations
EllipsoidLibrary.h
1 // CLASSIFICATION: UNCLASSIFIED
2 
3 #ifndef EllipsoidLibrary_H
4 #define EllipsoidLibrary_H
5 
6 /****************************************************************************/
7 /* RSC IDENTIFIER: Ellipsoid Library
8  *
9  * ABSTRACT
10  *
11  * The purpose of ELLIPSOID is to provide access to ellipsoid parameters
12  * for a collection of common ellipsoids. A particular ellipsoid can be
13  * accessed by using its standard 2-letter code to find its index in the
14  * ellipsoid table. The index can then be used to retrieve the ellipsoid
15  * name and parameters.
16  *
17  * By sequentially retrieving all of the ellipsoid codes and/or names, a
18  * menu of the available ellipsoids can be constructed. The index values
19  * resulting from selections from this menu can then be used to access the
20  * parameters of the selected ellipsoid.
21  *
22  * This component depends on a data file named "ellips.dat", which contains
23  * the ellipsoid parameter values. A copy of this file must be located in
24  * the directory specified by the environment variable "MSPCCS_DATA", if
25  * defined, or else in the current directory, whenever a program containing
26  * this component is executed.
27  *
28  * Additional ellipsoids can be added to this file, either manually or using
29  * the Create_Ellipsoid function. However, if a large number of ellipsoids
30  * are added, the ellipsoid table array size in this component will have to
31  * be increased.
32  *
33  * ERROR HANDLING
34  *
35  * This component checks parameters for valid values. If an invalid value
36  * is found, the error code is combined with the current error code using
37  * the bitwise or. This combining allows multiple error codes to be
38  * returned. The possible error codes are:
39  *
40  * ELLIPSE_NO_ERROR : No errors occured in function
41  * ELLIPSE_FILE_OPEN_ERROR : Ellipsoid file opening error
42  * ELLIPSE_INITIALIZE_ERROR : Ellipsoid table can not initialize
43  * ELLIPSE_TABLE_OVERFLOW_ERROR : Ellipsoid table overflow
44  * ELLIPSE_NOT_INITIALIZED_ERROR: Ellipsoid table not initialized properly
45  * ELLIPSE_INVALID_INDEX_ERROR : Index is an invalid value
46  * ELLIPSE_INVALID_CODE_ERROR : Code was not found in table
47  * ELLIPSE_A_ERROR : Semi-major axis less than or equal to zero
48  * ELLIPSE_INV_F_ERROR : Inverse flattening outside of valid range
49  * (250 to 350)
50  * ELLIPSE_NOT_USERDEF_ERROR : Ellipsoid is not user defined - cannot be
51  * deleted
52  *
53  * REUSE NOTES
54  *
55  * Ellipsoid is intended for reuse by any application that requires Earth
56  * approximating ellipsoids.
57  *
58  * REFERENCES
59  *
60  * Further information on Ellipsoid can be found in the Reuse Manual.
61  *
62  * Ellipsoid originated from : U.S. Army Topographic Engineering Center (USATEC)
63  * Geospatial Information Division (GID)
64  * 7701 Telegraph Road
65  * Alexandria, VA 22310-3864
66  *
67  * LICENSES
68  *
69  * None apply to this component.
70  *
71  * RESTRICTIONS
72  *
73  * Ellipsoid has no restrictions.
74  *
75  * ENVIRONMENT
76  *
77  * Ellipsoid was tested and certified in the following environments
78  *
79  * 1. Solaris 2.5
80  * 2. Windows 95
81  *
82  * MODIFICATIONS
83  *
84  * Date Description
85  * ---- -----------
86  * 11-19-95 Original Code
87  * 17-Jan-97 Moved local constants out of public interface
88  * Improved efficiency in algorithms (GEOTRANS)
89  * 24-May-99 Added user-defined ellipsoids (GEOTRANS for JMTK)
90  * 06-27-06 Moved data file to data directory
91  * 03-09-07 Original C++ Code
92  *
93  */
94 
95 
96 #include "DtccApi.h"
97 
98 namespace MSP
99 {
100  namespace CCS
101  {
102  class EllipsoidLibraryImplementation;
103 
104 
105  /***************************************************************************/
106  /*
107  * DEFINES
108  */
109  class MSP_DTCC_API EllipsoidLibrary
110  {
111  public:
112 
113  /*
114  * The constructor creates an empty list to store the ellipsoid data from ellips.dat,
115  * which is used to build the ellipsoid table.
116  */
117 
118  EllipsoidLibrary( EllipsoidLibraryImplementation* __ellipsoidLibraryImplementation );
119 
120 
122 
123 
124  EllipsoidLibrary& operator=( const EllipsoidLibrary &e );
125 
126 
127  ~EllipsoidLibrary( void );
128 
129 
130  /*
131  * The function defineEllipsoid creates a new ellipsoid with the specified
132  * Code, name, and axes. If the ellipsoid table has not been initialized,
133  * the specified code is already in use, or a new version of the ellips.dat
134  * file cannot be created, an exception is thrown.
135  * Note that the indexes of all ellipsoids in the ellipsoid
136  * table may be changed by this function.
137  *
138  * code : 2-letter ellipsoid code. (input)
139  * name : Name of the new ellipsoid (input)
140  * semiMajorAxis : Semi-major axis, in meters, of new ellipsoid (input)
141  * flattening : Flattening of new ellipsoid. (input)
142  *
143  */
144 
145  void defineEllipsoid( const char* code, const char* name, double semiMajorAxis, double flattening );
146 
147 
148  /*
149  * The function removeEllipsoid deletes a user defined ellipsoid with
150  * the specified Code. If the ellipsoid table has not been created,
151  * the specified code is in use by a user defined datum, or a new version
152  * of the ellips.dat file cannot be created, exception is thrown.
153  * Note that the indexes of all
154  * ellipsoids in the ellipsoid table may be changed by this function.
155  *
156  * code : 2-letter ellipsoid code. (input)
157  *
158  */
159 
160  void removeEllipsoid( const char* code );
161 
162 
163  /*
164  * The function getEllipsoidCount returns the number of ellipsoids in the
165  * ellipsoid table. If the ellipsoid table has not been initialized,
166  * an exception is thrown.
167  *
168  * count : The number of ellipsoids in the ellipsoid table. (output)
169  *
170  */
171 
172  void getEllipsoidCount ( long *count );
173 
174 
175  /*
176  * The function getEllipsoidIndex returns the index of the ellipsoid in
177  * the ellipsoid table with the specified code. If ellipsoid code is not found,
178  * an exception is thrown.
179  *
180  * code : 2-letter ellipsoid code. (input)
181  * index : Index of the ellipsoid in the ellipsoid table with the
182  * specified code (output)
183  *
184  */
185 
186  void getEllipsoidIndex( const char *code, long* index );
187 
188 
189  /*
190  * The Function getEllipsoidInfo returns the 2-letter code and name of the
191  * ellipsoid in the ellipsoid table with the specified index. If index is
192  * invalid, an exception is thrown.
193  *
194  * index : Index of a given ellipsoid in the ellipsoid table (input)
195  * code : 2-letter ellipsoid code. (output)
196  * name : Name of the ellipsoid referencd by index (output)
197  *
198  */
199 
200  void getEllipsoidInfo( const long index, char *code, char *name );
201 
202 
203  /*
204  * The function getEllipsoidParameters returns the semi-major axis and flattening
205  * for the ellipsoid with the specified index. If index is invalid,
206  * an exception is thrown.
207  *
208  * index : Index of a given ellipsoid in the ellipsoid table (input)
209  * a : Semi-major axis, in meters, of ellipsoid (output)
210  * f : Flattening of ellipsoid. (output)
211  *
212  */
213 
214  void getEllipsoidParameters( const long index, double *a, double *f );
215 
216 
217  private:
218 
219  EllipsoidLibraryImplementation* _ellipsoidLibraryImplementation;
220 
221  };
222  }
223 }
224 
225 #endif
226 
227 
228 // CLASSIFICATION: UNCLASSIFIED