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 | dispoly (DISP2X_ARGS)
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.

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 tpv7(), to do the computation.

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

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

## Macro Definition Documentation

#define DISP2X_ARGS

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

#define DISX2P_ARGS

Value:
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 dispoly | ( | DISP2X_ARGS |  | ) |

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.