libntv2.h File Reference

Go to the source code of this file.

Data Structures
struct	NTV2_EXTENT
struct	NTV2_FILE_OV
struct	NTV2_FILE_SF
struct	NTV2_FILE_END
struct	NTV2_FILE_GS
struct	NTV2_REC
struct	NTV2_HDR

Macros
#define	NTV2_VERSION_MAJOR   1
#define	NTV2_VERSION_MINOR   0
#define	NTV2_VERSION_RELEASE   0
#define	NTV2_VERSION_STR   "1.0.0"
#define	NTV2_NULL   0
#define	NTV2_COORD_LON   0
#define	NTV2_COORD_LAT   1
#define	NTV2_MAX_PATH_LEN   256
#define	NTV2_MAX_ERR_LEN   32
#define	NTV2_NAME_LEN   8
#define	NTV2_FILE_BIN_EXTENSION   "gsb"
#define	NTV2_FILE_ASC_EXTENSION   "gsa"
#define	NTV2_FILE_TYPE_UNK   0
#define	NTV2_FILE_TYPE_BIN   1
#define	NTV2_FILE_TYPE_ASC   2
#define	NTV2_ERR_OK   0
#define	NTV2_ERR_NO_MEMORY   1
#define	NTV2_ERR_IOERR   2
#define	NTV2_ERR_NULL_HDR   3
#define	NTV2_ERR_FILE_NEEDS_FIXING   101
#define	NTV2_ERR_START   200
#define	NTV2_ERR_INVALID_LAT_MIN_MAX   201
#define	NTV2_ERR_INVALID_LON_MIN_MAX   202
#define	NTV2_ERR_INVALID_LAT_MIN   203
#define	NTV2_ERR_INVALID_LAT_MAX   204
#define	NTV2_ERR_INVALID_LAT_INC   205
#define	NTV2_ERR_INVALID_LON_INC   206
#define	NTV2_ERR_INVALID_LON_MIN   207
#define	NTV2_ERR_INVALID_LON_MAX   208
#define	NTV2_ERR_UNRECOVERABLE_START   300
#define	NTV2_ERR_INVALID_NUM_OREC   301
#define	NTV2_ERR_INVALID_NUM_SREC   302
#define	NTV2_ERR_INVALID_NUM_FILE   303
#define	NTV2_ERR_INVALID_GS_TYPE   304
#define	NTV2_ERR_INVALID_GS_COUNT   305
#define	NTV2_ERR_INVALID_DELTA   306
#define	NTV2_ERR_INVALID_PARENT_NAME   307
#define	NTV2_ERR_PARENT_NOT_FOUND   308
#define	NTV2_ERR_NO_TOP_LEVEL_PARENT   309
#define	NTV2_ERR_PARENT_LOOP   310
#define	NTV2_ERR_PARENT_OVERLAP   311
#define	NTV2_ERR_SUBFILE_OVERLAP   312
#define	NTV2_ERR_INVALID_EXTENT   313
#define	NTV2_ERR_HDRS_NOT_READ   314
#define	NTV2_ERR_UNKNOWN_FILE_TYPE   315
#define	NTV2_ERR_FILE_NOT_BINARY   316
#define	NTV2_ERR_FILE_NOT_ASCII   317
#define	NTV2_ERR_NULL_PATH   318
#define	NTV2_ERR_ORIG_DATA_NOT_KEPT   319
#define	NTV2_ERR_DATA_NOT_READ   320
#define	NTV2_ERR_CANNOT_OPEN_FILE   321
#define	NTV2_ERR_UNEXPECTED_EOF   322
#define	NTV2_ERR_INVALID_LINE   323
#define	NTV2_FIX_UNPRINTABLE_CHAR   0x01
#define	NTV2_FIX_NAME_LOWERCASE   0x02
#define	NTV2_FIX_NAME_NOT_ALPHA   0x04
#define	NTV2_FIX_BLANK_PARENT_NAME   0x08
#define	NTV2_FIX_BLANK_SUBFILE_NAME   0x10
#define	NTV2_FIX_END_REC_NOT_FOUND   0x20
#define	NTV2_FIX_END_REC_NAME_NOT_ALPHA   0x40
#define	NTV2_FIX_END_REC_PAD_NOT_ZERO   0x80
#define	NTV2_ENDIAN_INP_FILE   0
#define	NTV2_ENDIAN_BIG   1
#define	NTV2_ENDIAN_LITTLE   2
#define	NTV2_ENDIAN_NATIVE   3
#define	NTV2_DUMP_HDRS_EXT   0x01
#define	NTV2_DUMP_HDRS_INT   0x02
#define	NTV2_DUMP_HDRS_BOTH   0x03
#define	NTV2_DUMP_HDRS_SUMMARY   0x04
#define	NTV2_DUMP_DATA   0x10
#define	NTV2_DUMP_DATA_ACC   0x30
#define	NTV2_STATUS_NOTFOUND   0
#define	NTV2_STATUS_CONTAINED   1
#define	NTV2_STATUS_NORTH   2
#define	NTV2_STATUS_WEST   3
#define	NTV2_STATUS_NORTH_WEST   4
#define	NTV2_STATUS_OUTSIDE_CELL   5
#define	NTV2_CVT_FORWARD   1
#define	NTV2_CVT_INVERSE   0
#define	NTV2_CVT_REVERSE(n)   (1 - n)

