NTv2 File Processing Routines
libntv2.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 /* public header for the libntv2 library */
19 /* ------------------------------------------------------------------------- */
20 
21 #ifndef LIBNTV2_INCLUDED
22 #define LIBNTV2_INCLUDED
23 
24 #include <stdio.h>
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 /* ---------------------------------------------------------------------- */
31 /* version info */
32 /* ---------------------------------------------------------------------- */
33 
34 #define NTV2_VERSION_MAJOR 1
35 #define NTV2_VERSION_MINOR 0
36 #define NTV2_VERSION_RELEASE 0
37 #define NTV2_VERSION_STR "1.0.0"
38 
39 /*------------------------------------------------------------------------*/
40 /* external definitions & structs */
41 /*------------------------------------------------------------------------*/
42 
43 #define FALSE 0
44 #define TRUE 1
45 
46 #define NTV2_NULL 0
48 #define NTV2_COORD_LON 0
49 #define NTV2_COORD_LAT 1
51 #define NTV2_MAX_PATH_LEN 256
52 #define NTV2_MAX_ERR_LEN 32
54 typedef int NTV2_BOOL;
55 typedef double NTV2_COORD [2];
57 /*---------------------------------------------------------------------*/
58 
74 typedef struct ntv2_extent NTV2_EXTENT;
75 struct ntv2_extent
76 {
77  /* lower-left corner */
78  double wlon;
79  double slat;
81  /* upper-right corner */
82  double elon;
83  double nlat;
84 };
85 
86 /*------------------------------------------------------------------------*/
87 /* NTv2 file layout */
88 /* */
89 /* A NTv2 file (either binary or text) is laid out as follows: */
90 /* */
91 /* overview record */
92 /* */
93 /* sub-file record 1 */
94 /* gs_count grid-shift records */
95 /* ... */
96 /* sub-file record n (if present) */
97 /* gs_count grid-shift records */
98 /* */
99 /* end record */
100 /*------------------------------------------------------------------------*/
101 
102 #define NTV2_NAME_LEN 8
104 #define NTV2_FILE_BIN_EXTENSION "gsb"
105 #define NTV2_FILE_ASC_EXTENSION "gsa"
107 #define NTV2_FILE_TYPE_UNK 0
108 #define NTV2_FILE_TYPE_BIN 1
109 #define NTV2_FILE_TYPE_ASC 2
111 /*---------------------------------------------------------------------*/
112 
125 typedef struct ntv2_file_ov NTV2_FILE_OV;
126 struct ntv2_file_ov
127 {
128  char n_num_orec [NTV2_NAME_LEN];
129  int i_num_orec;
130  int p_num_orec;
132  char n_num_srec [NTV2_NAME_LEN];
133  int i_num_srec;
134  int p_num_srec;
136  char n_num_file [NTV2_NAME_LEN];
137  int i_num_file;
138  int p_num_file;
140  char n_gs_type [NTV2_NAME_LEN];
141  char s_gs_type [NTV2_NAME_LEN];
143  char n_version [NTV2_NAME_LEN];
144  char s_version [NTV2_NAME_LEN];
146  char n_system_f [NTV2_NAME_LEN];
147  char s_system_f [NTV2_NAME_LEN];
149  char n_system_t [NTV2_NAME_LEN];
150  char s_system_t [NTV2_NAME_LEN];
152  char n_major_f [NTV2_NAME_LEN];
153  double d_major_f;
155  char n_minor_f [NTV2_NAME_LEN];
156  double d_minor_f;
158  char n_major_t [NTV2_NAME_LEN];
159  double d_major_t;
161  char n_minor_t [NTV2_NAME_LEN];
162  double d_minor_t;
163 };
164 
165 /*---------------------------------------------------------------------*/
182 typedef struct ntv2_file_sf NTV2_FILE_SF;
183 struct ntv2_file_sf
184 {
185  char n_sub_name [NTV2_NAME_LEN];
186  char s_sub_name [NTV2_NAME_LEN];
188  char n_parent [NTV2_NAME_LEN];
189  char s_parent [NTV2_NAME_LEN];
191  char n_created [NTV2_NAME_LEN];
192  char s_created [NTV2_NAME_LEN];
194  char n_updated [NTV2_NAME_LEN];
195  char s_updated [NTV2_NAME_LEN];
197  char n_s_lat [NTV2_NAME_LEN];
198  double d_s_lat;
200  char n_n_lat [NTV2_NAME_LEN];
201  double d_n_lat;
203  char n_e_lon [NTV2_NAME_LEN];
204  double d_e_lon;
206  char n_w_lon [NTV2_NAME_LEN];
207  double d_w_lon;
209  char n_lat_inc [NTV2_NAME_LEN];
210  double d_lat_inc;
212  char n_lon_inc [NTV2_NAME_LEN];
213  double d_lon_inc;
215  char n_gs_count [NTV2_NAME_LEN];
216  int i_gs_count;
217  int p_gs_count;
218 };
219 
220 /*---------------------------------------------------------------------*/
235 typedef struct ntv2_file_end NTV2_FILE_END;
236 struct ntv2_file_end
237 {
238  char n_end [NTV2_NAME_LEN];
239  char filler [NTV2_NAME_LEN];
241 };
242 
243 /*---------------------------------------------------------------------*/
251 typedef struct ntv2_file_gs NTV2_FILE_GS;
252 struct ntv2_file_gs
253 {
254  float f_lat_shift;
255  float f_lon_shift;
256  float f_lat_accuracy;
257  float f_lon_accuracy;
258 };
259 
260 /*------------------------------------------------------------------------*/
261 /* NTv2 internal structs */
262 /*------------------------------------------------------------------------*/
263 
264 /*---------------------------------------------------------------------*/
265 
266 typedef float NTV2_SHIFT [2];
275 typedef struct ntv2_rec NTV2_REC;
276 struct ntv2_rec
277 {
278  char record_name[NTV2_NAME_LEN+4];
279  char parent_name[NTV2_NAME_LEN+4];
281  NTV2_REC * parent;
282  NTV2_REC * sub;
283  NTV2_REC * next;
285  NTV2_BOOL active;
287  int num_subs;
288  int rec_num;
290  int num;
291  int nrows;
292  int ncols;
294  double lat_min;
295  double lat_max;
296  double lat_inc;
298  double lon_min;
299  double lon_max;
300  double lon_inc;
302  /* These fields are only used for binary files. */
303 
304  long offset;
305  int sskip;
306  int nskip;
307  int wskip;
308  int eskip;
310  /* This may be null if data is to be read on-the-fly. */
311 
312  NTV2_SHIFT * shifts;
314  /* This may be null if not wanted. Always null if shifts is null. */
315 
316  NTV2_SHIFT * accurs;
317 };
318 
319 /*---------------------------------------------------------------------*/
325 typedef struct ntv2_hdr NTV2_HDR;
326 struct ntv2_hdr
327 {
328  char path [NTV2_MAX_PATH_LEN];
330  int file_type;
332  int num_recs;
333  int num_parents;
335  NTV2_BOOL keep_orig;
336  NTV2_BOOL pads_present;
337  NTV2_BOOL swap_data;
338  int fixed;
340  double hdr_conv;
341  double dat_conv;
342  char gs_type [NTV2_NAME_LEN+4];
346  /* These are the mins and maxes across all sub-files */
347 
348  double lat_min;
349  double lat_max;
350  double lon_min;
351  double lon_max;
353  NTV2_REC * recs;
354  NTV2_REC * first_parent;
356  /* This will be null if data is in memory. */
357 
358  FILE * fp;
360  /* This should be used if mutex control is needed */
361  /* for multi-threaded access to the file when */
362  /* transforming points and reading data on-the-fly. */
363  /* This mutex does not need to be recursive. */
364 
365  void * mutex;
367  /* These may be null if not wanted. */
368 
369  NTV2_FILE_OV * overview;
370  NTV2_FILE_SF * subfiles;
371 };
372 
373 /*------------------------------------------------------------------------*/
374 /* NTv2 error codes */
375 /*------------------------------------------------------------------------*/
376 
377 #define NTV2_ERR_OK 0
378 
379 /* generic errors */
380 #define NTV2_ERR_NO_MEMORY 1
381 #define NTV2_ERR_IOERR 2
382 #define NTV2_ERR_NULL_HDR 3
383 
384 /* warnings */
385 #define NTV2_ERR_FILE_NEEDS_FIXING 101
386 
387 /* read errors that may be ignored */
388 #define NTV2_ERR_START 200
389 
390 #define NTV2_ERR_INVALID_LAT_MIN_MAX 201
391 #define NTV2_ERR_INVALID_LON_MIN_MAX 202
392 #define NTV2_ERR_INVALID_LAT_MIN 203
393 #define NTV2_ERR_INVALID_LAT_MAX 204
394 #define NTV2_ERR_INVALID_LAT_INC 205
395 #define NTV2_ERR_INVALID_LON_INC 206
396 #define NTV2_ERR_INVALID_LON_MIN 207
397 #define NTV2_ERR_INVALID_LON_MAX 208
398 
399 /* unrecoverable errors */
400 #define NTV2_ERR_UNRECOVERABLE_START 300
401 
402 #define NTV2_ERR_INVALID_NUM_OREC 301
403 #define NTV2_ERR_INVALID_NUM_SREC 302
404 #define NTV2_ERR_INVALID_NUM_FILE 303
405 #define NTV2_ERR_INVALID_GS_TYPE 304
406 #define NTV2_ERR_INVALID_GS_COUNT 305
407 #define NTV2_ERR_INVALID_DELTA 306
408 #define NTV2_ERR_INVALID_PARENT_NAME 307
409 #define NTV2_ERR_PARENT_NOT_FOUND 308
410 #define NTV2_ERR_NO_TOP_LEVEL_PARENT 309
411 #define NTV2_ERR_PARENT_LOOP 310
412 #define NTV2_ERR_PARENT_OVERLAP 311
413 #define NTV2_ERR_SUBFILE_OVERLAP 312
414 #define NTV2_ERR_INVALID_EXTENT 313
415 #define NTV2_ERR_HDRS_NOT_READ 314
416 #define NTV2_ERR_UNKNOWN_FILE_TYPE 315
417 #define NTV2_ERR_FILE_NOT_BINARY 316
418 #define NTV2_ERR_FILE_NOT_ASCII 317
419 #define NTV2_ERR_NULL_PATH 318
420 #define NTV2_ERR_ORIG_DATA_NOT_KEPT 319
421 #define NTV2_ERR_DATA_NOT_READ 320
422 #define NTV2_ERR_CANNOT_OPEN_FILE 321
423 #define NTV2_ERR_UNEXPECTED_EOF 322
424 #define NTV2_ERR_INVALID_LINE 323
425 
426 /* fix header reasons (bit-mask) */
427 
428 #define NTV2_FIX_UNPRINTABLE_CHAR 0x01
429 #define NTV2_FIX_NAME_LOWERCASE 0x02
430 #define NTV2_FIX_NAME_NOT_ALPHA 0x04
431 #define NTV2_FIX_BLANK_PARENT_NAME 0x08
432 #define NTV2_FIX_BLANK_SUBFILE_NAME 0x10
433 #define NTV2_FIX_END_REC_NOT_FOUND 0x20
434 #define NTV2_FIX_END_REC_NAME_NOT_ALPHA 0x40
435 #define NTV2_FIX_END_REC_PAD_NOT_ZERO 0x80
436 
448 extern const char * ntv2_errmsg(
449  int err_num,
450  char msg_buf[NTV2_MAX_ERR_LEN]);
451 
452 /*------------------------------------------------------------------------*/
453 /* NTv2 file methods */
454 /*------------------------------------------------------------------------*/
455 
456 /*---------------------------------------------------------------------*/
472 extern int ntv2_filetype(
473  const char *ntv2file);
474 
475 /*---------------------------------------------------------------------*/
502 extern NTV2_HDR * ntv2_load_file(
503  const char * ntv2file,
504  NTV2_BOOL keep_orig,
505  NTV2_BOOL read_data,
506  NTV2_EXTENT * extent,
507  int * prc);
508 
509 /*---------------------------------------------------------------------*/
517 extern void ntv2_delete(
518  NTV2_HDR *hdr);
519 
520 /*---------------------------------------------------------------------*/
521 
522 #define NTV2_ENDIAN_INP_FILE 0
523 #define NTV2_ENDIAN_BIG 1
524 #define NTV2_ENDIAN_LITTLE 2
525 #define NTV2_ENDIAN_NATIVE 3
564 extern int ntv2_write_file(
565  NTV2_HDR *hdr,
566  const char *path,
567  int byte_order);
568 
569 /*---------------------------------------------------------------------*/
603 extern int ntv2_validate(
604  NTV2_HDR *hdr,
605  FILE *fp);
606 
607 /*---------------------------------------------------------------------*/
608 
609 #define NTV2_DUMP_HDRS_EXT 0x01
610 #define NTV2_DUMP_HDRS_INT 0x02
611 #define NTV2_DUMP_HDRS_BOTH 0x03
612 #define NTV2_DUMP_HDRS_SUMMARY 0x04
613 #define NTV2_DUMP_DATA 0x10
614 #define NTV2_DUMP_DATA_ACC 0x30
627 extern void ntv2_dump(
628  const NTV2_HDR *hdr,
629  FILE *fp,
630  int mode);
631 
632 /*---------------------------------------------------------------------*/
648 extern void ntv2_list(
649  const NTV2_HDR *hdr,
650  FILE *fp,
651  int mode,
652  NTV2_BOOL do_hdr_line);
653 
654 /*------------------------------------------------------------------------*/
655 /* NTv2 transformation methods */
656 /*------------------------------------------------------------------------*/
657 
658 /*---------------------------------------------------------------------*/
659 
660 #define NTV2_STATUS_NOTFOUND 0
661 #define NTV2_STATUS_CONTAINED 1
662 #define NTV2_STATUS_NORTH 2
663 #define NTV2_STATUS_WEST 3
664 #define NTV2_STATUS_NORTH_WEST 4
665 #define NTV2_STATUS_OUTSIDE_CELL 5
680 extern const NTV2_REC * ntv2_find_rec(
681  const NTV2_HDR *hdr,
682  double lon,
683  double lat,
684  int *pstatus);
685 
686 /*---------------------------------------------------------------------*/
705 extern int ntv2_forward(
706  const NTV2_HDR *hdr,
707  double deg_factor,
708  int n,
709  NTV2_COORD coord[]);
710 
711 /*---------------------------------------------------------------------*/
730 extern int ntv2_inverse(
731  const NTV2_HDR *hdr,
732  double deg_factor,
733  int n,
734  NTV2_COORD coord[]);
735 
736 /*---------------------------------------------------------------------*/
737 
738 #define NTV2_CVT_FORWARD 1
739 #define NTV2_CVT_INVERSE 0
740 #define NTV2_CVT_REVERSE(n) (1 - n)
760 extern int ntv2_transform(
761  const NTV2_HDR *hdr,
762  double deg_factor,
763  int n,
764  NTV2_COORD coord[],
765  int direction);
766 
767 /*---------------------------------------------------------------------*/
768 
769 #ifdef __cplusplus
770 }
771 #endif
772 
773 #endif /* LIBNTV2_INCLUDED */
Generated on Wed Aug 7 2013 13:28:26 for NTv2 File Processing Routines by   doxygen 1.8.2