libgeocon.h File Reference

Go to the source code of this file.

Data Structures
struct	GEOCON_FILE_HDR
struct	GEOCON_POINT
struct	GEOCON_HDR
struct	GEOCON_EXTENT

Macros
#define	GEOCON_VERSION_MAJOR   1
#define	GEOCON_VERSION_MINOR   0
#define	GEOCON_VERSION_RELEASE   0
#define	GEOCON_VERSION_STR   "1.0.0"
#define	GEOCON_NULL   0
#define	GEOCON_MAX_PATH_LEN   256
#define	GEOCON_MAX_ERR_LEN   32
#define	GEOCON_COORD_LON   0
#define	GEOCON_COORD_LAT   1
#define	GEOCON_COORD_LAM   0
#define	GEOCON_COORD_PHI   1
#define	GEOCON_HDR_MAGIC   0x47434f4e
#define	GEOCON_HDR_MAGIC_SWAPPED   0x4e4f4347
#define	GEOCON_HDR_VERSION   1
#define	GEOCON_HDR_INFO_LEN   80
#define	GEOCON_HDR_DATE_LEN   24
#define	GEOCON_HDR_NAME_LEN   80
#define	GEOCON_LAT_S_TO_N   0
#define	GEOCON_LAT_N_TO_S   1
#define	GEOCON_LON_W_TO_E   0
#define	GEOCON_LON_E_TO_W   1
#define	GEOCON_BIN_EXTENSION   "gcb"
#define	GEOCON_ASC_EXTENSION   "gca"
#define	GEOCON_FILE_TYPE_UNK   0
#define	GEOCON_FILE_TYPE_BIN   1
#define	GEOCON_FILE_TYPE_ASC   2
#define	GEOCON_ENDIAN_INP_FILE   0
#define	GEOCON_ENDIAN_BIG   1
#define	GEOCON_ENDIAN_LITTLE   2
#define	GEOCON_ENDIAN_NATIVE   3
#define	GEOCON_INTERP_DEFAULT   0
#define	GEOCON_INTERP_BILINEAR   1
#define	GEOCON_INTERP_BICUBIC   2
#define	GEOCON_INTERP_BIQUADRATIC   3
#define	GEOCON_INTERP_NATSPLINE   4
#define	GEOCON_CVT_FORWARD   1
#define	GEOCON_CVT_INVERSE   0
#define	GEOCON_CVT_REVERSE(n)   (1 - n)
#define	GEOCON_FILE_HDR_LEN   sizeof(GEOCON_FILE_HDR)
#define	GEOCON_ERR_OK   0
#define	GEOCON_ERR_NO_MEMORY   1
#define	GEOCON_ERR_IOERR   2
#define	GEOCON_ERR_NULL_PARAMETER   3
#define	GEOCON_ERR_INVALID_EXTENT   4
#define	GEOCON_ERR_FILE_NOT_FOUND   5
#define	GEOCON_ERR_INVALID_FILE   6
#define	GEOCON_ERR_CANNOT_OPEN_FILE   7
#define	GEOCON_ERR_UNKNOWN_FILETYPE   8
#define	GEOCON_ERR_UNEXPECTED_EOF   9
#define	GEOCON_ERR_INVALID_TOKEN_CNT   10

Typedefs
typedef int	GEOCON_BOOL
typedef double	GEOCON_COORD [2]

Functions
int	geocon_filetype (const char *pathname)
const char *	geocon_errmsg (int err_num, char msg_buf[])
GEOCON_HDR *	geocon_create ()
GEOCON_HDR *	geocon_load (const char *pathname, GEOCON_EXTENT *extent, GEOCON_BOOL load_data, int *prc)
int	geocon_write (const GEOCON_HDR *hdr, const char *pathname, int byte_order, int *prc)
void	geocon_delete (GEOCON_HDR *hdr)
void	geocon_list_hdr (const GEOCON_HDR *hdr, FILE *fp, GEOCON_BOOL do_hdr_line)
void	geocon_dump_hdr (const GEOCON_HDR *hdr, FILE *fp)
void	geocon_dump_data (const GEOCON_HDR *hdr, FILE *fp)
int	geocon_forward (const GEOCON_HDR *hdr, int interp, double deg_factor, double hgt_factor, int n, GEOCON_COORD coord[], double h[])
int	geocon_inverse (const GEOCON_HDR *hdr, int interp, double deg_factor, double hgt_factor, int n, GEOCON_COORD coord[], double h[])
int	geocon_transform (const GEOCON_HDR *hdr, int interp, double deg_factor, double hgt_factor, int n, GEOCON_COORD coord[], double h[], int direction)