Typedefs
typedef int	NTV2_BOOL
typedef double	NTV2_COORD [2]
typedef float	NTV2_SHIFT [2]

Functions
const char *	ntv2_errmsg (int err_num, char msg_buf[NTV2_MAX_ERR_LEN])
int	ntv2_filetype (const char *ntv2file)
NTV2_HDR *	ntv2_load_file (const char *ntv2file, NTV2_BOOL keep_orig, NTV2_BOOL read_data, NTV2_EXTENT *extent, int *prc)
void	ntv2_delete (NTV2_HDR *hdr)
int	ntv2_write_file (NTV2_HDR *hdr, const char *path, int byte_order)
int	ntv2_validate (NTV2_HDR *hdr, FILE *fp)
void	ntv2_dump (const NTV2_HDR *hdr, FILE *fp, int mode)
void	ntv2_list (const NTV2_HDR *hdr, FILE *fp, int mode, NTV2_BOOL do_hdr_line)
const NTV2_REC *	ntv2_find_rec (const NTV2_HDR *hdr, double lon, double lat, int *pstatus)
int	ntv2_forward (const NTV2_HDR *hdr, double deg_factor, int n, NTV2_COORD coord[])
int	ntv2_inverse (const NTV2_HDR *hdr, double deg_factor, int n, NTV2_COORD coord[])
int	ntv2_transform (const NTV2_HDR *hdr, double deg_factor, int n, NTV2_COORD coord[], int direction)

Macro Definition Documentation

#define NTV2_COORD_LAT   1

NTV2_COORD latitude

#define NTV2_COORD_LON   0

NTV2_COORD longitude

#define NTV2_CVT_FORWARD   1

Convert data forward

#define NTV2_CVT_INVERSE   0

Convert data inverse

#define NTV2_CVT_REVERSE

(

n

)

(1 - n)

Reverse the direction

#define NTV2_DUMP_DATA   0x10

Dump data for shifts

#define NTV2_DUMP_DATA_ACC   0x30

Dump data for shifts & accuracy

#define NTV2_DUMP_HDRS_BOTH   0x03

Dump hdrs both ways

#define NTV2_DUMP_HDRS_EXT   0x01

Dump hdrs as they are in file

#define NTV2_DUMP_HDRS_INT   0x02

Dump hdrs as they are in memory

#define NTV2_DUMP_HDRS_SUMMARY   0x04

Dump hdr summaries

#define NTV2_ENDIAN_BIG   1

Big-endian byte-order

#define NTV2_ENDIAN_INP_FILE   0

Input-file byte-order

#define NTV2_ENDIAN_LITTLE   2

Little-endian byte-order

