WCSLIB: dis.h File Reference

WCSLIB 8.7

Loading...
Searching...
No Matches
Data Structures | Macros | Enumerations | Functions | Variables
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 | disenq_enum { DISENQ_MEM = 1 , DISENQ_SET = 2 , DISENQ_BYP = 4 }
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.
int | dpfill (struct dpkey *dp, const char *keyword, const char *field, int j, int type, int i, double f)
| Fill the contents of a dpkey struct.
int | dpkeyi (const struct dpkey *dp)
| Get the data value in a dpkey struct as int.
double | dpkeyd (const struct dpkey *dp)
| Get the data value in a dpkey struct as double.
int | disini (int alloc, int naxis, struct disprm *dis)
| Default constructor for the disprm struct.
int | disinit (int alloc, int naxis, struct disprm *dis, int ndpmax)
| Default constructor for the disprm struct.
int | discpy (int alloc, const struct disprm *dissrc, struct disprm *disdst)
| Copy routine for the disprm struct.
int | disfree (struct disprm *dis)
| Destructor for the disprm struct.
int | dissize (const struct disprm *dis, int sizes[2])
| Compute the size of a disprm struct.
int | disenq (const struct disprm *dis, int enquiry)
| enquire about the state of a disprm struct.
int | disprt (const struct disprm *dis)
| Print routine for the disprm struct.
int | disperr (const struct disprm *dis, const char *prefix)
| Print error messages from a disprm struct.
int | dishdo (struct disprm *dis)
| write FITS headers using TPD.
int | disset (struct disprm *dis)
| Setup routine for the disprm struct.
int | disp2x (struct disprm *dis, const double rawcrd[], double discrd[])
| Apply distortion function.
int | disx2p (struct disprm *dis, const double discrd[], double rawcrd[])
| Apply de-distortion function.
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.

## Variables
const char * | dis_errmsg []
| Status return messages.

## Detailed Description

Routines in this suite implement extensions to the FITS World Coordinate System (WCS) standard proposed by

"Representations of distortions in FITS world coordinate systems",
Calabretta, M.R. et al. (WCS Paper IV, draft dated 2004/04/22),
available from http://www.atnf.csiro.au/computing/software/wcs

In brief, a distortion function may occupy one of two positions in the WCS algorithm chain. Prior distortions precede the linear transformation matrix, whether it be PCi_ja or CDi_ja, and sequent distortions follow it. WCS Paper IV defines FITS keywords used to specify parameters for predefined distortion functions. The following are used for prior distortions:

CPDISja ...(string-valued, identifies the distortion function)
DPja ...(record-valued, parameters)
CPERRja ...(floating-valued, maximum value)

Their counterparts for sequent distortions are CQDISia, DQia, and CQERRia. An additional floating-valued keyword, DVERRa, records the maximum value of the combined distortions.

DPja and DQia are "record-valued". Syntactically, the keyvalues are standard FITS strings, but they are to be interpreted in a special way. The general form is

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

where the field-specifier consists of a sequence of fields separated by periods, and the ': ' between the field-specifier and the floating-point value is part of the record syntax. For example:

DP1 = 'AXIS.1: 1'

Certain field-specifiers are defined for all distortion functions, while others are defined only for particular distortions. Refer to WCS Paper IV for further details. wcspih() parses all distortion keywords and loads them into a disprm struct for analysis by disset() which knows (or possibly does not know) how to interpret them. Of the Paper IV distortion functions, only the general Polynomial distortion is currently implemented here.

TPV - the TPV "projection":
The distortion function component of the TPV celestial "projection" is also supported. The TPV projection, originally proposed in a draft of WCS Paper II, consists of a TAN projection with sequent polynomial distortion, the coefficients of which are encoded in PVi_ma keyrecords. Full details may be

http://fits.gsfc.nasa.gov/registry/tpvwcs/tpv.html

Internally, wcsset() changes TPV to a TAN projection, translates the PVi_ma keywords to DQia and loads them into a disprm struct. These DQia keyrecords have the form

DQia = 'TPV.m: <value>'

where i, a, m, and the value for each DQia match each PVi_ma. Consequently, WCSLIB would handle a FITS header containing these keywords, along with CQDISia = 'TPV' and the required DQia.NAXES and DQia.AXIS.ihat keywords.

Note that, as defined, TPV assumes that CDi_ja is used to define the linear transformation. The section on historical idiosyncrasies (below) cautions about translating CDi_ja to PCi_ja plus CDELTia in this case.

SIP - Simple Imaging Polynomial:
These routines also support the Simple Imaging Polynomial (SIP), whose design was influenced by early drafts of WCS Paper IV. It is described in detail in