Macro Definition Documentation

#define GEOCON_ASC_EXTENSION   "gca"

Geocon Combined Ascii

#define GEOCON_BIN_EXTENSION   "gcb"

Geocon Combined Binary

#define GEOCON_COORD_LAM   0

Longitude coord index

#define GEOCON_COORD_LAT   1

Latitude coord index

#define GEOCON_COORD_LON   0

Longitude coord index

#define GEOCON_COORD_PHI   1

Latitude coord index

#define GEOCON_CVT_FORWARD   1

Convert data forward

#define GEOCON_CVT_INVERSE   0

Convert data inverse

#define GEOCON_CVT_REVERSE

(

n

)

(1 - n)

Reverse the direction

#define GEOCON_ENDIAN_BIG   1

Write big-endian byte-order

#define GEOCON_ENDIAN_INP_FILE   0

Write input-file byte-order

#define GEOCON_ENDIAN_LITTLE   2

Write little-endian byte-order

#define GEOCON_ENDIAN_NATIVE   3

Write native byte-order

#define GEOCON_ERR_CANNOT_OPEN_FILE   7

#define GEOCON_ERR_FILE_NOT_FOUND   5

#define GEOCON_ERR_INVALID_EXTENT   4

#define GEOCON_ERR_INVALID_FILE   6

#define GEOCON_ERR_INVALID_TOKEN_CNT   10

#define GEOCON_ERR_IOERR   2

#define GEOCON_ERR_NO_MEMORY   1

#define GEOCON_ERR_NULL_PARAMETER   3

#define GEOCON_ERR_OK   0

#define GEOCON_ERR_UNEXPECTED_EOF   9

#define GEOCON_ERR_UNKNOWN_FILETYPE   8

#define GEOCON_FILE_HDR_LEN   sizeof(GEOCON_FILE_HDR)

#define GEOCON_FILE_TYPE_ASC   2

File type is ascii

#define GEOCON_FILE_TYPE_BIN   1

File type is binary

#define GEOCON_FILE_TYPE_UNK   0

File type is unknown

#define GEOCON_HDR_DATE_LEN   24

Max length of date field

#define GEOCON_HDR_INFO_LEN   80

Max length of info field

#define GEOCON_HDR_MAGIC   0x47434f4e

"GCON" (not swapped)

#define GEOCON_HDR_MAGIC_SWAPPED   0x4e4f4347

"NOCG" ( swapped)

#define GEOCON_HDR_NAME_LEN   80

Max length of obj names

#define GEOCON_HDR_VERSION   1

#define GEOCON_INTERP_BICUBIC   2

Use bicubic interpolation

#define GEOCON_INTERP_BILINEAR   1

Use bilinear interpolation

#define GEOCON_INTERP_BIQUADRATIC   3

Use biquadratic interpolation

#define GEOCON_INTERP_DEFAULT   0

Use default interpolation

#define GEOCON_INTERP_NATSPLINE   4

Use natural spline interpolation

#define GEOCON_LAT_N_TO_S   1

Latitude values go from N to S

#define GEOCON_LAT_S_TO_N   0

Latitude values go from S to N

#define GEOCON_LON_E_TO_W   1

Longitude values go from E to W

#define GEOCON_LON_W_TO_E   0

Longitude values go from W to E

#define GEOCON_MAX_ERR_LEN   32

Max err msg length

