dis.h File Reference

Go to the source code of this file.

Data Structures
struct	dpkey
	Store for DPja and DQia keyvalues. More...
struct	disprm
	Distortion parameters. More...

Macros
#define	DISP2X_ARGS
#define	DISX2P_ARGS
#define	DPLEN   (sizeof(struct dpkey)/sizeof(int))
#define	DISLEN   (sizeof(struct disprm)/sizeof(int))

Enumerations
enum	dis_errmsg_enum {   DISERR_SUCCESS = 0, DISERR_NULL_POINTER = 1, DISERR_MEMORY = 2, DISERR_BAD_PARAM = 3,   DISERR_DISTORT = 4, DISERR_DEDISTORT = 5 }

Functions
int	disndp (int n)
	Memory allocation for DPja and DQia. More...
int	dpfill (struct dpkey *dp, const char *keyword, const char *field, int j, int type, int ival, double fval)
	Fill the contents of a dpkey struct. More...
int	disini (int alloc, int naxis, struct disprm *dis)
	Default constructor for the disprm struct. More...
int	discpy (int alloc, const struct disprm *dissrc, struct disprm *disdst)
	Copy routine for the disprm struct. More...
int	disfree (struct disprm *dis)
	Destructor for the disprm struct. More...
int	disprt (const struct disprm *dis)
	Print routine for the disprm struct. More...
int	disset (struct disprm *dis)
	Setup routine for the disprm struct. More...
int	disp2x (struct disprm *dis, const double rawcrd[], double discrd[])
	Apply distortion function. More...
int	disx2p (struct disprm *dis, const double discrd[], double rawcrd[])
	Apply de-distortion function. More...
int	diswarp (struct disprm *dis, const double pixblc[], const double pixtrc[], const double pixsamp[], int *nsamp, double maxdis[], double *maxtot, double avgdis[], double *avgtot, double rmsdis[], double *rmstot)
	Compute measures of distortion. More...
int	polyset (int j, struct disprm *dis)
int	pol2tpd (int j, struct disprm *dis)
int	dispoly (DISP2X_ARGS)
int	tpdset (int j, struct disprm *dis)
int	tpvset (int j, struct disprm *dis)
	(Internal use only.) More...
int	sipset (int j, struct disprm *dis)
int	tpd1 (DISP2X_ARGS)
int	tpd2 (DISP2X_ARGS)
int	tpd3 (DISP2X_ARGS)
int	tpd4 (DISP2X_ARGS)
int	tpd5 (DISP2X_ARGS)
int	tpd6 (DISP2X_ARGS)
int	tpd7 (DISP2X_ARGS)
int	tpd8 (DISP2X_ARGS)
int	tpd9 (DISP2X_ARGS)

Variables
const char *	dis_errmsg []
	Status return messages. More...

Detailed Description

These routines apply the distortion functions defined by the extension to the FITS WCS standard proposed in Paper IV. They are based on the disprm struct which contains all information needed for the computations. The struct contains some members that must be set by the user, and others that are maintained by these routines, somewhat like a C++ class but with no encapsulation.

disndp(), dpfill(), disini(), discpy(), and disfree() are provided to manage the disprm struct, and another, disprt(), prints its contents.

A setup routine, disset(), computes intermediate values in the disprm struct from parameters in it that were supplied by the user. The struct always needs to be set up by disset(), though disset() need not be called explicitly - refer to the explanation of disprm::flag.

disp2x() and disx2p() implement the WCS distortion functions, disp2x() using separate functions, such as dispoly() and tpd7(), to do the computation.

An auxiliary routine, diswarp(), computes various measures of the distortion over a specified range of coordinates.

PLEASE NOTE:
wcscompare(), or wcshdo().

Macro Definition Documentation

#define DISP2X_ARGS

Value:

int inverse, const int iparm[], const double dparm[], \
int ncrd, const double rawcrd[], double *discrd