http://fits.gsfc.nasa.gov/registry/sip.html

SIP, which is defined only as a prior distortion for 2-D celestial images, has the interesting feature that it records an approximation to the inverse polynomial distortion function. This is used by disx2p() to provide an initial estimate for its more precise iterative inversion. The special-purpose keywords used by SIP are parsed and translated by wcspih() as follows:

A_p_q = <value> -> DP1 = 'SIP.FWD.p_q: <value>'
AP_p_q = <value> -> DP1 = 'SIP.REV.p_q: <value>'
B_p_q = <value> -> DP2 = 'SIP.FWD.p_q: <value>'
BP_p_q = <value> -> DP2 = 'SIP.REV.p_q: <value>'
A_DMAX = <value> -> DPERR1 = <value>
B_DMAX = <value> -> DPERR2 = <value>

SIP's A_ORDER and B_ORDER keywords are not used. WCSLIB would recognise a FITS header containing the above keywords, along with CPDISja = 'SIP' and the required DPja.NAXES keywords.

DSS - Digitized Sky Survey:
The Digitized Sky Survey resulted from the production of the Guide Star Catalogue for the Hubble Space Telescope. Plate solutions based on a polynomial distortion function were encoded in FITS using non-standard keywords. Sect. 5.2 of WCS Paper IV describes how DSS coordinates may be translated to a sequent Polynomial distortion using two auxiliary variables. That translation is based on optimising the non-distortion component of the plate solution.

Following Paper IV, wcspih() translates the non-distortion component of DSS coordinates to standard WCS keywords (CRPIXja, PCi_ja, CRVALia, etc), and fills a wcsprm struct with their values. It encodes the DSS polynomial coefficients as

AMDXm = <value> -> DQ1 = 'AMD.m: <value>'
AMDYm = <value> -> DQ2 = 'AMD.m: <value>'

WCSLIB would recognise a FITS header containing the above keywords, along with CQDISia = 'DSS' and the required DQia.NAXES keywords.

WAT - the TNX and ZPX "projections":
The TNX and ZPX "projections" add a polynomial distortion function to the standard TAN and ZPN projections respectively. Unusually, the polynomial may be expressed as the sum of Chebyshev or Legendre polynomials, or as a simple sum of monomials, as described in

http://fits.gsfc.nasa.gov/registry/tnx/tnx-doc.html
http://fits.gsfc.nasa.gov/registry/zpxwcs/zpx.html

The polynomial coefficients are encoded in special-purpose WATi_n keywords as a set of continued strings, thus providing the name for this distortion type. WATi_n are parsed and translated by wcspih() into the following set:

DQi = 'WAT.POLY: <value>'
DQi = 'WAT.XMIN: <value>'
DQi = 'WAT.XMAX: <value>'
DQi = 'WAT.YMIN: <value>'
DQi = 'WAT.YMAX: <value>'
DQi = 'WAT.CHBY.m_n: <value>' or
DQi = 'WAT.LEGR.m_n: <value>' or
DQi = 'WAT.MONO.m_n: <value>'

along with CQDISia = 'WAT' and the required DPja.NAXES keywords. For ZPX, the ZPN projection parameters are also encoded in WATi_n, and wcspih() translates these to standard PVi_ma.

Note that, as defined, TNX and ZPX assume that CDi_ja is used to define the linear transformation. The section on historical idiosyncrasies (below) cautions about translating CDi_ja to PCi_ja plus CDELTia in this case.

TPD - Template Polynomial Distortion:
The "Template Polynomial Distortion" (TPD) is a superset of the TPV, SIP, DSS, and WAT (TNX & ZPX) polynomial distortions that also supports 1-D usage and inversions. Like TPV, SIP, and DSS, the form of the polynomial is fixed (the "template") and only the coefficients for the required terms are set non-zero. TPD generalizes TPV in going to 9th degree, SIP by accomodating TPV's linear and radial terms, and DSS in both respects. While in theory the degree of the WAT polynomial distortion in unconstrained, in practice it is limited to values that can be handled by TPD.

Within WCSLIB, TPV, SIP, DSS, and WAT are all implemented as special cases of TPD. Indeed, TPD was developed precisely for that purpose. WAT distortions expressed as the sum of Chebyshev or Legendre polynomials are expanded for TPD as a simple sum of monomials. Moreover, the general Polynomial distortion is translated and implemented internally as TPD whenever possible.

However, WCSLIB also recognizes 'TPD' as a distortion function in its own right (i.e. a recognized value of CPDISja or CQDISia), for use as both prior and sequent distortions. Its DPja and DQia keyrecords have the form

