WCSLIB  6.2
Data Structures | Macros | Enumerations | Functions | Variables
wcs.h File Reference
#include "lin.h"
#include "cel.h"
#include "spc.h"

Go to the source code of this file.

Data Structures

struct  pvcard
 Store for PVi_ma keyrecords. More...
 
struct  pscard
 Store for PSi_ma keyrecords. More...
 
struct  wcsprm
 Coordinate transformation parameters. More...
 

Macros

#define WCSSUB_LONGITUDE   0x1001
 Mask for extraction of longitude axis by wcssub(). More...
 
#define WCSSUB_LATITUDE   0x1002
 Mask for extraction of latitude axis by wcssub(). More...
 
#define WCSSUB_CUBEFACE   0x1004
 Mask for extraction of CUBEFACE axis by wcssub(). More...
 
#define WCSSUB_CELESTIAL   0x1007
 Mask for extraction of celestial axes by wcssub(). More...
 
#define WCSSUB_SPECTRAL   0x1008
 Mask for extraction of spectral axis by wcssub(). More...
 
#define WCSSUB_STOKES   0x1010
 Mask for extraction of STOKES axis by wcssub(). More...
 
#define WCSCOMPARE_ANCILLARY   0x0001
 
#define WCSCOMPARE_TILING   0x0002
 
#define WCSCOMPARE_CRPIX   0x0004
 
#define PVLEN   (sizeof(struct pvcard)/sizeof(int))
 
#define PSLEN   (sizeof(struct pscard)/sizeof(int))
 
#define WCSLEN   (sizeof(struct wcsprm)/sizeof(int))
 Size of the wcsprm struct in int units. More...
 
#define wcscopy(alloc, wcssrc, wcsdst)   wcssub(alloc, wcssrc, 0x0, 0x0, wcsdst)
 Copy routine for the wcsprm struct. More...
 
#define wcsini_errmsg   wcs_errmsg
 Deprecated. More...
 
#define wcssub_errmsg   wcs_errmsg
 Deprecated. More...
 
#define wcscopy_errmsg   wcs_errmsg
 Deprecated. More...
 
#define wcsfree_errmsg   wcs_errmsg
 Deprecated. More...
 
#define wcsprt_errmsg   wcs_errmsg
 Deprecated. More...
 
#define wcsset_errmsg   wcs_errmsg
 Deprecated. More...
 
#define wcsp2s_errmsg   wcs_errmsg
 Deprecated. More...
 
#define wcss2p_errmsg   wcs_errmsg
 Deprecated. More...
 
#define wcsmix_errmsg   wcs_errmsg
 Deprecated. More...
 

Enumerations

enum  wcs_errmsg_enum {
  WCSERR_SUCCESS = 0, WCSERR_NULL_POINTER = 1, WCSERR_MEMORY = 2, WCSERR_SINGULAR_MTX = 3,
  WCSERR_BAD_CTYPE = 4, WCSERR_BAD_PARAM = 5, WCSERR_BAD_COORD_TRANS = 6, WCSERR_ILL_COORD_TRANS = 7,
  WCSERR_BAD_PIX = 8, WCSERR_BAD_WORLD = 9, WCSERR_BAD_WORLD_COORD = 10, WCSERR_NO_SOLUTION = 11,
  WCSERR_BAD_SUBIMAGE = 12, WCSERR_NON_SEPARABLE = 13
}
 

Functions

int wcsnpv (int n)
 Memory allocation for PVi_ma. More...
 
int wcsnps (int n)
 Memory allocation for PSi_ma. More...
 
int wcsini (int alloc, int naxis, struct wcsprm *wcs)
 Default constructor for the wcsprm struct. More...
 
int wcsinit (int alloc, int naxis, struct wcsprm *wcs, int npvmax, int npsmax, int ndpmax)
 Default constructor for the wcsprm struct. More...
 
int wcssub (int alloc, const struct wcsprm *wcssrc, int *nsub, int axes[], struct wcsprm *wcsdst)
 Subimage extraction routine for the wcsprm struct. More...
 