#define GEOCON_MAX_PATH_LEN   256

Max pathname length

#define GEOCON_NULL   0

NULL pointer

#define GEOCON_VERSION_MAJOR   1

#define GEOCON_VERSION_MINOR   0

#define GEOCON_VERSION_RELEASE   0

#define GEOCON_VERSION_STR   "1.0.0"

Typedef Documentation

typedef int GEOCON_BOOL

Boolean variable

typedef double GEOCON_COORD[2]

Lon/lat coordinate

Function Documentation

GEOCON_HDR* geocon_create

(

)

Create an empty GEOCON_HDR object.

The header returned will be all zeros except for the first four words, which will be properly set.

Returns

A pointer to an allocated GEOCON_HDR struct or GEOCON_NULL.

void geocon_delete

(

GEOCON_HDR *

hdr

)

Delete a GEOCON object

This method will also close any open stream (and mutex) in the object.

Parameters

hdr	A pointer to a GEOCON object.

void geocon_dump_data	(	const GEOCON_HDR *	hdr,
		FILE *	fp
	)

Dump the contents the GEOCON data.

Parameters

hdr	A pointer to a GEOCON_HDR object.
fp	The stream to dump it to, typically stdout. If NULL, no dump will be done.

Note that the data is always dumped with latitudes going south-to-north and longitudes going west-to-east.

void geocon_dump_hdr	(	const GEOCON_HDR *	hdr,
		FILE *	fp
	)

Dump the contents of a GEOCON header.

This routine provides a verbose multi-line dump of a file header.

Parameters

hdr	A pointer to a GEOCON_HDR object.
fp	The stream to dump it to, typically stdout. If NULL, no dump will be done.

const char* geocon_errmsg	(	int	err_num,
		char	msg_buf[]
	)

Convert a GEOCON 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 an error-message string.

int geocon_filetype

(

const char *

pathname

)

Determine whether a filename is for a binary or an ascii file.

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

Parameters

pathname

The filename to query.

Returns

One of the following:

• GEOCON_FILE_TYPE_UNK file type is unknown
• GEOCON_FILE_TYPE_BIN file type is binary
• GEOCON_FILE_TYPE_ASC file type is ascii

int geocon_forward	(	const GEOCON_HDR *	hdr,
		int	interp,
		double	deg_factor,
		double	hgt_factor,
		int	n,
		GEOCON_COORD	coord[],
		double	h[]
	)

Perform a forward transformation on an array of points.

Parameters

hdr	A pointer to a GEOCON_HDR object.
interp	The interpolation method to use: GEOCON_INTERP_DEFAULT (biquadratic) GEOCON_INTERP_BILINEAR GEOCON_INTERP_BICUBIC GEOCON_INTERP_BIQUADRATIC GEOCON_INTERP_NATSPLINE
deg_factor	The conversion factor to convert the given coordinates to decimal degrees. The value is degrees-per-unit.
hgt_factor	The conversion factor to convert the given height to meters. The value is meters-per-unit.
n	Number of points in the array to be transformed.
coord	An array of GEOCON_COORD values to be transformed.
h	An array of heights to transform. This may be NULL.

Returns

The number of points successfully transformed.

Note that the return value is the number of points successfully transformed, and points that can't be transformed (usually because they are outside of the grid) are left unchanged. However, there is no indication of which points were changed and which were not. If you need that information, then call this routine with one point at a time. The overhead for doing that is minimal.

int geocon_inverse	(	const GEOCON_HDR *	hdr,
		int	interp,
		double	deg_factor,
		double	hgt_factor,
		int	n,
		GEOCON_COORD	coord[],
		double	h[]
	)

Perform an inverse transformation on an array of points.

Parameters