#define DISX2P_ARGS

Value:

int inverse, const int iparm[], const double dparm[], \
int ncrd, const double discrd[], double *rawcrd

#define DPLEN   (sizeof(struct dpkey)/sizeof(int))

#define DISLEN   (sizeof(struct disprm)/sizeof(int))

Enumeration Type Documentation

enum dis_errmsg_enum

Enumerator
DISERR_SUCCESS
DISERR_NULL_POINTER
DISERR_MEMORY
DISERR_BAD_PARAM
DISERR_DISTORT
DISERR_DEDISTORT

Function Documentation

int disndp

(

int

n

)

disndp() changes the value of NDPMAX (default 256). This global variable controls the number of dpkey structs, for holding DPja or DQia keyvalues, that disini() should allocate space for.

PLEASE NOTE: This function is not thread-safe.

Parameters

[in]

n

Value of NDPMAX; ignored if < 0.

Returns

Current value of NDPMAX.

int dpfill	(	struct dpkey *	dp,
		const char *	keyword,
		const char *	field,
		int	j,
		int	type,
		int	ival,
		double	fval
	)

dpfill() is a utility routine to aid in filling the contents of the dpkey struct. No checks are done on the validity of the inputs.

WCS Paper IV specifies the syntax of a record-valued keyword as

keyword = '<field-specifier>: <float>'

However, some DPja and DQia record values, such as those of DPja.NAXES and DPja.AXIS.j, are intrinsically integer-valued. While FITS header parsers are not expected to know in advance which of DPja and DQia are integral and which are floating point, if the record's value parses as an integer (i.e. without decimal point or exponent), then preferably enter it into the dpkey struct as an integer. Either way, it doesn't matter as disset() accepts either data type for all record values.

Parameters

[in,out]	dp	Store for DPja and DQia keyvalues.
[in]	keyword
[in]	field	These arguments are concatenated with an intervening "." to construct the full record field name, i.e. including the keyword name, DPja or DQia (but excluding the colon delimiter which is NOT part of the name). Either may be given as a NULL pointer. Set both NULL to omit setting this component of the struct.
[in]	j	Axis number (1-relative), i.e. the j in DPja or i in DQia. Can be given as 0, in which case the axis number will be obtained from the keyword component of the field name which must either have been given or preset.
[in]	type	Data type of the record's value 0: Integer, 1: Floating point.
[in]	ival	For type == 0, the integer value of the record.
[in]	fval	For type == 1, the floating point value of the record.

Returns

Status return value:

• 0: Success.

int disini	(	int	alloc,
		int	naxis,
		struct disprm *	dis
	)

disini() allocates memory for arrays in a disprm struct and sets all members of the struct to default values. Memory is allocated for up to NDPMAX DPja or DQia keywords per WCS representation. This may be changed via disndp() before disini() is called.

PLEASE NOTE: every disprm struct must be initialized by disini(), possibly repeatedly. On the first invokation, and only the first invokation, disprm::flag must be set to -1 to initialize memory management, regardless of whether disini() will actually be used to allocate memory.

Parameters

[in]	alloc	If true, allocate memory unconditionally for arrays in the disprm struct. If false, it is assumed that pointers to these arrays have been set by the user except if they are null pointers in which case memory will be allocated for them regardless. (In other words, setting alloc true saves having to initalize these pointers to zero.)
[in]	naxis	The number of world coordinate axes, used to determine array sizes.
[in,out]	dis	Distortion function parameters. Note that, in order to initialize memory management disprm::flag must be set to -1 when dis is initialized for the first time (memory leaks may result if it had already been initialized).

Returns

Status return value:

• 0: Success.
• 1: Null disprm pointer passed.
• 2: Memory allocation failed.

For returns > 1, a detailed error message is set in disprm::err if enabled, see wcserr_enable().

int discpy	(	int	alloc,
		const struct disprm *	dissrc,
		struct disprm *	disdst
	)