int wcscompare (int cmp, double tol, const struct wcsprm *wcs1, const struct wcsprm *wcs2, int *equal)
 Compare two wcsprm structs for equality. More...
 
int wcsfree (struct wcsprm *wcs)
 Destructor for the wcsprm struct. More...
 
int wcsprt (const struct wcsprm *wcs)
 Print routine for the wcsprm struct. More...
 
int wcsperr (const struct wcsprm *wcs, const char *prefix)
 Print error messages from a wcsprm struct. More...
 
int wcsbchk (struct wcsprm *wcs, int bounds)
 Enable/disable bounds checking. More...
 
int wcsset (struct wcsprm *wcs)
 Setup routine for the wcsprm struct. More...
 
int wcsp2s (struct wcsprm *wcs, int ncoord, int nelem, const double pixcrd[], double imgcrd[], double phi[], double theta[], double world[], int stat[])
 Pixel-to-world transformation. More...
 
int wcss2p (struct wcsprm *wcs, int ncoord, int nelem, const double world[], double phi[], double theta[], double imgcrd[], double pixcrd[], int stat[])
 World-to-pixel transformation. More...
 
int wcsmix (struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[], double vstep, int viter, double world[], double phi[], double theta[], double imgcrd[], double pixcrd[])
 Hybrid coordinate transformation. More...
 
int wcssptr (struct wcsprm *wcs, int *i, char ctype[9])
 Spectral axis translation. More...
 
const char * wcslib_version (int vers[3])
 

Variables

const char * wcs_errmsg []
 Status return messages. More...
 

Detailed Description

Routines in this suite implement the FITS World Coordinate System (WCS) standard which defines methods to be used for computing world coordinates from image pixel coordinates, and vice versa. The standard, and proposed extensions for handling distortions, are described in

"Representations of world coordinates in FITS",
Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
"Representations of celestial coordinates in FITS",
Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (WCS Paper II)
"Representations of spectral coordinates in FITS",
Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
2006, A&A, 446, 747 (WCS Paper III)
"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/people/Mark.Calabretta
"Mapping on the HEALPix grid",
Calabretta, M.R., & Roukema, B.F. 2007, MNRAS, 381, 865 (WCS Paper V)
"Representing the 'Butterfly' Projection in FITS -- Projection Code XPH",
Calabretta, M.R., & Lowe, S.R. 2013, PASA, 30, e050 (WCS Paper VI)
"Representations of time coordinates in FITS -
Time and relative dimension in space",
Rots, A.H., Bunclark, P.S., Calabretta, M.R., Allen, S.L.,
Manchester, R.N., & Thompson, W.T. 2015, A&A, 574, A36 (WCS Paper VII)

These routines are based on the wcsprm 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.

wcsnpv(), wcsnps(), wcsini(), wcsinit(), wcssub(), and wcsfree() are provided to manage the wcsprm struct and another, wcsprt(), prints its contents. Refer to the description of the wcsprm struct for an explanation of the anticipated usage of these routines. wcscopy(), which does a deep copy of one wcsprm struct to another, is defined as a preprocessor macro function that invokes wcssub().

wcsperr() prints the error message(s) (if any) stored in a wcsprm struct, and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.

A setup routine, wcsset(), computes intermediate values in the wcsprm struct from parameters in it that were supplied by the user. The struct always needs to be set up by wcsset() but this need not be called explicitly - refer to the explanation of wcsprm::flag.

wcsp2s() and wcss2p() implement the WCS world coordinate transformations. In fact, they are high level driver routines for the WCS linear, logarithmic, celestial, spectral and tabular transformation routines described in lin.h, log.h, cel.h, spc.h and tab.h.

Given either the celestial longitude or latitude plus an element of the pixel coordinate a hybrid routine, wcsmix(), iteratively solves for the unknown elements.

wcssptr() translates the spectral axis in a wcsprm struct. For example, a 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.

wcslib_version() returns the WCSLIB version number.

Quadcube projections:
The quadcube projections (TSC, CSC, QSC) may be represented in FITS in either of two ways:

a: The six faces may be laid out in one plane and numbered as follows:

0
4 3 2 1 4 3 2
5