DPja = 'TPD.FWD.m: <value>'
DPja = 'TPD.REV.m: <value>'

for the forward and reverse distortion functions. Moreover, like the general Polynomial distortion, TPD supports auxiliary variables, though only as a linear transformation of pixel coordinates (p1,p2):

x = a0 + a1*p1 + a2*p2
y = b0 + b1*p1 + b2*p2

where the coefficients of the auxiliary variables (x,y) are recorded as

DPja = 'AUX.1.COEFF.0: a0' ...default 0.0
DPja = 'AUX.1.COEFF.1: a1' ...default 1.0
DPja = 'AUX.1.COEFF.2: a2' ...default 0.0
DPja = 'AUX.2.COEFF.0: b0' ...default 0.0
DPja = 'AUX.2.COEFF.1: b1' ...default 0.0
DPja = 'AUX.2.COEFF.2: b2' ...default 1.0

Though nowhere near as powerful, in typical applications TPD is considerably faster than the general Polynomial distortion. As TPD has a finite and not too large number of possible terms (60), the coefficients for each can be stored (by disset()) in a fixed location in the disprm::dparm[] array. A large part of the speedup then arises from evaluating the polynomial using Horner's scheme.

Separate implementations for polynomials of each degree, and conditionals for 1-D polynomials and 2-D polynomials with and without the radial variable, ensure that unused terms mostly do not impose a significant computational overhead.

The TPD terms are as follows

0: 1 4: xx 12: xxxx 24: xxxxxx 40: xxxxxxxx
5: xy 13: xxxy 25: xxxxxy 41: xxxxxxxy
1: x 6: yy 14: xxyy 26: xxxxyy 42: xxxxxxyy
2: y 15: xyyy 27: xxxyyy 43: xxxxxyyy
3: r 7: xxx 16: yyyy 28: xxyyyy 44: xxxxyyyy
8: xxy 29: xyyyyy 45: xxxyyyyy
9: xyy 17: xxxxx 30: yyyyyy 46: xxyyyyyy
10: yyy 18: xxxxy 47: xyyyyyyy
11: rrr 19: xxxyy 31: xxxxxxx 48: yyyyyyyy
20: xxyyy 32: xxxxxxy
21: xyyyy 33: xxxxxyy 49: xxxxxxxxx
22: yyyyy 34: xxxxyyy 50: xxxxxxxxy
23: rrrrr 35: xxxyyyy 51: xxxxxxxyy
36: xxyyyyy 52: xxxxxxyyy
37: xyyyyyy 53: xxxxxyyyy
38: yyyyyyy 54: xxxxyyyyy
39: rrrrrrr 55: xxxyyyyyy
56: xxyyyyyyy
57: xyyyyyyyy
58: yyyyyyyyy
59: rrrrrrrrr

where r = . Note that even powers of r are excluded since they can be accomodated by powers of .

Note here that "x" refers to the axis to which the distortion function is attached, with "y" being the complementary axis. So, for example, with longitude on axis 1 and latitude on axis 2, for TPD attached to axis 1, "x" refers to axis 1 and "y" to axis 2. For TPD attached to axis 2, "x" refers to axis 2, and "y" to axis 1.

TPV uses all terms up to 39. The m in its PVi_ma keywords translates directly to the TPD coefficient number.

SIP uses all terms except for 0, 3, 11, 23, 39, and 59, with terms 1 and 2 only used for the inverse. Its A_p_q, etc. keywords must be translated using a map.

DSS uses terms 0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 17, 19, and 21. The presence of a non-zero constant term arises through the use of auxiliary variables with origin offset from the reference point of the TAN projection. However, in the translation given by WCS Paper IV, the distortion polynomial is zero, or very close to zero, at the reference pixel itself. The mapping between DSS's AMDXm (or AMDYm) keyvalues and TPD coefficients, while still simple, is not quite as straightforward as for TPV and SIP.

WAT uses all but the radial terms, namely 3, 11, 23, 39, and 59. While the mapping between WAT's monomial coefficients and TPD is fairly simple, for its expression in terms of a sum of Chebyshev or Legendre polynomials it is much less so.

Historical idiosyncrasies:
In addition to the above, some historical distortion functions have further idiosyncrasies that must be taken into account when translating them to TPD.

WCS Paper IV specifies that a distortion function returns a correction to be added to pixel coordinates (prior distortion) or intermediate pixel coordinates (sequent distortion). The correction is meant to be small so that ignoring the distortion function, i.e. setting the correction to zero, produces a commensurately small error.

However, rather than an additive correction, some historical distortion functions (TPV, DSS) define a polynomial that returns the corrected coordinates directly.