#define NTV2_ENDIAN_NATIVE   3

Native byte-order

#define NTV2_ERR_CANNOT_OPEN_FILE   321

#define NTV2_ERR_DATA_NOT_READ   320

#define NTV2_ERR_FILE_NEEDS_FIXING   101

#define NTV2_ERR_FILE_NOT_ASCII   317

#define NTV2_ERR_FILE_NOT_BINARY   316

#define NTV2_ERR_HDRS_NOT_READ   314

#define NTV2_ERR_INVALID_DELTA   306

#define NTV2_ERR_INVALID_EXTENT   313

#define NTV2_ERR_INVALID_GS_COUNT   305

#define NTV2_ERR_INVALID_GS_TYPE   304

#define NTV2_ERR_INVALID_LAT_INC   205

#define NTV2_ERR_INVALID_LAT_MAX   204

#define NTV2_ERR_INVALID_LAT_MIN   203

#define NTV2_ERR_INVALID_LAT_MIN_MAX   201

#define NTV2_ERR_INVALID_LINE   323

#define NTV2_ERR_INVALID_LON_INC   206

#define NTV2_ERR_INVALID_LON_MAX   208

#define NTV2_ERR_INVALID_LON_MIN   207

#define NTV2_ERR_INVALID_LON_MIN_MAX   202

#define NTV2_ERR_INVALID_NUM_FILE   303

#define NTV2_ERR_INVALID_NUM_OREC   301

#define NTV2_ERR_INVALID_NUM_SREC   302

#define NTV2_ERR_INVALID_PARENT_NAME   307

#define NTV2_ERR_IOERR   2

#define NTV2_ERR_NO_MEMORY   1

#define NTV2_ERR_NO_TOP_LEVEL_PARENT   309

#define NTV2_ERR_NULL_HDR   3

#define NTV2_ERR_NULL_PATH   318

#define NTV2_ERR_OK   0

#define NTV2_ERR_ORIG_DATA_NOT_KEPT   319

#define NTV2_ERR_PARENT_LOOP   310

#define NTV2_ERR_PARENT_NOT_FOUND   308

#define NTV2_ERR_PARENT_OVERLAP   311

#define NTV2_ERR_START   200

#define NTV2_ERR_SUBFILE_OVERLAP   312

#define NTV2_ERR_UNEXPECTED_EOF   322

#define NTV2_ERR_UNKNOWN_FILE_TYPE   315

#define NTV2_ERR_UNRECOVERABLE_START   300

#define NTV2_FILE_ASC_EXTENSION   "gsa"

"Grid Shift Ascii"

#define NTV2_FILE_BIN_EXTENSION   "gsb"

"Grid Shift Binary"

#define NTV2_FILE_TYPE_ASC   2

File type is ascii

#define NTV2_FILE_TYPE_BIN   1

File type is binary

#define NTV2_FILE_TYPE_UNK   0

File type is unknown

#define NTV2_FIX_BLANK_PARENT_NAME   0x08

#define NTV2_FIX_BLANK_SUBFILE_NAME   0x10

#define NTV2_FIX_END_REC_NAME_NOT_ALPHA   0x40

#define NTV2_FIX_END_REC_NOT_FOUND   0x20

#define NTV2_FIX_END_REC_PAD_NOT_ZERO   0x80

#define NTV2_FIX_NAME_LOWERCASE   0x02

#define NTV2_FIX_NAME_NOT_ALPHA   0x04

#define NTV2_FIX_UNPRINTABLE_CHAR   0x01

#define NTV2_MAX_ERR_LEN   32

Max err msg length

#define NTV2_MAX_PATH_LEN   256

Max pathname length

#define NTV2_NAME_LEN   8

Blank-padded, no null

#define NTV2_NULL   0

NULL pointer

#define NTV2_STATUS_CONTAINED   1

Point is totally contained

#define NTV2_STATUS_NORTH   2

Point is on North border

#define NTV2_STATUS_NORTH_WEST   4

Point is on North & West border

#define NTV2_STATUS_NOTFOUND   0