Faces 2, 3 and 4 may appear on one side or the other (or both). The world-to-pixel routines map faces 2, 3 and 4 to the left but the pixel-to-world routines accept them on either side.

b: The "COBE" convention in which the six faces are stored in a three-dimensional structure using a CUBEFACE axis indexed from 0 to 5 as above.

These routines support both methods; wcsset() determines which is being used by the presence or absence of a CUBEFACE axis in ctype[]. wcsp2s() and wcss2p() translate the CUBEFACE axis representation to the single plane representation understood by the lower-level WCSLIB projection routines.

Macro Definition Documentation

◆ WCSSUB_LONGITUDE

#define WCSSUB_LONGITUDE   0x1001

Mask to use for extracting the longitude axis when sub-imaging, refer to the axes argument of wcssub().

◆ WCSSUB_LATITUDE

#define WCSSUB_LATITUDE   0x1002

Mask to use for extracting the latitude axis when sub-imaging, refer to the axes argument of wcssub().

◆ WCSSUB_CUBEFACE

#define WCSSUB_CUBEFACE   0x1004

Mask to use for extracting the CUBEFACE axis when sub-imaging, refer to the axes argument of wcssub().

◆ WCSSUB_CELESTIAL

#define WCSSUB_CELESTIAL   0x1007

Mask to use for extracting the celestial axes (longitude, latitude and cubeface) when sub-imaging, refer to the axes argument of wcssub().

◆ WCSSUB_SPECTRAL

#define WCSSUB_SPECTRAL   0x1008

Mask to use for extracting the spectral axis when sub-imaging, refer to the axes argument of wcssub().

◆ WCSSUB_STOKES

#define WCSSUB_STOKES   0x1010

Mask to use for extracting the STOKES axis when sub-imaging, refer to the axes argument of wcssub().

◆ WCSCOMPARE_ANCILLARY

#define WCSCOMPARE_ANCILLARY   0x0001

◆ WCSCOMPARE_TILING

#define WCSCOMPARE_TILING   0x0002

◆ WCSCOMPARE_CRPIX

#define WCSCOMPARE_CRPIX   0x0004

◆ PVLEN

#define PVLEN   (sizeof(struct pvcard)/sizeof(int))

◆ PSLEN

#define PSLEN   (sizeof(struct pscard)/sizeof(int))

◆ WCSLEN

#define WCSLEN   (sizeof(struct wcsprm)/sizeof(int))

Size of the wcsprm struct in int units, used by the Fortran wrappers.

◆ wcscopy

#define wcscopy (   alloc,
  wcssrc,
  wcsdst 
)    wcssub(alloc, wcssrc, 0x0, 0x0, wcsdst)

wcscopy() does a deep copy of one wcsprm struct to another. As of WCSLIB 3.6, it is implemented as a preprocessor macro that invokes wcssub() with the nsub and axes pointers both set to zero.

◆ wcsini_errmsg

#define wcsini_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

◆ wcssub_errmsg

#define wcssub_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

◆ wcscopy_errmsg

#define wcscopy_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

◆ wcsfree_errmsg

#define wcsfree_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

◆ wcsprt_errmsg

#define wcsprt_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

◆ wcsset_errmsg

#define wcsset_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

◆ wcsp2s_errmsg

#define wcsp2s_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

◆ wcss2p_errmsg

#define wcss2p_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

◆ wcsmix_errmsg

#define wcsmix_errmsg   wcs_errmsg
Deprecated:
Added for backwards compatibility, use wcs_errmsg directly now instead.

Enumeration Type Documentation

◆ wcs_errmsg_enum

Enumerator
WCSERR_SUCCESS 
WCSERR_NULL_POINTER 
WCSERR_MEMORY 
WCSERR_SINGULAR_MTX 
WCSERR_BAD_CTYPE 
WCSERR_BAD_PARAM 
WCSERR_BAD_COORD_TRANS 
WCSERR_ILL_COORD_TRANS 
WCSERR_BAD_PIX 
WCSERR_BAD_WORLD 
WCSERR_BAD_WORLD_COORD 
WCSERR_NO_SOLUTION 
WCSERR_BAD_SUBIMAGE 
WCSERR_NON_SEPARABLE 

