UNCLASSIFIED

GeographicTranslator
 All Classes Namespaces Functions Enumerations
EllipsoidLibraryImplementation.h
1 // CLASSIFICATION: UNCLASSIFIED
2 
3 #ifndef EllipsoidLibraryImplementation_H
4 #define EllipsoidLibraryImplementation_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 <vector>
97 
98 
99 namespace MSP
100 {
101  class CCSThreadMutex;
102  namespace CCS
103  {
104  class Ellipsoid;
105  class DatumLibraryImplementation;
106 
107 
108  /***************************************************************************/
109  /*
110  * DEFINES
111  */
112 
114  {
115  friend class EllipsoidLibraryImplementationCleaner;
116 
117  public:
118 
119  /*
120  * The function getInstance returns an instance of the EllipsoidLibraryImplementation
121  */
122 
123  static EllipsoidLibraryImplementation* getInstance();
124 
125 
126  /*
127  * The function removeInstance removes this EllipsoidLibraryImplementation instance from the
128  * total number of instances.
129  */
130 
131  static void removeInstance();
132 
133 
135 
136 
137  /*
138  * The function defineEllipsoid creates a new ellipsoid with the specified
139  * Code, name, and axes. If the ellipsoid table has not been initialized,
140  * the specified code is already in use, or a new version of the ellips.dat
141  * file cannot be created, an exception is thrown.
142  * Note that the indexes of all ellipsoids in the ellipsoid
143  * table may be changed by this function.
144  *
145  * code : 2-letter ellipsoid code. (input)
146  * name : Name of the new ellipsoid (input)
147  * semiMajorAxis : Semi-major axis, in meters, of new ellipsoid (input)
148  * flattening : Flattening of new ellipsoid. (input)
149  *
150  */
151 
152  void defineEllipsoid( const char* code, const char* name, double semiMajorAxis, double flattening );
153 
154 
155  /*
156  * The function removeEllipsoid deletes a user defined ellipsoid with
157  * the specified Code. If the ellipsoid table has not been created,
158  * the specified code is in use by a user defined datum, or a new version
159  * of the ellips.dat file cannot be created, an exception is thrown.
160  * Note that the indexes of all
161  * ellipsoids in the ellipsoid table may be changed by this function.
162  *
163  * code : 2-letter ellipsoid code. (input)
164  *
165  */
166 
167  void removeEllipsoid( const char* Code );
168 
169 
170  /*
171  * The function ellipsoidCount returns the number of ellipsoids in the
172  * ellipsoid table. If the ellipsoid table has not been initialized,
173  * an exception is thrown.
174  *
175  * count : The number of ellipsoids in the ellipsoid table. (output)
176  *
177  */
178 
179  void ellipsoidCount ( long *count );
180 
181 
182  /*
183  * The function ellipsoidIndex returns the index of the ellipsoid in
184  * the ellipsoid table with the specified code. If ellipsoid code is not found,
185  * an exception is thrown.
186  *
187  * code : 2-letter ellipsoid code. (input)
188  * index : Index of the ellipsoid in the ellipsoid table with the
189  * specified code (output)
190  *
191  */
192 
193  void ellipsoidIndex( const char* code, long* index );
194 
195 
196  /*
197  * The Function ellipsoidCode returns the 2-letter code for the
198  * ellipsoid in the ellipsoid table with the specified index. If index is
199  * invalid, an exception is thrown.
200  *
201  * index : Index of a given ellipsoid in the ellipsoid table (input)
202  * code : 2-letter ellipsoid code. (output)
203  *
204  */
205 
206  void ellipsoidCode( const long index, char *code );
207 
208 
209  /*
210  * The Function ellipsoidName returns the name of the ellipsoid in
211  * the ellipsoid table with the specified index. If index is invalid,
212  * an exception is thrown.
213  *
214  * index : Index of a given ellipsoid.in the ellipsoid table with the
215  * specified index (input)
216  * name : Name of the ellipsoid referencd by index (output)
217  *
218  */
219 
220  void ellipsoidName( const long index, char *name );
221 
222 
223  /*
224  * The function ellipsoidParameters returns the semi-major axis and flattening
225  * for the ellipsoid with the specified index. If index is invalid,
226  * an exception is thrown.
227  *
228  * index : Index of a given ellipsoid in the ellipsoid table (input)
229  * a : Semi-major axis, in meters, of ellipsoid (output)
230  * f : Flattening of ellipsoid. (output)
231  *
232  */
233 
234  void ellipsoidParameters( const long index, double *a, double *f );
235 
236 
237  /*
238  * The function ellipsoidEccentricity2 returns the square of the
239  * eccentricity for the ellipsoid with the specified index. If index is
240  * invalid, an exception is thrown.
241  *
242  * index : Index of a given ellipsoid in the ellipsoid table (input)
243  * eccentricitySquared : Square of eccentricity of ellipsoid (output)
244  *
245  */
246 
247  void ellipsoidEccentricity2( const long index, double *eccentricitySquared );
248 
249 
250  /*
251  * The function ellipsoidUserDefined returns 1 if the ellipsoid is user
252  * defined. Otherwise, 0 is returned. If index is invalid an
253  * exception is thrown.
254  *
255  * index : Index of a given ellipsoid in the ellipsoid table (input)
256  * result : Indicates whether specified ellipsoid is user defined (1)
257  * or not (0) (output)
258  *
259  */
260 
261  void ellipsoidUserDefined( const long index, long *result );
262 
263 
264  /*
265  * The function setDatumLibraryImplementation sets the datum library information
266  * which is needed to ensure a user defined ellipsoid is not in use before being deleted.
267  *
268  * __datumLibraryImplementation : Datum library implementation (input)
269  *
270  */
271 
272  void setDatumLibraryImplementation( DatumLibraryImplementation* __datumLibraryImplementation );
273 
274 
275  protected:
276 
277  /*
278  * The constructor creates an empty list to store the ellipsoid data from ellips.dat,
279  * which is used to build the ellipsoid table.
280  */
281 
283 
284 
286 
287 
289 
290 
291 
292  private:
293 
294  static CCSThreadMutex mutex;
295  static EllipsoidLibraryImplementation* instance;
296  static int instanceCount;
297 
298  std::vector<Ellipsoid*> ellipsoidList;
299 
300 
301  DatumLibraryImplementation* _datumLibraryImplementation;
302 
303  /*
304  * The function loadEllipsoids reads ellipsoid data from ellips.dat
305  * and builds the ellipsoid table from it. If an error occurs,
306  * an exception is thrown.
307  */
308 
309  void loadEllipsoids();
310 
311 
312  /*
313  * Delete the singleton.
314  */
315 
316  static void deleteInstance();
317  };
318  }
319 }
320 
321 #endif
322 
323 // CLASSIFICATION: UNCLASSIFIED