Point not found in any record

#define NTV2_STATUS_OUTSIDE_CELL   5

Point is in cell just outside

#define NTV2_STATUS_WEST   3

Point is on West border

#define NTV2_VERSION_MAJOR   1

#define NTV2_VERSION_MINOR   0

#define NTV2_VERSION_RELEASE   0

#define NTV2_VERSION_STR   "1.0.0"

Typedef Documentation

typedef int NTV2_BOOL

Boolean variable

typedef double NTV2_COORD[2]

Lon/lat coordinate

typedef float NTV2_SHIFT[2]

Lat/lon shift/accuracy pair

Function Documentation

void ntv2_delete

(

NTV2_HDR *

hdr

)

Delete a NTv2 object

This method will also close any open stream in the object.

Parameters

hdr	A pointer to a NTV2_HDR object.

void ntv2_dump	(	const NTV2_HDR *	hdr,
		FILE *	fp,
		int	mode
	)

Dump the contents of all headers in a NTv2 file.

Parameters

hdr	A pointer to a NTV2_HDR object.
fp	The stream to dump it to, typically stdout. If NULL, no dump will be done.
mode	The dump mode. This consists of a bit mask of NTV2_DUMP_* values.

const char* ntv2_errmsg	(	int	err_num,
		char	msg_buf[NTV2_MAX_ERR_LEN]
	)

Convert an NTV2 error code to a string.

Currently, these messages are in English, but this call is designed so a user could implement messages in other languages.

Parameters

err_num	The error code to convert.
msg_buf	Buffer to store error message in.

Returns

A pointer to a error-message string.

int ntv2_filetype

(

const char *

ntv2file

)

Determine whether a filename is for a binary or a text file.

This is done solely by checking the filename extension. No examination of the file contents (if any) is done.

Parameters

ntv2file

The filename to query.

Returns

One of the following:

• NTV2_FILE_TYPE_UNK file type is unknown
• NTV2_FILE_TYPE_BIN file type is binary
• NTV2_FILE_TYPE_ASC file type is ascii

const NTV2_REC* ntv2_find_rec	(	const NTV2_HDR *	hdr,
		double	lon,
		double	lat,
		int *	pstatus
	)

Find the best NTv2 sub-file record containing a given point.

This is an internal routine, and is exposed for debugging purposes. Normally, users have no need to call this routine.

Parameters

hdr	A pointer to a NTV2_HDR object.
lon	Longitude of point (in degrees)
lat	Latitude of point (in degrees)
pstatus	Returned status (NTV2_STATUS_*).

Returns

A pointer to a NTV2_REC object or NULL.

int ntv2_forward	(	const NTV2_HDR *	hdr,
		double	deg_factor,
		int	n,
		NTV2_COORD	coord[]
	)

Perform a forward transformation on an array of points.

Parameters

hdr	A pointer to a NTV2_HDR object.
deg_factor	The conversion factor to convert the given coordinates to decimal degrees. The value is degrees-per-unit.
n	Number of points in the array to be transformed.
coord	An array of NTV2_COORD values to be transformed.

Returns

The number of points successfully transformed.

Note that this routine just calls ntv2_transform() with a direction value of NTV2_CVT_FORWARD.

int ntv2_inverse	(	const NTV2_HDR *	hdr,
		double	deg_factor,
		int	n,
		NTV2_COORD	coord[]
	)

Perform an inverse transformation on an array of points.

Parameters

hdr	A pointer to a NTV2_HDR object.
deg_factor	The conversion factor to convert the given coordinates to decimal degrees. The value is degrees-per-unit.
n	Number of points in the array to be transformed.
coord	An array of NTV2_COORD values to be transformed.

Returns

The number of points successfully transformed.

Note that this routine just calls ntv2_transform() with a direction value of NTV2_CVT_INVERSE.

void ntv2_list	(	const NTV2_HDR *	hdr,
		FILE *	fp,
		int	mode,
		NTV2_BOOL	do_hdr_line
	)

List the contents of all headers in a NTv2 file.