Function Documentation

◆ wcsnpv()

int wcsnpv ( int  n)

wcsnpv() sets or gets the value of NPVMAX (default 64). This global variable controls the number of pvcard structs, for holding PVi_ma keyvalues, that wcsini() should allocate space for. It is also used by wcsinit() as the default value of npvmax.

PLEASE NOTE: This function is not thread-safe.

Parameters
[in]nValue of NPVMAX; ignored if < 0. Use a value less than zero to get the current value.
Returns
Current value of NPVMAX.

◆ wcsnps()

int wcsnps ( int  n)

wcsnps() sets or gets the value of NPSMAX (default 8). This global variable controls the number of pscard structs, for holding PSi_ma keyvalues, that wcsini() should allocate space for. It is also used by wcsinit() as the default value of npsmax.

PLEASE NOTE: This function is not thread-safe.

Parameters
[in]nValue of NPSMAX; ignored if < 0. Use a value less than zero to get the current value.
Returns
Current value of NPSMAX.

◆ wcsini()

int wcsini ( int  alloc,
int  naxis,
struct wcsprm wcs 
)

wcsini() is a thin wrapper on wcsinit(). It invokes it with npvmax, npsmax, and ndpmax set to -1 which causes it to use the values of the global variables NDPMAX, NPSMAX, and NDPMAX. It is thereby potentially thread-unsafe if these variables are altered dynamically via wcsnpv(), wcsnps(), and disndp(). Use wcsinit() for a thread-safe alternative in this case.

◆ wcsinit()

int wcsinit ( int  alloc,
int  naxis,
struct wcsprm wcs,
int  npvmax,
int  npsmax,
int  ndpmax 
)

wcsinit() optionally allocates memory for arrays in a wcsprm struct and sets all members of the struct to default values.

PLEASE NOTE: every wcsprm struct should be initialized by wcsinit(), possibly repeatedly. On the first invokation, and only the first invokation, wcsprm::flag must be set to -1 to initialize memory management, regardless of whether wcsinit() will actually be used to allocate memory.

Parameters
[in]allocIf true, allocate memory unconditionally for the crpix, etc. arrays.
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]naxisThe number of world coordinate axes. This is used to determine the length of the various wcsprm vectors and matrices and therefore the amount of memory to allocate for them.
[in,out]wcsCoordinate transformation parameters.
Note that, in order to initialize memory management, wcsprm::flag should be set to -1 when wcs is initialized for the first time (memory leaks may result if it had already been initialized).
[in]npvmaxThe number of PVi_ma keywords to allocate space for. If set to -1, the value of the global variable NPVMAX will be used. This is potentially thread-unsafe if wcsnpv() is being used dynamically to alter its value.
[in]npsmaxThe number of PSi_ma keywords to allocate space for. If set to -1, the value of the global variable NPSMAX will be used. This is potentially thread-unsafe if wcsnps() is being used dynamically to alter its value.
[in]ndpmaxThe 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 wcsprm pointer passed.
  • 2: Memory allocation failed.
For returns > 1, a detailed error message is set in wcsprm::err if enabled, see wcserr_enable().

◆ wcssub()

int wcssub ( int  alloc,
const struct wcsprm wcssrc,
int *  nsub,
int  axes[],
struct wcsprm wcsdst 
)

wcssub() extracts the coordinate description for a subimage from a wcsprm struct. It does a deep copy, using wcsinit() to allocate memory for its arrays if required. Only the "information to be provided" part of the struct is extracted. Consequently, wcsset() need not have been, and won't be invoked on the struct from which the subimage is extracted. A call to wcsset() is required to set up the subimage struct.

The world coordinate system of the subimage must be separable in the sense that the world coordinates at any point in the subimage must depend only on the pixel coordinates of the axes extracted. In practice, this means that the linear transformation matrix of the original image must not contain non-zero off-diagonal terms that associate any of the subimage axes with any of the non-subimage axes. Likewise, if any distortions are associated with the subimage axes, they must not depend on any of the axes that are not being extracted.