The difference between the two approaches is readily accounted for simply by adding or subtracting 1 from the coefficient of the first degree term of the polynomial. However, it opens the way for considerable confusion.

Additional to the formalism of WCS Paper IV, both the Polynomial and TPD distortion functions recognise a keyword

DPja = 'DOCORR: 0'

which is meant to apply generally to indicate that the distortion function returns the corrected coordinates directly. Any other value for DOCORR (or its absence) indicates that the distortion function returns an additive correction.

WCS Paper IV also specifies that the independent variables of a distortion function are pixel coordinates (prior distortion) or intermediate pixel coordinates (sequent distortion).

On the contrary, the independent variables of the SIP polynomial are pixel coordinate offsets from the reference pixel. This is readily handled via the renormalisation parameters

DPja = 'OFFSET.jhat: <value>'

where the value corresponds to CRPIXja.

Likewise, because TPV, TNX, and ZPX are defined in terms of CDi_ja, the independent variables of the polynomial are intermediate world coordinates rather than intermediate pixel coordinates. Because sequent distortions are always applied before CDELTia, if CDi_ja is translated to PCi_ja plus CDELTia, then either CDELTia must be unity, or the distortion polynomial coefficients must be adjusted to account for the change of scale.

Summary of the dis routines:
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.

dpfill(), dpkeyi(), and dpkeyd() are provided to manage the dpkey struct.

disndp(), disini(), disinit(), discpy(), and disfree() are provided to manage the disprm struct, dissize() computes its total size including allocated memory, disenq() returns information about the state of the struct, and disprt() prints its contents.

disperr() prints the error message(s) (if any) stored in a disprm struct.

wcshdo() normally writes SIP and TPV headers in their native form if at all possible. However, dishdo() may be used to set a flag that tells it to write the header in the form of the TPD translation used internally.

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:

## Macro Definition Documentation

## ◆ DISP2X_ARGS

#define DISP2X_ARGS

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

## ◆ DISX2P_ARGS

#define DISX2P_ARGS

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

## ◆ DPLEN

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

## ◆ DISLEN

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

## Enumeration Type Documentation

## ◆ disenq_enum

enum disenq_enum

Enumerator
DISENQ_MEM |
DISENQ_SET |
DISENQ_BYP |

## ◆ dis_errmsg_enum

enum dis_errmsg_enum

Enumerator
DISERR_SUCCESS |
DISERR_NULL_POINTER |
DISERR_MEMORY |
DISERR_BAD_PARAM |
DISERR_DISTORT |
DISERR_DEDISTORT |

## Function Documentation

## ◆ disndp()

int disndp | ( | int | n | ) |

Memory allocation for DPja and DQia.

disndp() sets or gets the value of NDPMAX (default 256). This global variable controls the maximum number of dpkey structs, for holding DPja or DQia keyvalues, that disini() should allocate space for. It is also used by disinit() as the default value of ndpmax.

PLEASE NOTE: This function is not thread-safe.

Parameters

  [in] | n | Value of NDPMAX; ignored if < 0. Use a value less than zero to get the current value.

Returns
  Current value of NDPMAX.

## ◆ dpfill()

int dpfill | ( | struct dpkey * | dp,
|  | const char * | keyword,
|  | const char * | field,
|  | int | j,
|  | int | type,
|  | int | i,
|  | double | f )

Fill the contents of a dpkey struct.

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. If j is non-zero, and keyword was given, then the value of j will be used to fill in the axis number.
  [in] | type | Data type of the record's value 0: Integer, 1: Floating point.
  [in] | i | For type == 0, the integer value of the record.
  [in] | f | For type == 1, the floating point value of the record.

Returns
  Status return value:
  - 0: Success.

## ◆ dpkeyi()

int dpkeyi | ( | const struct dpkey * | dp | ) |

Get the data value in a dpkey struct as int.

dpkeyi() returns the data value in a dpkey struct as an integer value.

Parameters

  [in,out] | dp | Parsed contents of a DPja or DQia keyrecord.

Returns
  The record's value as int.

## ◆ dpkeyd()

double dpkeyd | ( | const struct dpkey * | dp | ) |

Get the data value in a dpkey struct as double.

dpkeyd() returns the data value in a dpkey struct as a floating point value.

Parameters

  [in,out] | dp | Parsed contents of a DPja or DQia keyrecord.

Returns
  The record's value as double.

## ◆ disini()

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

Default constructor for the disprm struct.

disini() is a thin wrapper on disinit(). It invokes it with ndpmax set to -1 which causes it to use the value of the global variable NDPMAX. It is thereby potentially thread-unsafe if NDPMAX is altered dynamically via disndp(). Use disinit() for a thread-safe alternative in this case.