hdr	A pointer to a GEOCON_HDR object.
interp	The interpolation method to use: GEOCON_INTERP_DEFAULT (biquadratic) GEOCON_INTERP_BILINEAR GEOCON_INTERP_BICUBIC GEOCON_INTERP_BIQUADRATIC GEOCON_INTERP_NATSPLINE
deg_factor	The conversion factor to convert the given coordinates to decimal degrees. The value is degrees-per-unit.
hgt_factor	The conversion factor to convert the given height to meters. The value is meters-per-unit.
n	Number of points in the array to be transformed.
coord	An array of GEOCON_COORD values to be transformed.
h	An array of heights to transform. This may be NULL.

Returns

The number of points successfully transformed.

Note that the return value is the number of points successfully transformed, and points that can't be transformed (usually because they are outside of the grid) are left unchanged. However, there is no indication of which points were changed and which were not. If you need that information, then call this routine with one point at a time. The overhead for doing that is minimal.

void geocon_list_hdr	(	const GEOCON_HDR *	hdr,
		FILE *	fp,
		GEOCON_BOOL	do_hdr_line
	)

List the contents of a GEOCON header.

This routine provides a terse single-line summary of a file header.

Parameters

hdr	A pointer to a GEOCON_HDR object.
fp	The stream to dump it to, typically stdout. If NULL, no dump will be done.
do_hdr_line	TRUE to output a header line.

GEOCON_HDR* geocon_load	(	const char *	pathname,
		GEOCON_EXTENT *	extent,
		GEOCON_BOOL	load_data,
		int *	prc
	)

Load a GEOCON file into memory.

Parameters

pathname	The name of the GEOCON file to load.
extent	A pointer to an GEOCON_EXTENT struct. This pointer may be NULL. This is ignored for ascii files.
load_data	TRUE to read shift data into memory. A TRUE value will also result in closing the file after reading, since there is no need to keep it open.
prc	A pointer to a result code. This pointer may be NULL. If successful, it will be set to GEOCON_ERR_OK (0). If unsuccessful, it will be set to GEOCON_ERR_*.

Returns

A pointer to a GEOCON object or NULL if unsuccessful.

int geocon_transform	(	const GEOCON_HDR *	hdr,
		int	interp,
		double	deg_factor,
		double	hgt_factor,
		int	n,
		GEOCON_COORD	coord[],
		double	h[],
		int	direction
	)

Perform a forward or inverse transformation on an array of points.

Parameters

hdr	A pointer to a GEOCON_HDR object.
interp	The interpolation method to use: GEOCON_INTERP_DEFAULT (biquadratic) GEOCON_INTERP_BILINEAR GEOCON_INTERP_BICUBIC GEOCON_INTERP_BIQUADRATIC GEOCON_INTERP_NATSPLINE
deg_factor	The conversion factor to convert the given coordinates to decimal degrees. The value is degrees-per-unit.
hgt_factor	The conversion factor to convert the given height to meters. The value is meters-per-unit.
n	Number of points in the array to be transformed.
coord	An array of GEOCON_COORD values to be transformed.
h	An array of heights to transform. This may be NULL.
direction	The direction of the transformation (GEOCON_CVT_FORWARD or GEOCON_CVT_INVERSE).

Returns

The number of points successfully transformed.

Note that the return value is the number of points successfully transformed, and points that can't be transformed (usually because they are outside of the grid) are left unchanged. However, there is no indication of which points were changed and which were not. If you need that information, then call this routine with one point at a time. The overhead for doing that is minimal.

int geocon_write	(	const GEOCON_HDR *	hdr,
		const char *	pathname,
		int	byte_order,
		int *	prc
	)

Write out a GEOCON object to a file.

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

Parameters

hdr	A pointer to a GEOCON_HDR object.
pathname	The pathname of the file to write. This can name either a binary or an ascii file.
byte_order	Byte order of the output file (GEOCON_ENDIAN_*) if binary. A value of GEOCON_ENDIAN_INP_FILE means to write the file using the same byte-order as the input file if binary or in native byte-order if the input file was an ascii file. This parameter is ignored when writing ascii files.
prc	A pointer to a result code. This pointer may be NULL. If successful, it will be set to GEOCON_ERR_OK (0). If unsuccessful, it will be set to GEOCON_ERR_*.

Returns

0 if OK, -1 if error.