discpy() does a deep copy of one disprm struct to another, using disini() to allocate memory unconditionally for its arrays if required. Only the "information to be provided" part of the struct is copied; a call to disset() is required to initialize the remainder.

Parameters

[in]	alloc	If true, allocate memory unconditionally for arrays in the destination. Otherwise, it is assumed that pointers to these arrays have been set by the user except if they are null pointers in which case memory will be allocated for them regardless.
[in]	dissrc	Struct to copy from.
[in,out]	disdst	Struct to copy to. disprm::flag should be set to -1 if disdst was not previously initialized (memory leaks may result if it was previously initialized).

Returns

Status return value:

• 0: Success.
• 1: Null disprm pointer passed.
• 2: Memory allocation failed.

For returns > 1, a detailed error message is set in disprm::err if enabled, see wcserr_enable().

int disfree

(

struct disprm *

dis

)

disfree() frees memory allocated for the disprm arrays by disini(). disini() keeps a record of the memory it allocates and disfree() will only attempt to free this.

PLEASE NOTE: disfree() must not be invoked on a disprm struct that was not initialized by disini().

Parameters

[in]

dis

Distortion function parameters.

Returns

Status return value:

• 0: Success.
• 1: Null disprm pointer passed.

int disprt

(

const struct disprm *

dis

)

disprt() prints the contents of a disprm struct using wcsprintf(). Mainly intended for diagnostic purposes.

Parameters

[in]

dis

Distortion function parameters.

Returns

Status return value:

• 0: Success.
• 1: Null disprm pointer passed.

int disset

(

struct disprm *

dis

)

disset(), sets up the disprm struct according to information supplied within it - refer to the explanation of disprm::flag.

Note that this routine need not be called directly; it will be invoked by disp2x() and disx2p() if the disprm::flag is anything other than a predefined magic value.

Parameters

[in,out]

dis

Distortion function parameters.

Returns

Status return value:

• 0: Success.
• 1: Null disprm pointer passed.
• 2: Memory allocation failed.
• 3: Invalid parameter.

For returns > 1, a detailed error message is set in disprm::err if enabled, see wcserr_enable().

int disp2x	(	struct disprm *	dis,
		const double	rawcrd[],
		double	discrd[]
	)

disp2x() applies the distortion functions. By definition, the distortion is in the pixel-to-world direction.

Depending on the point in the algorithm chain at which it is invoked, disp2x() may transform pixel coordinates to corrected pixel coordinates, or intermediate pixel coordinates to corrected intermediate pixel coordinates, or image coordinates to corrected image coordinates.

int disx2p	(	struct disprm *	dis,
		const double	discrd[],
		double	rawcrd[]
	)

disx2p() applies the inverse of the distortion functions. By definition, the de-distortion is in the world-to-pixel direction.

Depending on the point in the algorithm chain at which it is invoked, disx2p() may transform corrected pixel coordinates to pixel coordinates, or corrected intermediate pixel coordinates to intermediate pixel coordinates, or corrected image coordinates to image coordinates.

disx2p() iteratively solves for the inverse using disp2x(). It assumes that the distortion is small and the functions are well-behaved, being continuous and with continuous derivatives. Also that, to first order in the neighbourhood of the solution, discrd[j] ~= a + b*rawcrd[j], i.e. independent of rawcrd[i], where i != j. This is effectively equivalent to assuming that the distortion functions are separable to first order. Furthermore, a is assumed to be small, and b close to unity.

Parameters

[in,out]	dis	Distortion function parameters.
[in]	discrd	Array of coordinates.
[out]	rawcrd	Array of coordinates to which the inverse distortion functions have been applied.

Returns

Status return value:

• 0: Success.
• 1: Null disprm pointer passed.
• 2: Memory allocation failed.
• 3: Invalid parameter.
• 5: De-distort error.

For returns > 1, a detailed error message is set in disprm::err if enabled, see wcserr_enable().

