WCSLIB 4.4: wcsprm Struct Reference

int wcsprm::flag

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

wcsprm::naxis (q.v., not normally set by the user),
wcsprm::crpix,
wcsprm::pc,
wcsprm::cdelt,
wcsprm::crval,
wcsprm::cunit,
wcsprm::ctype,
wcsprm::lonpole,
wcsprm::latpole,
wcsprm::restfrq,
wcsprm::restwav,
wcsprm::npv,
wcsprm::pv,
wcsprm::nps,
wcsprm::ps,
wcsprm::cd,
wcsprm::crota,
wcsprm::altlin.

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

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

int wcsprm::naxis

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

If wcsini() is used to initialize the linprm 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.

double * wcsprm::crpix

(Given) Address of the first element of an array of double containing the coordinate reference pixel, CRPIXja.

double * wcsprm::pc

(Given) Address of the first element of the PCi_ja (pixel coordinate) transformation matrix. The expected order is

        struct wcsprm wcs;
        wcs.pc = {PC1_1, PC1_2, PC2_1, PC2_2};

This may be constructed conveniently from a 2-D array via

        double m[2][2] = {{PC1_1, PC1_2},
                          {PC2_1, PC2_2}};

which is equivalent to

        double m[2][2];
        m[0][0] = PC1_1;
        m[0][1] = PC1_2;
        m[1][0] = PC2_1;
        m[1][1] = PC2_2;

The storage order for this 2-D array is the same as for the 1-D array, whence

        wcs.pc = *m;

would be legitimate.

double * wcsprm::cdelt

(Given) Address of the first element of an array of double containing the coordinate increments, CDELTia.

double * wcsprm::crval

(Given) Address of the first element of an array of double containing the coordinate reference values, CRVALia.

wcsprm::cunit

(Given) Address of the first element of an array of char[72] containing the CUNITia keyvalues which define the units of measurement of the CRVALia, CDELTia, and CDi_ja keywords.

As CUNITia is an optional header keyword, cunit[][72] may be left blank but otherwise is expected to contain a standard units specification as defined by WCS Paper I. Utility function wcsutrn(), described in wcsunits.h, is available to translate commonly used non-standard units specifications but this must be done as a separate step before invoking wcsset().

For celestial axes, if cunit[][72] is not blank, wcsset() uses wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to degrees. It then resets cunit[][72] to "deg".

For spectral axes, if cunit[][72] is not blank, wcsset() uses wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to SI units. It then resets cunit[][72] accordingly.

wcsset() ignores cunit[][72] for other coordinate types; cunit[][72] may be used to label coordinate values.

These variables accomodate the longest allowed string-valued FITS keyword, being limited to 68 characters, plus the null-terminating character.

wcsprm::ctype

(Given) Address of the first element of an array of char[72] containing the coordinate axis types, CTYPEia.

The ctype[][72] keyword values must be in upper case and there must be zero or one pair of matched celestial axis types, and zero or one spectral axis. The ctype[][72] strings should be padded with blanks on the right and null-terminated so that they are at least eight characters in length.

These variables accomodate the longest allowed string-valued FITS keyword, being limited to 68 characters, plus the null-terminating character.

double wcsprm::lonpole

(Given and returned) The native longitude of the celestial pole, $\phi_{\mathrm p}$ , given by LONPOLEa [deg] or by PVi_2a [deg] attached to the longitude axis which takes precedence if defined, and ...

double wcsprm::latpole

(Given and returned) ... the native latitude of the celestial pole, $\theta_{\mathrm p}$ , given by LATPOLEa [deg] or by PVi_3a [deg] attached to the longitude axis which takes precedence if defined.

lonpole and latpole may be left to default to values set by wcsini() (see celprm::ref), but in any case they will be reset by wcsset() to the values actually used. Note therefore that if the wcsprm struct is reused without resetting them, whether directly or via wcsini(), they will no longer have their default values.

double wcsprm::restfrq

(Given) The rest frequency [Hz], and/or ...

double wcsprm::restwav

(Given) ... the rest wavelength in vacuuo [m], only one of which need be given, the other should be set to zero.

int wcsprm::npv

(Given) The number of entries in the wcsprm::pv[] array.

int wcsprm::npvmax

(Given or returned) The length of the wcsprm::pv[] array.

npvmax will be set by wcsini() if it allocates memory for wcsprm::pv[], otherwise it must be set by the user. See also wcsnpv().

struct pvcard * wcsprm::pv