This method dumps all headers in a concise list format.

Parameters

hdr	A pointer to a NTV2_HDR object.
fp	The stream to dump it to, typically stdout. If NULL, no dump will be done.
mode	The dump mode. This consists of a bit mask of NTV2_DUMP_* values.
do_hdr_line	TRUE to output a header line.

NTV2_HDR* ntv2_load_file	(	const char *	ntv2file,
		NTV2_BOOL	keep_orig,
		NTV2_BOOL	read_data,
		NTV2_EXTENT *	extent,
		int *	prc
	)

Load a NTv2 file into memory.

Parameters

ntv2file	The name of the NTv2 file to load.
keep_orig	TRUE to keep copies of all external records. A TRUE value will also cause accuracy values to be read in when reading shift values.
read_data	TRUE to read in shift (and optionally accuracy) data. A TRUE value will also result in closing the file after reading, since there is no need to keep it open.
extent	A pointer to an NTV2_EXTENT struct. This pointer may be NULL. This is ignored for text files.
prc	A pointer to a result code. This pointer may be NULL. If successful, it will be set to NTV2_ERR_OK (0). If unsuccessful, it will be set to NTV2_ERR_*.

Returns

A pointer to a NTV2_HDR object or NULL if unsuccessful.

int ntv2_transform	(	const NTV2_HDR *	hdr,
		double	deg_factor,
		int	n,
		NTV2_COORD	coord[],
		int	direction
	)

Perform a transformation on an array of points.

Parameters

hdr	A pointer to a NTV2_HDR object.
deg_factor	The conversion factor to convert the given coordinates to decimal degrees. The value is degrees-per-unit.
n	Number of points in the array to be transformed.
coord	An array of NTV2_COORD values to be transformed.
direction	The direction of the transformation (NTV2_CVT_FORWARD or NTV2_CVT_INVERSE).

Returns

The number of points successfully transformed.

int ntv2_validate	(	NTV2_HDR *	hdr,
		FILE *	fp
	)

Validate all headers in a NTv2 file.

Some unrecoverable errors are found when reading the headers, but this method does an in-depth analysis of all headers and their parent-child relationships.

Note that all validation messages are in English, and no mechanism was setup to localize them.

Rules:

• Each grid is rectangular, and its dimensions must be an integral number of grid intervals.
• Densified grid intervals must be an integral division of its parent grid intervals.
• Densified boundaries must be coincident with its parent grid, enclosing complete cells.
• Densified areas may not overlap each other.

Parameters

hdr	A pointer to a NTV2_HDR object.
fp	A stream to write all messages to. If NULL, no messages will be written, but validation will still be done. Note that in this case, only the last error encountered will be returned, although there may be numerous errors in the file.

Returns

If successful, NTV2_ERR_OK (0). If unsuccessful, NTV2_ERR_*.

int ntv2_write_file	(	NTV2_HDR *	hdr,
		const char *	path,
		int	byte_order
	)

Write out a NTV2_HDR object to a file.

Rules:

• A binary file is always written with the zero-pads in it.
• Sub-files are written recursively just after their parents.
• Parents are written in the order they appeared in the original file.

One advantage of this routine is to be able to write out a file that has been "cut down" by an extent specification. Presumably, this could help keep down memory usage in mobile environments.

This also provides the ability to rewrite a file in order to cleanup all its header info into "standard" form. This could be useful if the file will be used by a different program that isn't as tolerant and forgiving as we are.

This call can also be used to write out a binary file for an object that was read from a text file, and vice-versa.

Parameters

hdr	A pointer to a NTV2_HDR object.
path	The pathname of the file to write. This can name either a binary or a text NTv2 file.
byte_order	Byte order of the output file (NTV2_ENDIAN_*) if binary. A value of NTV2_ENDIAN_INP_FILE means to write the file using the same byte-order as the input file if binary or native byte-order if the input file was a text file. This parameter is ignored when writing text files.

Returns

If successful, NTV2_ERR_OK (0). If unsuccessful, NTV2_ERR_*.