Note that while the required elements of the tabprm array are extracted, the wtbarr array is not. (Thus it is not appropriate to call wcssub() after wcstab() but before filling the tabprm structs - refer to wcshdr.h.)

wcssub() can also add axes to a wcsprm struct. The new axes will be created using the defaults set by wcsinit() which produce a simple, unnamed, linear axis with world coordinate equal to the pixel coordinate. These default values can be changed afterwards, before invoking wcsset().

Parameters
[in]allocIf true, allocate memory for the crpix, etc. 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]wcssrcStruct to extract from.
[in,out]nsub
[in,out]axesVector of length *nsub containing the image axis numbers (1-relative) to extract. Order is significant; axes[0] is the axis number of the input image that corresponds to the first axis in the subimage, etc.
Use an axis number of 0 to create a new axis using the defaults set by wcsinit(). They can be changed later.
nsub (the pointer) may be set to zero, and so also may *nsub, which is interpreted to mean all axes in the input image; the number of axes will be returned if nsub != 0x0. axes itself (the pointer) may be set to zero to indicate the first *nsub axes in their original order.
Set both nsub (or *nsub) and axes to zero to do a deep copy of one wcsprm struct to another.
Subimage extraction by coordinate axis type may be done by setting the elements of axes[] to the following special preprocessor macro values:
  • WCSSUB_LONGITUDE: Celestial longitude.
  • WCSSUB_LATITUDE: Celestial latitude.
  • WCSSUB_CUBEFACE: Quadcube CUBEFACE axis.
  • WCSSUB_SPECTRAL: Spectral axis.
  • WCSSUB_STOKES: Stokes axis.
Refer to the notes (below) for further usage examples.
On return, *nsub will be set to the number of axes in the subimage; this may be zero if there were no axes of the required type(s) (in which case no memory will be allocated). axes[] will contain the axis numbers that were extracted, or 0 for newly created axes. The vector length must be sufficient to contain all axis numbers. No checks are performed to verify that the coordinate axes are consistent, this is done by wcsset().
[in,out]wcsdstStruct describing the subimage. wcsprm::flag should be set to -1 if wcsdst was not previously initialized (memory leaks may result if it was previously initialized).
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 12: Invalid subimage specification.
  • 13: Non-separable subimage coordinate system.
For returns > 1, a detailed error message is set in wcsprm::err if enabled, see wcserr_enable().

Notes:
Combinations of subimage axes of particular types may be extracted in the same order as they occur in the input image by combining preprocessor codes, for example

would extract the longitude, latitude, and spectral axes in the same order as the input image. If one of each were present, *nsub = 3 would be returned.

For convenience, WCSSUB_CELESTIAL is defined as the combination WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.

The codes may also be negated to extract all but the types specified, for example

*nsub = 4;
axes[0] = WCSSUB_LONGITUDE;
axes[1] = WCSSUB_LATITUDE;
axes[2] = WCSSUB_CUBEFACE;

The last of these specifies all axis types other than spectral or Stokes. Extraction is done in the order specified by axes[] a longitude axis (if present) would be extracted first (via axes[0]) and not subsequently (via axes[3]). Likewise for the latitude and cubeface axes in this example.

From the foregoing, it is apparent that the value of *nsub returned may be less than or greater than that given. However, it will never exceed the number of axes in the input image (plus the number of newly-created axes if any were specified on input).

◆ wcscompare()

int wcscompare ( int  cmp,
double  tol,
const struct wcsprm wcs1,
const struct wcsprm wcs2,
int *  equal 
)

wcscompare() compares two wcsprm structs for equality.

Parameters
[in]cmpA bit field controlling the strictness of the comparison. When 0, all fields must be identical.
The following constants may be or'ed together to relax the comparison:
  • WCSCOMPARE_ANCILLARY: Ignore ancillary keywords that don't change the WCS transformation, such as DATE-OBS or EQUINOX.
  • WCSCOMPARE_TILING: Ignore integral differences in CRPIXja. This is the 'tiling' condition, where two WCSes cover different regions of the same map projection and align on the same map grid.
  • WCSCOMPARE_CRPIX: Ignore any differences at all in CRPIXja. The two WCSes cover different regions of the same map projection but may not align on the same grid map. Overrides WCSCOMPARE_TILING.
