WCSLIB: disprm Struct Reference

WCSLIB 7.3.1

Data Fields
disprm Struct Reference

Distortion parameters. More...

`#include <dis.h>`

## Data Fields
int | flag
int | naxis
char(* | dtype )[72]
int | ndp
int | ndpmax
struct dpkey * | dp
double * | maxdis
double | totdis
int * | docorr
int * | Nhat
int ** | axmap
double ** | offset
double ** | scale
int ** | iparm
double ** | dparm
int | i_naxis
int | ndis
struct wcserr * | err
int(** | disp2x )(DISP2X_ARGS)
int(** | disx2p )(DISX2P_ARGS)
double * | tmpmem
int | m_flag
int | m_naxis
char(* | m_dtype )[72]
struct dpkey * | m_dp
double * | m_maxdis

## Detailed Description

The disprm struct contains all of the information required to apply a set of distortion functions. It consists of certain members that must be set by the user (given) and others that are set by the WCSLIB routines (returned). While the addresses of the arrays themselves may be set by disinit() if it (optionally) allocates memory, their contents must be set by the user.

## Field Documentation

## ◆ flag

int disprm::flag

(Given and returned) This flag must be set to zero whenever any of the following members of the disprm struct are set or modified:

- disprm::naxis,
- disprm::dtype,
- disprm::ndp,
- disprm::dp.

This signals the initialization routine, disset(), to recompute the returned members of the disprm struct. disset() will reset flag to indicate that this has been done.

PLEASE NOTE: flag must be set to -1 when disinit() is called for the first time for a particular disprm struct in order to initialize memory management. It must ONLY be used on the first initialization otherwise memory leaks may result.

## ◆ naxis

int disprm::naxis

(Given or returned) Number of pixel and world coordinate elements.

If disinit() is used to initialize the disprm struct (as would normally be the case) then it will set naxis from the value passed to it as a function argument. The user should not subsequently modify it.

## ◆ dtype

disprm::dtype

(Given) Pointer to the first element of an array of char[72] containing the name of the distortion function for each axis.

## ◆ ndp

int disprm::ndp

(Given) The number of entries in the disprm::dp[] array.

## ◆ ndpmax

int disprm::ndpmax

(Given) The length of the disprm::dp[] array.

ndpmax will be set by disinit() if it allocates memory for disprm::dp[], otherwise it must be set by the user. See also disndp().

## ◆ dp

struct dpkey disprm::dp

(Given) Address of the first element of an array of length ndpmax of dpkey structs.

As a FITS header parser encounters each `DPja` or `DQia` keyword it should load it into a dpkey struct in the array and increment ndp. However, note that a single disprm struct must hold only `DPja` or `DQia` keyvalues, not both. disset() interprets them as required by the particular distortion function.

## ◆ maxdis

double * disprm::maxdis

(Given) Pointer to the first element of an array of double specifying the maximum absolute value of the distortion for each axis computed over the whole image.

It is not necessary to reset the disprm struct (via disset()) when disprm::maxdis is changed.

## ◆ totdis

double disprm::totdis

(Given) The maximum absolute value of the combination of all distortion functions specified as an offset in pixel coordinates computed over the whole image.

It is not necessary to reset the disprm struct (via disset()) when disprm::totdis is changed.

## ◆ docorr

int * disprm::docorr

(Returned) Pointer to the first element of an array of int containing flags that indicate the mode of correction for each axis.

If docorr is zero, the distortion function returns the corrected coordinates directly. Any other value indicates that the distortion function computes a correction to be added to pixel coordinates (prior distortion) or intermediate pixel coordinates (sequent distortion).

## ◆ Nhat

int * disprm::Nhat

(Returned) Pointer to the first element of an array of int containing the number of coordinate axes that form the independent variables of the distortion function for each axis.

## ◆ axmap

int ** disprm::axmap

(Returned) Pointer to the first element of an array of int* containing pointers to the first elements of the axis mapping arrays for each axis.

An axis mapping associates the independent variables of a distortion function with the 0-relative image axis number. For example, consider an image with a spectrum on the first axis (axis 0), followed by RA (axis 1), Dec (axis2), and time (axis 3) axes. For a distortion in (RA,Dec) and no distortion on the spectral or time axes, the axis mapping arrays, axmap[j][], would be

j=0: [-1, -1, -1, -1] ...no distortion on spectral axis,
1: [ 1, 2, -1, -1] ...RA distortion depends on RA and Dec,
2: [ 2, 1, -1, -1] ...Dec distortion depends on Dec and RA,
3: [-1, -1, -1, -1] ...no distortion on time axis,

where -1 indicates that there is no corresponding independent variable.

## ◆ offset

double ** disprm::offset

(Returned) Pointer to the first element of an array of double* containing pointers to the first elements of arrays of offsets used to renormalize the independent variables of the distortion function for each axis.

The offsets are subtracted from the independent variables before scaling.

## ◆ scale

double ** disprm::scale

(Returned) Pointer to the first element of an array of double* containing pointers to the first elements of arrays of scales used to renormalize the independent variables of the distortion function for each axis.

The scale is applied to the independent variables after the offsets are subtracted.

## ◆ iparm

int ** disprm::iparm

(Returned) Pointer to the first element of an array of int* containing pointers to the first elements of the arrays of integer distortion parameters for each axis.

## ◆ dparm

double ** disprm::dparm

(Returned) Pointer to the first element of an array of double* containing pointers to the first elements of the arrays of floating point distortion parameters for each axis.

## ◆ i_naxis

int disprm::i_naxis

(Returned) Dimension of the internal arrays (normally equal to naxis).

## ◆ ndis

int disprm::ndis

(Returned) The number of distortion functions.

## ◆ err

struct wcserr * disprm::err

(Returned) If enabled, when an error status is returned, this struct contains detailed information about the error, see wcserr_enable().

## ◆ disp2x

int(** disprm::disp2x)(DISP2X_ARGS)

(For internal use only.)

## ◆ disx2p

int(** disprm::disx2p)(DISX2P_ARGS)

(For internal use only.)

## ◆ tmpmem

double * disprm::tmpmem

(For internal use only.)

## ◆ m_flag

int disprm::m_flag

(For internal use only.)

## ◆ m_naxis

int disprm::m_naxis

(For internal use only.)

## ◆ m_dtype

disprm::m_dtype

(For internal use only.)

## ◆ m_dp

double ** disprm::m_dp

(For internal use only.)

## ◆ m_maxdis

double * disprm::m_maxdis

(For internal use only.)