GEOCON File Processing Routines
libgeocon.h
Go to the documentation of this file.
1 /* ------------------------------------------------------------------------- */
2 /* Copyright 2013 Esri */
3 /* */
4 /* Licensed under the Apache License, Version 2.0 (the "License"); */
5 /* you may not use this file except in compliance with the License. */
6 /* You may obtain a copy of the License at */
7 /* */
8 /* http://www.apache.org/licenses/LICENSE-2.0 */
9 /* */
10 /* Unless required by applicable law or agreed to in writing, software */
11 /* distributed under the License is distributed on an "AS IS" BASIS, */
12 /* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */
13 /* See the License for the specific language governing permissions and */
14 /* limitations under the License. */
15 /* ------------------------------------------------------------------------- */
16 
17 /*---------------------------------------------------------------------------*/
18 /* This is the public header for the GEOCON API, which is a C API providing */
19 /* the ability to read GEOCON files, write GEOCON files, and use GEOCON */
20 /* files to convert coordinates (both forward and inverse). */
21 /* ------------------------------------------------------------------------- */
22 
23 #ifndef LIBGEOCON_H_INCLUDED
24 #define LIBGEOCON_H_INCLUDED
25 
26 #include <stdio.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /* ------------------------------------------------------------------------- */
33 /* version info */
34 /* ------------------------------------------------------------------------- */
35 
36 #define GEOCON_VERSION_MAJOR 1
37 #define GEOCON_VERSION_MINOR 0
38 #define GEOCON_VERSION_RELEASE 0
39 #define GEOCON_VERSION_STR "1.0.0"
40 
41 /*---------------------------------------------------------------------------*/
42 /* external definitions & structs */
43 /*---------------------------------------------------------------------------*/
44 
45 #define FALSE 0
46 #define TRUE 1
47 
48 #define GEOCON_NULL 0
50 #define GEOCON_MAX_PATH_LEN 256
51 #define GEOCON_MAX_ERR_LEN 32
53 typedef int GEOCON_BOOL;
54 typedef double GEOCON_COORD [2];
56 #define GEOCON_COORD_LON 0
57 #define GEOCON_COORD_LAT 1
59 #define GEOCON_COORD_LAM 0
60 #define GEOCON_COORD_PHI 1
62 /*------------------------------------------------------------------------
63  * GEOCON defines
64  */
65 #define GEOCON_HDR_MAGIC 0x47434f4e
66 #define GEOCON_HDR_MAGIC_SWAPPED 0x4e4f4347
68 #define GEOCON_HDR_VERSION 1
69 
70 #define GEOCON_HDR_INFO_LEN 80
71 #define GEOCON_HDR_DATE_LEN 24
72 #define GEOCON_HDR_NAME_LEN 80
74 /* data organization in file */
75 
76 #define GEOCON_LAT_S_TO_N 0
77 #define GEOCON_LAT_N_TO_S 1
79 #define GEOCON_LON_W_TO_E 0
80 #define GEOCON_LON_E_TO_W 1
82 /* filename extensions */
83 
84 #define GEOCON_BIN_EXTENSION "gcb"
85 #define GEOCON_ASC_EXTENSION "gca"
87 #define GEOCON_FILE_TYPE_UNK 0
88 #define GEOCON_FILE_TYPE_BIN 1
89 #define GEOCON_FILE_TYPE_ASC 2
91 /* output byte-order options */
92 
93 #define GEOCON_ENDIAN_INP_FILE 0
94 #define GEOCON_ENDIAN_BIG 1
95 #define GEOCON_ENDIAN_LITTLE 2
96 #define GEOCON_ENDIAN_NATIVE 3
98 /* interpolation types */
99 
100 #define GEOCON_INTERP_DEFAULT 0
101 #define GEOCON_INTERP_BILINEAR 1
102 #define GEOCON_INTERP_BICUBIC 2
103 #define GEOCON_INTERP_BIQUADRATIC 3
104 #define GEOCON_INTERP_NATSPLINE 4
106 /* transformation directions */
107 
108 #define GEOCON_CVT_FORWARD 1
109 #define GEOCON_CVT_INVERSE 0
110 #define GEOCON_CVT_REVERSE(n) (1 - n)
112 /*---------------------------------------------------------------------------*/
113 
119 typedef struct geocon_file_hdr GEOCON_FILE_HDR;
120 struct geocon_file_hdr
121 {
122  int magic;
123  int version;
124  int hdrlen;
125  int reserved;
127  char info [GEOCON_HDR_INFO_LEN];
128  char source[GEOCON_HDR_INFO_LEN];
129  char date [GEOCON_HDR_DATE_LEN];
131  int lat_dir;
132  int lon_dir;
134  int nrows;
135  int ncols;
137  double lat_south;
138  double lat_north;
140  double lon_west;
141  double lon_east;
143  double lat_delta;
144  double lon_delta;
146  double horz_scale;
147  double vert_scale;
149  char from_gcs[GEOCON_HDR_NAME_LEN];
150  char from_vcs[GEOCON_HDR_NAME_LEN];
151  double from_semi_major;
152  double from_flattening;
154  char to_gcs [GEOCON_HDR_NAME_LEN];
155  char to_vcs [GEOCON_HDR_NAME_LEN];
156  double to_semi_major;
157  double to_flattening;
158 };
159 
160 #define GEOCON_FILE_HDR_LEN sizeof(GEOCON_FILE_HDR)
161 
162 /*---------------------------------------------------------------------------*/
168 typedef struct geocon_point GEOCON_POINT;
169 struct geocon_point
170 {
171  float lat_value;
172  float lon_value;
173  float hgt_value;
174 };
175 
176 /*---------------------------------------------------------------------------*/
180 typedef struct geocon_hdr GEOCON_HDR;
181 struct geocon_hdr
182 {
183  GEOCON_FILE_HDR fhdr;
185  char pathname[GEOCON_MAX_PATH_LEN];
186  int filetype;
188  GEOCON_BOOL flip;
189  long points_start;
190  int line_count;
192  /* These values may be different from the file header if
193  an extent was specified when loading data.
194  */
195  int nrows;
196  int ncols;
198  double lat_min;
199  double lat_max;
200  double lon_min;
201  double lon_max;
203  /* These values are copied from the file header for convienence.
204  However, they may be changed if you want the point data written
205  in a different order.
206  */
207  int lat_dir;
208  int lon_dir;
210  /* These values are copied from the file header for convienence. */
211  double lat_delta;
212  double lon_delta;
214  double horz_scale;
215  double vert_scale;
217  /* Values for "phantom cells" around our grid. */
218  double lat_min_ghost;
219  double lat_max_ghost;
220  double lon_min_ghost;
221  double lon_max_ghost;
223  /* This will be null if data is in memory. */
224  FILE * fp;
226  /* This should be used if mutex control is needed
227  for multi-threaded access to the file when
228  transforming points and reading data on-the-fly.
229  This mutex does not need to be recursive.
230  */
231  void * mutex;
233  /* If reading data on the fly, this is null.
234  This array is always stored with points going from SW to NE.
235  */
236  GEOCON_POINT *points;
237 };
238 
239 /*---------------------------------------------------------------------------*/
253 typedef struct geocon_extent GEOCON_EXTENT;
254 struct geocon_extent
255 {
256  /* lower-left corner */
257  double slat;
258  double wlon;
260  /* upper-right corner */
261  double nlat;
262  double elon;
263 };
264 
265 /*---------------------------------------------------------------------------*/
266 /* GEOCON error codes */
267 /*---------------------------------------------------------------------------*/
268 
269 #define GEOCON_ERR_OK 0
270 
271 #define GEOCON_ERR_NO_MEMORY 1
272 #define GEOCON_ERR_IOERR 2
273 #define GEOCON_ERR_NULL_PARAMETER 3
274 
275 #define GEOCON_ERR_INVALID_EXTENT 4
276 #define GEOCON_ERR_FILE_NOT_FOUND 5
277 #define GEOCON_ERR_INVALID_FILE 6
278 #define GEOCON_ERR_CANNOT_OPEN_FILE 7
279 #define GEOCON_ERR_UNKNOWN_FILETYPE 8
280 #define GEOCON_ERR_UNEXPECTED_EOF 9
281 #define GEOCON_ERR_INVALID_TOKEN_CNT 10
282 
283 /*---------------------------------------------------------------------------*/
284 /* GEOCON routines */
285 /*---------------------------------------------------------------------------*/
286 
287 /*---------------------------------------------------------------------------*/
303 extern int geocon_filetype(
304  const char *pathname);
305 
306 /*---------------------------------------------------------------------------*/
318 extern const char * geocon_errmsg(
319  int err_num,
320  char msg_buf[]);
321 
322 /*---------------------------------------------------------------------------*/
331 extern GEOCON_HDR * geocon_create();
332 
333 /*---------------------------------------------------------------------------*/
356 extern GEOCON_HDR * geocon_load(
357  const char *pathname,
358  GEOCON_EXTENT *extent,
359  GEOCON_BOOL load_data,
360  int *prc);
361 
362 /*---------------------------------------------------------------------------*/
390 extern int geocon_write(
391  const GEOCON_HDR *hdr,
392  const char *pathname,
393  int byte_order,
394  int *prc);
395 
396 /*---------------------------------------------------------------------------*/
404 extern void geocon_delete(
405  GEOCON_HDR *hdr);
406 
407 /*---------------------------------------------------------------------------*/
420 extern void geocon_list_hdr(
421  const GEOCON_HDR *hdr,
422  FILE *fp,
423  GEOCON_BOOL do_hdr_line);
424 
425 /*---------------------------------------------------------------------------*/
436 extern void geocon_dump_hdr(
437  const GEOCON_HDR *hdr,
438  FILE *fp);
439 
440 /*---------------------------------------------------------------------------*/
452 extern void geocon_dump_data(
453  const GEOCON_HDR *hdr,
454  FILE *fp);
455 
456 /*---------------------------------------------------------------------------*/
494 extern int geocon_forward(
495  const GEOCON_HDR *hdr,
496  int interp,
497  double deg_factor,
498  double hgt_factor,
499  int n,
500  GEOCON_COORD coord[],
501  double h[]);
502 
503 /*---------------------------------------------------------------------------*/
541 extern int geocon_inverse(
542  const GEOCON_HDR *hdr,
543  int interp,
544  double deg_factor,
545  double hgt_factor,
546  int n,
547  GEOCON_COORD coord[],
548  double h[]);
549 
550 /*---------------------------------------------------------------------------*/
591 extern int geocon_transform(
592  const GEOCON_HDR *hdr,
593  int interp,
594  double deg_factor,
595  double hgt_factor,
596  int n,
597  GEOCON_COORD coord[],
598  double h[],
599  int direction);
600 
601 /*---------------------------------------------------------------------------*/
602 
603 #ifdef __cplusplus
604 }
605 #endif
606 
607 #endif /* LIBGEOCON_H_INCLUDED */
Generated on Wed Aug 28 2013 14:58:52 for GEOCON File Processing Routines by   doxygen 1.8.2