## ◆ disinit()

int disinit | ( | int | alloc,
|  | int | naxis,
|  | struct disprm * | dis,
|  | int | ndpmax )

Default constructor for the disprm struct.

disinit() allocates memory for arrays in a disprm struct and sets all members of the struct to default values.

PLEASE NOTE: every disprm struct must be initialized by disinit(), 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 disinit() 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).
  [in] | ndpmax | The number of DPja or DQia keywords to allocate space for. If set to -1, the value of the global variable NDPMAX will be used. This is potentially thread-unsafe if disndp() is being used dynamically to alter its value.

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

## ◆ discpy()

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

Copy routine for the disprm struct.

discpy() does a deep copy of one disprm struct to another, using disinit() 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().

## ◆ disfree()

int disfree | ( | struct disprm * | dis | ) |

Destructor for the disprm struct.

disfree() frees memory allocated for the disprm arrays by disinit(). disinit() 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 disinit().

Parameters

  [in,out] | dis | Distortion function parameters.

Returns
  Status return value:
  - 0: Success.
  - 1: Null disprm pointer passed.

## ◆ dissize()

int dissize | ( | const struct disprm * | dis,
|  | int | sizes[2] )

Compute the size of a disprm struct.

dissize() computes the full size of a disprm struct, including allocated memory.

Parameters

  [in] | dis | Distortion function parameters. If NULL, the base size of the struct and the allocated size are both set to zero.
  [out] | sizes | The first element is the base size of the struct as returned by sizeof(struct disprm). The second element is the total allocated size, in bytes, assuming that the allocation was done by disini(). This figure includes memory allocated for members of constituent structs, such as disprm::dp. It is not an error for the struct not to have been set up via tabset(), which normally results in additional memory allocation.

Returns
  Status return value:
  - 0: Success.

## ◆ disenq()

int disenq | ( | const struct disprm * | dis,
|  | int | enquiry )

enquire about the state of a disprm struct.

disenq() may be used to obtain information about the state of a disprm struct. The function returns a true/false answer for the enquiry asked.

Parameters

  [in] | dis | Distortion function parameters.
  [in] | enquiry | Enquiry according to the following parameters: DISENQ_MEM: memory in the struct is being managed by WCSLIB (see disinit()). DISENQ_SET: the struct has been set up by disset(). DISENQ_BYP: the struct is in bypass mode (see disset()). These may be combined by logical OR, e.g. DISENQ_MEM | DISENQ_SET. The enquiry result will be the logical AND of the individual results.

Returns
  Enquiry result:
  - 0: No.
  - 1: Yes.

## ◆ disprt()

int disprt | ( | const struct disprm * | dis | ) |

Print routine for the disprm struct.

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.

## ◆ disperr()

int disperr | ( | const struct disprm * | dis,
|  | const char * | prefix )

Print error messages from a disprm struct.

disperr() prints the error message(s) (if any) stored in a disprm struct. If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.

Parameters

  [in] | dis | Distortion function parameters.
  [in] | prefix | If non-NULL, each output line will be prefixed with this string.

Returns
  Status return value:
  - 0: Success.
  - 1: Null disprm pointer passed.

## ◆ dishdo()

int dishdo | ( | struct disprm * | dis | ) |

write FITS headers using TPD.

dishdo() sets a flag that tells wcshdo() to write FITS headers in the form of the TPD translation used internally. Normally SIP and TPV would be written in their native form if at all possible.

Parameters

  [in,out] | dis | Distortion function parameters.

Returns
  Status return value:
  - 0: Success.
  - 1: Null disprm pointer passed.
  - 3: No TPD translation.

## ◆ disset()

int disset | ( | struct disprm * | dis | ) |

Setup routine for the disprm struct.

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.

disset() normally operates regardless of the value of disprm::flag; i.e. even if a struct was previously set up it will be reset unconditionally. However, a disprm struct may be put into "bypass" mode by invoking disset() initially with disprm::flag == 1 (rather than 0). disset() will return immediately if invoked on a struct in that state. To take a struct out of bypass mode, simply reset disprm::flag to zero. See also disenq().

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

## ◆ disp2x()

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

Apply distortion function.

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.

## ◆ disx2p()

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

Apply de-distortion function.

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.

If disprm::disx2p() is defined, then disx2p() uses it to provide an initial estimate for its more precise iterative inversion.

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

## ◆ diswarp()

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.

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.

## Variable Documentation

## ◆ dis_errmsg

const char* dis_errmsg[]
| extern

Status return messages.

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