(Given or returned) Address of the first element of an array of length npvmax of pvcard structs. Set by wcsini() if it allocates memory for pv[], otherwise it must be set by the user. See also wcsnpv().

As a FITS header parser encounters each PVi_ma keyword it should load it into a pvcard struct in the array and increment npv. wcsset() interprets these as required.

Note that, if they were not given, wcsset() resets the entries for PVi_1a, PVi_2a, PVi_3a, and PVi_4a for longitude axis i to match $(\phi_0,\theta_0)$ , the native longitude and latitude of the reference point given by LONPOLEa and LATPOLEa.

int wcsprm::nps

(Given) The number of entries in the wcsprm::ps[] array.

int wcsprm::npsmax

(Given or returned) The length of the wcsprm::ps[] array.

npsmax will be set by wcsini() if it allocates memory for wcsprm::ps[], otherwise it must be set by the user. See also wcsnps().

struct pscard * wcsprm::ps

(Given or returned) Address of the first element of an array of length npsmax of pscard structs. Set by wcsini() if it allocates memory for ps[], otherwise it must be set by the user. See also wcsnps().

As a FITS header parser encounters each PSi_ma keyword it should load it into a pscard struct in the array and increment nps. wcsset() interprets these as required (currently no PSi_ma keyvalues are recognized).

double * wcsprm::cd

(Given) For historical compatibility, the wcsprm struct supports two alternate specifications of the linear transformation matrix, those associated with the CDi_ja keywords, and ...

double * wcsprm::crota

(Given) ... those associated with the CROTAia keywords. Although these may not formally co-exist with PCi_ja, the approach taken here is simply to ignore them if given in conjunction with PCi_ja.

int wcsprm::altlin

(Given) altlin is a bit flag that denotes which of the PCi_ja, CDi_ja and CROTAia keywords are present in the header:

Bit 0: PCi_ja is present.
Bit 1: CDi_ja is present.
Matrix elements in the IRAF convention are equivalent to the product CDi_ja = CDELTia * PCi_ja, but the defaults differ from that of the PCi_ja matrix. If one or more CDi_ja keywords are present then all unspecified CDi_ja default to zero. If no CDi_ja (or CROTAia) keywords are present, then the header is assumed to be in PCi_ja form whether or not any PCi_ja keywords are present since this results in an interpretation of CDELTia consistent with the original FITS specification.
While CDi_ja may not formally co-exist with PCi_ja, it may co-exist with CDELTia and CROTAia which are to be ignored.
Bit 2: CROTAia is present.
In the AIPS convention, CROTAia may only be associated with the latitude axis of a celestial axis pair. It specifies a rotation in the image plane that is applied AFTER the CDELTia; any other CROTAia keywords are ignored.
CROTAia may not formally co-exist with PCi_ja.
CROTAia and CDELTia may formally co-exist with CDi_ja but if so are to be ignored.

CDi_ja and CROTAia keywords, if found, are to be stored in the wcsprm::cd and wcsprm::crota arrays which are dimensioned similarly to wcsprm::pc and wcsprm::cdelt. FITS header parsers should use the following procedure:

Whenever a PCi_ja keyword is encountered:
```
 altlin |= 1; 
```
Whenever a CDi_ja keyword is encountered:
```
 altlin |= 2; 
```
Whenever a CROTAia keyword is encountered:
```
 altlin |= 4; 
```

If none of these bits are set the PCi_ja representation results, i.e. wcsprm::pc and wcsprm::cdelt will be used as given.

These alternate specifications of the linear transformation matrix are translated immediately to PCi_ja by wcsset() and are invisible to the lower-level WCSLIB routines. In particular, wcsset() resets wcsprm::cdelt to unity if CDi_ja is present (and no PCi_ja).

If CROTAia are present but none is associated with the latitude axis (and no PCi_ja or CDi_ja), then wcsset() reverts to a unity PCi_ja matrix.

int wcsprm::padding

(An unused variable inserted for alignment purposes only.)

char wcsprm::alt

(Given, auxiliary) Character code for alternate coordinate descriptions (i.e. the 'a' in keyword names such as CTYPEia). This is blank for the primary coordinate description, or one of the 26 upper-case letters, A-Z.

An array of four characters is provided for alignment purposes, only the first is used.

int wcsprm::colnum

(Given, auxiliary) Where the coordinate representation is associated with an image-array column in a FITS binary table, this variable may be used to record the relevant column number.

It should be set to zero for an image header or pixel list.

