WCSLIB  4.25.1
Data Structures | Macros | Enumerations | Functions | Variables
dis.h File Reference

Go to the source code of this file.

Data Structures

struct  disprm
 Distortion parameters. More...
 

Macros

#define DISP2X_ARGS
 
#define DISX2P_ARGS
 
#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 disini (int alloc, int naxis, struct disprm *dis)
 Default constructor for the disprm struct. More...
 
int disparms (struct disprm *dis)
 Allocate memory for parameters in a 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 tpvset (int j, struct disprm *dis)
 (Internal use only.) More...
 
int tpv1 (DISP2X_ARGS)
 (Internal use only.) More...
 
int tpv2 (DISP2X_ARGS)
 (Internal use only.) More...
 
int tpv3 (DISP2X_ARGS)
 (Internal use only.) More...
 
int tpv4 (DISP2X_ARGS)
 (Internal use only.) More...
 
int tpv5 (DISP2X_ARGS)
 (Internal use only.) More...
 
int tpv6 (DISP2X_ARGS)
 (Internal use only.) More...
 
int tpv7 (DISP2X_ARGS)
 (Internal use only.) More...
 

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.

Four routines, disini(), disparms(), 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 tpv1(), to do the computation.

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

Macro Definition Documentation

#define DISP2X_ARGS
Value:
int nparm, const double parms[], int ncrd, \
const double rawcrd[], double *discrd
#define DISX2P_ARGS
Value:
int nparm, const double parms[], int ncrd, \
const double discrd[], double rawcrd[]
#define DISLEN   (sizeof(struct disprm)/sizeof(int))

Enumeration Type Documentation

Enumerator
DISERR_SUCCESS 
DISERR_NULL_POINTER 
DISERR_MEMORY 
DISERR_BAD_PARAM 
DISERR_DISTORT 
DISERR_DEDISTORT 

Function Documentation

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.

In general, different distortion functions may be associated with each axis, and at the point where disini() is invoked, it is usually not known how many distortion parameters may be required for each. Hence a separate routine, disparms(), is provided to allocate memory for the parameter arrays if desired. One way or the other, after invoking disini(), it is the caller's responsibility to allocate memory (if necessary) for the distortion parameters. If disparms() is used for this purpose, then disfree() will free it and subsequent calls to disini() will manage it, e.g. if naxis changes. Of course, if there is no distortion function on an axis then there is no need to allocate memory for any parameters.

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]allocIf 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]naxisThe number of world coordinate axes, used to determine array sizes.
[in,out]disDistortion 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 disparms ( struct disprm dis)

disparms() allocates memory for the arrays of distortion function parameters in a disprm struct. It relies on disprm::nparm[] having been set to determine the number of parameters for each distortion function. The allocated memory will be freed by disfree().

Parameters
[in,out]disdisprm::nparm[] is used to determine the number of parameters in each distortion function. Memory is allocated for the distortion function parameters, disprm::parms[][], and it is initialized to zero.
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]allocIf true, allocate memory unconditionally for arrays in the destination, including the parameter array via a call to disparms(). 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]dissrcStruct to copy from.
[in,out]disdstStruct 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() and/or disparms(). disini() and disparms() keep a record of the memory they allocate 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]disDistortion 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]disDistortion 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]disDistortion 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]disDistortion function parameters.
[in]discrdArray of coordinates.
[out]rawcrdArray 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 the 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]disDistortion function parameters.
[in]pixblcStart 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]pixtrcEnd of the range of pixel coordinates (prior) or intermediate pixel coordinates (sequent).
[in]pixsampIf 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]nsampThe number of pixel coordinates sampled.
Can be specified as a NULL pointer if not required.
[out]maxdisFor each individual distortion function, the maximum absolute value of the distortion.
Can be specified as a NULL pointer if not required.
[out]maxtotFor the combination of all distortion functions, the maximum absolute value of the distortion.
Can be specified as a NULL pointer if not required.
[out]avgdisFor each individual distortion function, the mean value of the distortion.
Can be specified as a NULL pointer if not required.
[out]avgtotFor the combination of all distortion functions, the mean value of the distortion.
Can be specified as a NULL pointer if not required.
[out]rmsdisFor each individual distortion function, the root mean square deviation of the distortion.
Can be specified as a NULL pointer if not required.
[out]rmstotFor 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.
tpvset ( int  j,
struct disprm dis 
)

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

tpv1 ( DISP2X_ARGS  )

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

tpv2 ( DISP2X_ARGS  )

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

tpv3 ( DISP2X_ARGS  )

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

tpv4 ( DISP2X_ARGS  )

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

tpv5 ( DISP2X_ARGS  )

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

tpv6 ( DISP2X_ARGS  )

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

tpv7 ( DISP2X_ARGS  )

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

Variable Documentation

const char * dis_errmsg[]

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