[in]tolTolerance for comparison of floating-point values. For example, for tol == 1e-6, all floating-point values in the structs must be equal to the first 6 decimal places. A value of 0 implies exact equality.
[in]wcs1The first wcsprm struct to compare.
[in]wcs2The second wcsprm struct to compare.
[out]equalNon-zero when the given structs are equal.
Returns
Status return value:
  • 0: Success.
  • 1: Null pointer passed.

◆ wcsfree()

int wcsfree ( struct wcsprm wcs)

wcsfree() frees memory allocated for the wcsprm arrays by wcsinit() and/or wcsset(). wcsinit() records the memory it allocates and wcsfree() will only attempt to free this.

PLEASE NOTE: wcsfree() must not be invoked on a wcsprm struct that was not initialized by wcsinit().

Parameters
[out]wcsCoordinate transformation parameters.
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.

◆ wcsprt()

int wcsprt ( const struct wcsprm wcs)

wcsprt() prints the contents of a wcsprm struct using wcsprintf(). Mainly intended for diagnostic purposes.

Parameters
[in]wcsCoordinate transformation parameters.
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.

◆ wcsperr()

int wcsperr ( const struct wcsprm wcs,
const char *  prefix 
)

wcsperr() prints the error message(s), if any, stored in a wcsprm struct, and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains. If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.

Parameters
[in]wcsCoordinate transformation parameters.
[in]prefixIf non-NULL, each output line will be prefixed with this string.
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.

◆ wcsbchk()

int wcsbchk ( struct wcsprm wcs,
int  bounds 
)

wcsbchk() is used to control bounds checking in the projection routines. Note that wcsset() always enables bounds checking. wcsbchk() will invoke wcsset() on the wcsprm struct beforehand if necessary.

Parameters
[in,out]wcsCoordinate transformation parameters.
[in]boundsIf bounds&1 then enable strict bounds checking for the spherical-to-Cartesian (s2x) transformation for the AZP, SZP, TAN, SIN, ZPN, and COP projections.
If bounds&2 then enable strict bounds checking for the Cartesian-to-spherical (x2s) transformation for the HPX and XPH projections.
If bounds&4 then enable bounds checking on the native coordinates returned by the Cartesian-to-spherical (x2s) transformations using prjchk().
Zero it to disable all checking.
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.

◆ wcsset()

int wcsset ( struct wcsprm wcs)

wcsset() sets up a wcsprm struct according to information supplied within it (refer to the description of the wcsprm struct).

wcsset() recognizes the NCP projection and converts it to the equivalent SIN projection and likewise translates GLS into SFL. It also translates the AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.), possibly changing the input header keywords wcsprm::ctype and/or wcsprm::specsys if necessary.

Note that this routine need not be called directly; it will be invoked by wcsp2s() and wcss2p() if the wcsprm::flag is anything other than a predefined magic value.

Parameters
[in,out]wcsCoordinate transformation parameters.
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 3: Linear transformation matrix is singular.
  • 4: Inconsistent or unrecognized coordinate axis types.
  • 5: Invalid parameter value.
  • 6: Invalid coordinate transformation parameters.
  • 7: Ill-conditioned coordinate transformation parameters.
For returns > 1, a detailed error message is set in wcsprm::err if enabled, see wcserr_enable().

Notes:
wcsset() always enables strict bounds checking in the projection routines (via a call to prjini()). Use wcsbchk() to modify bounds-checking after wcsset() is invoked.

◆ wcsp2s()

int wcsp2s ( struct wcsprm wcs,
int  ncoord,
int  nelem,
const double  pixcrd[],
double  imgcrd[],
double  phi[],
double  theta[],
double  world[],
int  stat[] 
)

wcsp2s() transforms pixel coordinates to world coordinates.