int * wcsprm::colax

(Given, auxiliary) Address of the first element of an array of int recording the column numbers for each axis in a pixel list.

The array elements should be set to zero for an image header or image array in a binary table.

wcsprm::cname

(Given, auxiliary) The address of the first element of an array of char[72] containing the coordinate axis names, CNAMEia.

These variables accomodate the longest allowed string-valued FITS keyword, being limited to 68 characters, plus the null-terminating character.

double * wcsprm::crder

(Given, auxiliary) Address of the first element of an array of double recording the random error in the coordinate value, CRDERia.

double * wcsprm::csyer

(Given, auxiliary) Address of the first element of an array of double recording the systematic error in the coordinate value, CSYERia.

char wcsprm::dateavg

(Given, auxiliary) The date of a representative mid-point of the observation in ISO format, yyyy-mm-ddThh:mm:ss.

char wcsprm::dateobs

(Given, auxiliary) The date of the start of the observation unless otherwise explained in the comment field of the DATE-OBS keyword, in ISO format, yyyy-mm-ddThh:mm:ss.

double wcsprm::equinox

(Given, auxiliary) The equinox associated with dynamical equatorial or ecliptic coordinate systems, EQUINOXa (or EPOCH in older headers). Not applicable to ICRS equatorial or ecliptic coordinates.

double wcsprm::mjdavg

(Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-AVG, corresponding to DATE-AVG.

double wcsprm::mjdobs

(Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-OBS, corresponding to DATE-OBS.

double wcsprm::obsgeo

(Given, auxiliary) Location of the observer in a standard terrestrial reference frame, OBSGEO-X, OBSGEO-Y, OBSGEO-Z [m].

char wcsprm::radesys

(Given, auxiliary) The equatorial or ecliptic coordinate system type, RADESYSa.

char wcsprm::specsys

(Given, auxiliary) Spectral reference frame (standard of rest), SPECSYSa, and ...

char wcsprm::ssysobs

(Given, auxiliary) ... the actual frame in which there is no differential variation in the spectral coordinate across the field-of-view, SSYSOBSa.

double wcsprm::velosys

(Given, auxiliary) The relative radial velocity [m/s] between the observer and the selected standard of rest in the direction of the celestial reference coordinate, VELOSYSa.

double wcsprm::zsource

(Given, auxiliary) The redshift, ZSOURCEa, of the source, and ...

char wcsprm::ssyssrc

(Given, auxiliary) ... the spectral reference frame (standard of rest) in which this was measured, SSYSSRCa.

double wcsprm::velangl

(Given, auxiliary) The angle [deg] that should be used to decompose an observed velocity into radial and transverse components.

char wcsprm::wcsname

(Given, auxiliary) The name given to the coordinate representation, WCSNAMEa. This variable accomodates the longest allowed string-valued FITS keyword, being limited to 68 characters, plus the null-terminating character.

int wcsprm::ntab

(Given) See wcsprm::tab.

int wcsprm::nwtb

(Given) See wcsprm::wtb.

struct tabprm * wcsprm::tab

(Given) Address of the first element of an array of ntab tabprm structs for which memory has been allocated. These are used to store tabular transformation parameters.

Although technically wcsprm::ntab and tab are "given", they will normally be set by invoking wcstab(), whether directly or indirectly.

The tabprm structs contain some members that must be supplied and others that are derived. The information to be supplied comes primarily from arrays stored in one or more FITS binary table extensions. These arrays, referred to here as "wcstab arrays", are themselves located by parameters stored in the FITS image header.

struct wtbarr * wcsprm::wtb

(Given) Address of the first element of an array of nwtb wtbarr structs for which memory has been allocated. These are used in extracting wcstab arrays from a FITS binary table.

Although technically wcsprm::nwtb and wtb are "given", they will normally be set by invoking wcstab(), whether directly or indirectly.

int * wcsprm::types

(Returned) Address of the first element of an array of int containing a four-digit type code for each axis.

First digit (i.e. 1000s):
- 0: Non-specific coordinate type.
- 1: Stokes coordinate.
- 2: Celestial coordinate (including CUBEFACE).
- 3: Spectral coordinate.
Second digit (i.e. 100s):
- 0: Linear axis.
- 1: Quantized axis (STOKES, CUBEFACE).
- 2: Non-linear celestial axis.
- 3: Non-linear spectral axis.
- 4: Logarithmic axis.
- 5: Tabular axis.
Third digit (i.e. 10s):
- 0: Group number, e.g. lookup table number, being an index into the tabprm array (see above).
The fourth digit is used as a qualifier depending on the axis type.
- For celestial axes:
  - 0: Longitude coordinate.
  - 1: Latitude coordinate.
  - 2: CUBEFACE number.
- For lookup tables: the axis number in a multidimensional table.

CTYPEia in "4-3" form with unrecognized algorithm code will have its type set to -1 and generate an error.

char wcsprm::lngtyp

(Returned) Four-character WCS celestial longitude and ...

char wcsprm::lattyp

(Returned) ... latitude axis types. e.g. "RA", "DEC", "GLON", "GLAT", etc. extracted from 'RA--', 'DEC-', 'GLON', 'GLAT', etc. in the first four characters of CTYPEia but with trailing dashes removed. (Declared as char[8] for alignment reasons.)

int wcsprm::lng

(Returned) Index for the longitude coordinate, and ...

int wcsprm::lat

(Returned) ... index for the latitude coordinate, and ...

int wcsprm::spec

(Returned) ... index for the spectral coordinate in the imgcrd[][] and world[][] arrays in the API of wcsp2s(), wcss2p() and wcsmix().

These may also serve as indices into the pixcrd[][] array provided that the PCi_ja matrix does not transpose axes.

int wcsprm::cubeface

(Returned) Index into the pixcrd[][] array for the CUBEFACE axis. This is used for quadcube projections where the cube faces are stored on a separate axis (see wcs.h).

struct linprm wcsprm::lin

(Returned) Linear transformation parameters (usage is described in the prologue to lin.h).

struct celprm wcsprm::cel

(Returned) Celestial transformation parameters (usage is described in the prologue to cel.h).

struct spcprm wcsprm::spc

(Returned) Spectral transformation parameters (usage is described in the prologue to spc.h).

int wcsprm::m_flag

(For internal use only.)

int wcsprm::m_naxis

(For internal use only.)

double * wcsprm::m_crpix

(For internal use only.)

double * wcsprm::m_pc

(For internal use only.)

double * wcsprm::m_cdelt

(For internal use only.)

double * wcsprm::m_crval

(For internal use only.)

wcsprm::m_cunit

(For internal use only.)

wcsprm::m_ctype

(For internal use only.)

struct pvcard * wcsprm::m_pv

(For internal use only.)

struct pscard * wcsprm::m_ps

(For internal use only.)

double * wcsprm::m_cd

(For internal use only.)

double * wcsprm::m_crota

(For internal use only.)

int * wcsprm::m_colax

(For internal use only.)

wcsprm::m_cname

(For internal use only.)

double * wcsprm::m_crder

(For internal use only.)

double * wcsprm::m_csyer

(For internal use only.)

struct tabprm * wcsprm::m_tab

(For internal use only.)

struct wtbarr * wcsprm::m_wtb

(For internal use only.)

wcsprm Struct Reference

Data Fields

Detailed Description

Field Documentation


Data Fields
int	flag
int	naxis
double *	crpix
double *	pc
double *	cdelt
double *	crval
char(*	cunit )[72]
char(*	ctype )[72]
double	lonpole
double	latpole
double	restfrq
double	restwav
int	npv
int	npvmax
pvcard *	pv
int	nps
int	npsmax
pscard *	ps
double *	cd
double *	crota
int	altlin
int	padding
char	alt [4]
int	colnum
int *	colax
char(*	cname )[72]
double *	crder
double *	csyer
char	dateavg [72]
char	dateobs [72]
double	equinox
double	mjdavg
double	mjdobs
double	obsgeo [3]
char	radesys [72]
char	specsys [72]
char	ssysobs [72]
double	velosys
double	zsource
char	ssyssrc [72]
double	velangl
char	wcsname [72]
int	ntab
int	nwtb
tabprm *	tab
wtbarr *	wtb
int *	types
char	lngtyp [8]
char	lattyp [8]
int	lng
int	lat
int	spec
int	cubeface
linprm	lin
celprm	cel
spcprm	spc
int	m_flag
int	m_naxis
double *	m_crpix
double *	m_pc
double *	m_cdelt
double *	m_crval
char(*	m_cunit )[72]
char((*	m_ctype )[72]
pvcard *	m_pv
pscard *	m_ps
double *	m_cd
double *	m_crota
int *	m_colax
char(*	m_cname )[72]
double *	m_crder
double *	m_csyer
tabprm *	m_tab
wtbarr *	m_wtb