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

enum dis_errmsg_enum

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] | 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 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] | dis | disprm::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] | alloc | If 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] | 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() 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] | 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 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] | 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.

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.