Parameters
[in,out]wcsCoordinate transformation parameters.
[in]ncoord,nelemThe number of coordinates, each of vector length nelem but containing wcs.naxis coordinate elements. Thus nelem must equal or exceed the value of the NAXIS keyword unless ncoord == 1, in which case nelem is not used.
[in]pixcrdArray of pixel coordinates.
[out]imgcrdArray of intermediate world coordinates. For celestial axes, imgcrd[][wcs.lng] and imgcrd[][wcs.lat] are the projected $x$-, and $y$-coordinates in pseudo "degrees". For spectral axes, imgcrd[][wcs.spec] is the intermediate spectral coordinate, in SI units.
[out]phi,thetaLongitude and latitude in the native coordinate system of the projection [deg].
[out]worldArray of world coordinates. For celestial axes, world[][wcs.lng] and world[][wcs.lat] are the celestial longitude and latitude [deg]. For spectral axes, imgcrd[][wcs.spec] is the intermediate spectral coordinate, in SI units.
[out]statStatus return value for each coordinate:
  • 0: Success.
1+: A bit mask indicating invalid pixel coordinate element(s).
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 3: Linear transformation matrix is singular.
  • 4: Inconsistent or unrecognized coordinate axis types.
  • 5: Invalid parameter value.
  • 6: Invalid coordinate transformation parameters.
  • 7: Ill-conditioned coordinate transformation parameters.
  • 8: One or more of the pixel coordinates were invalid, as indicated by the stat vector.
For returns > 1, a detailed error message is set in wcsprm::err if enabled, see wcserr_enable().

◆ wcss2p()

int wcss2p ( struct wcsprm wcs,
int  ncoord,
int  nelem,
const double  world[],
double  phi[],
double  theta[],
double  imgcrd[],
double  pixcrd[],
int  stat[] 
)

wcss2p() transforms world coordinates to pixel coordinates.

Parameters
[in,out]wcsCoordinate transformation parameters.
[in]ncoord,nelemThe number of coordinates, each of vector length nelem but containing wcs.naxis coordinate elements. Thus nelem must equal or exceed the value of the NAXIS keyword unless ncoord == 1, in which case nelem is not used.
[in]worldArray of world coordinates. For celestial axes, world[][wcs.lng] and world[][wcs.lat] are the celestial longitude and latitude [deg]. For spectral axes, world[][wcs.spec] is the spectral coordinate, in SI units.
[out]phi,thetaLongitude and latitude in the native coordinate system of the projection [deg].
[out]imgcrdArray of intermediate world coordinates. For celestial axes, imgcrd[][wcs.lng] and imgcrd[][wcs.lat] are the projected $x$-, and $y$-coordinates in pseudo "degrees". For quadcube projections with a CUBEFACE axis the face number is also returned in imgcrd[][wcs.cubeface]. For spectral axes, imgcrd[][wcs.spec] is the intermediate spectral coordinate, in SI units.
[out]pixcrdArray of pixel coordinates.
[out]statStatus return value for each coordinate:
  • 0: Success.
1+: A bit mask indicating invalid world coordinate element(s).
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 3: Linear transformation matrix is singular.
  • 4: Inconsistent or unrecognized coordinate axis types.
  • 5: Invalid parameter value.
  • 6: Invalid coordinate transformation parameters.
  • 7: Ill-conditioned coordinate transformation parameters.
  • 9: One or more of the world coordinates were invalid, as indicated by the stat vector.
For returns > 1, a detailed error message is set in wcsprm::err if enabled, see wcserr_enable().

◆ wcsmix()

int wcsmix ( struct wcsprm wcs,
int  mixpix,
int  mixcel,
const double  vspan[],
double  vstep,
int  viter,
double  world[],
double  phi[],
double  theta[],
double  imgcrd[],
double  pixcrd[] 
)

wcsmix(), given either the celestial longitude or latitude plus an element of the pixel coordinate, solves for the remaining elements by iterating on the unknown celestial coordinate element using wcss2p(). Refer also to the notes below.

Parameters
[in,out]wcsIndices for the celestial coordinates obtained by parsing the wcsprm::ctype[].
[in]mixpixWhich element of the pixel coordinate is given.
[in]mixcelWhich element of the celestial coordinate is given:
  • 1: Celestial longitude is given in world[wcs.lng], latitude returned in world[wcs.lat].
  • 2: Celestial latitude is given in world[wcs.lat], longitude returned in world[wcs.lng].