int diswarp	(	struct disprm *	dis,
		const double	pixblc[],
		const double	pixtrc[],
		const double	pixsamp[],
		int *	nsamp,
		double	maxdis[],
		double *	maxtot,
		double	avgdis[],
		double *	avgtot,
		double	rmsdis[],
		double *	rmstot
	)

diswarp() computes various measures of the distortion over a specified range of coordinates.

For prior distortions, the measures may be interpreted simply as an offset in pixel coordinates. For sequent distortions, the interpretation depends on the nature of the linear transformation matrix (PCi_ja or CDi_ja). If the latter introduces a scaling, then the measures will also be scaled. Note also that the image domain, which is rectangular in pixel coordinates, may be rotated, skewed, and/or stretched in intermediate pixel coordinates, and in general cannot be defined using pixblc[] and pixtrc[].

PLEASE NOTE: the measures of total distortion may be essentially meaningless if there are multiple sequent distortions with different scaling.

See also linwarp().

Parameters

[in,out]	dis	Distortion function parameters.
[in]	pixblc	Start of the range of pixel coordinates (for prior distortions), or intermediate pixel coordinates (for sequent distortions). May be specified as a NULL pointer which is interpreted as (1,1,...).
[in]	pixtrc	End of the range of pixel coordinates (prior) or intermediate pixel coordinates (sequent).
[in]	pixsamp	If positive or zero, the increment on the particular axis, starting at pixblc[]. Zero is interpreted as a unit increment. pixsamp may also be specified as a NULL pointer which is interpreted as all zeroes, i.e. unit increments on all axes. If negative, the grid size on the particular axis (the absolute value being rounded to the nearest integer). For example, if pixsamp is (-128.0,-128.0,...) then each axis will be sampled at 128 points between pixblc[] and pixtrc[] inclusive. Use caution when using this option on non-square images.
[out]	nsamp	The number of pixel coordinates sampled. Can be specified as a NULL pointer if not required.
[out]	maxdis	For each individual distortion function, the maximum absolute value of the distortion. Can be specified as a NULL pointer if not required.
[out]	maxtot	For the combination of all distortion functions, the maximum absolute value of the distortion. Can be specified as a NULL pointer if not required.
[out]	avgdis	For each individual distortion function, the mean value of the distortion. Can be specified as a NULL pointer if not required.
[out]	avgtot	For the combination of all distortion functions, the mean value of the distortion. Can be specified as a NULL pointer if not required.
[out]	rmsdis	For each individual distortion function, the root mean square deviation of the distortion. Can be specified as a NULL pointer if not required.
[out]	rmstot	For the combination of all distortion functions, the root mean square deviation of the distortion. Can be specified as a NULL pointer if not required.

Returns

Status return value:

• 0: Success.
• 1: Null disprm pointer passed.
• 2: Memory allocation failed.
• 3: Invalid parameter.
• 4: Distort error.

int polyset	(	int	j,
		struct disprm *	dis
	)

int pol2tpd	(	int	j,
		struct disprm *	dis
	)

int dispoly

(

DISP2X_ARGS

)

int tpdset	(	int	j,
		struct disprm *	dis
	)

tpvset	(	int	j,
		struct disprm *	dis
	)

For internal use only in the implementation of the TPV "projection".

int sipset	(	int	j,
		struct disprm *	dis
	)

int tpd1

(

DISP2X_ARGS

)

int tpd2

(

DISP2X_ARGS

)

int tpd3

(

DISP2X_ARGS

)

int tpd4

(

DISP2X_ARGS

)

int tpd5

(

DISP2X_ARGS

)

int tpd6

(

DISP2X_ARGS

)

int tpd7

(

DISP2X_ARGS

)

int tpd8

(

DISP2X_ARGS

)

int tpd9

(

DISP2X_ARGS

)

Variable Documentation

const char * dis_errmsg[]

Error messages to match the status value returned from each function.