[in]vspanSolution interval for the celestial coordinate [deg]. The ordering of the two limits is irrelevant. Longitude ranges may be specified with any convenient normalization, for example [-120,+120] is the same as [240,480], except that the solution will be returned with the same normalization, i.e. lie within the interval specified.
[in]vstepStep size for solution search [deg]. If zero, a sensible, although perhaps non-optimal default will be used.
[in]viterIf a solution is not found then the step size will be halved and the search recommenced. viter controls how many times the step size is halved. The allowed range is 5 - 10.
[in,out]worldWorld coordinate elements. world[wcs.lng] and world[wcs.lat] are the celestial longitude and latitude [deg]. Which is given and which returned depends on the value of mixcel. All other elements are given.
[out]phi,thetaLongitude and latitude in the native coordinate system of the projection [deg].
[out]imgcrdImage coordinate elements. imgcrd[wcs.lng] and imgcrd[wcs.lat] are the projected $x$-, and $y$-coordinates in pseudo "degrees".
[in,out]pixcrdPixel coordinate. The element indicated by mixpix is given and the remaining elements are returned.
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 3: Linear transformation matrix is singular.
  • 4: Inconsistent or unrecognized coordinate axis types.
  • 5: Invalid parameter value.
  • 6: Invalid coordinate transformation parameters.
  • 7: Ill-conditioned coordinate transformation parameters.
  • 10: Invalid world coordinate.
  • 11: No solution found in the specified interval.
For returns > 1, a detailed error message is set in wcsprm::err if enabled, see wcserr_enable().

Notes:
Initially the specified solution interval is checked to see if it's a "crossing" interval. If it isn't, a search is made for a crossing solution by iterating on the unknown celestial coordinate starting at the upper limit of the solution interval and decrementing by the specified step size. A crossing is indicated if the trial value of the pixel coordinate steps through the value specified. If a crossing interval is found then the solution is determined by a modified form of "regula falsi" division of the crossing interval. If no crossing interval was found within the specified solution interval then a search is made for a "non-crossing" solution as may arise from a point of tangency. The process is complicated by having to make allowance for the discontinuities that occur in all map projections.

Once one solution has been determined others may be found by subsequent invokations of wcsmix() with suitably restricted solution intervals.

Note the circumstance that arises when the solution point lies at a native pole of a projection in which the pole is represented as a finite curve, for example the zenithals and conics. In such cases two or more valid solutions may exist but wcsmix() only ever returns one.

Because of its generality wcsmix() is very compute-intensive. For compute-limited applications more efficient special-case solvers could be written for simple projections, for example non-oblique cylindrical projections.

◆ wcssptr()

int wcssptr ( struct wcsprm wcs,
int *  i,
char  ctype[9] 
)

wcssptr() translates the spectral axis in a wcsprm struct. For example, a 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.

Parameters
[in,out]wcsCoordinate transformation parameters.
[in,out]iIndex of the spectral axis (0-relative). If given < 0 it will be set to the first spectral axis identified from the ctype[] keyvalues in the wcsprm struct.
[in,out]ctypeDesired spectral CTYPEia. Wildcarding may be used as for the ctypeS2 argument to spctrn() as described in the prologue of spc.h, i.e. if the final three characters are specified as "???", or if just the eighth character is specified as '?', the correct algorithm code will be substituted and returned.
Returns
Status return value:
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 3: Linear transformation matrix is singular.
  • 4: Inconsistent or unrecognized coordinate axis types.
  • 5: Invalid parameter value.
  • 6: Invalid coordinate transformation parameters.
  • 7: Ill-conditioned coordinate transformation parameters.
  • 12: Invalid subimage specification (no spectral axis).
For returns > 1, a detailed error message is set in wcsprm::err if enabled, see wcserr_enable().

◆ wcslib_version()

const char* wcslib_version ( int  vers[3])

Variable Documentation

◆ wcs_errmsg

const char * wcs_errmsg[]

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