WCSLIB: cel.h File Reference

WCSLIB 8.7

Loading...
Searching...
No Matches
Data Structures | Macros | Enumerations | Functions | Variables
cel.h File Reference
`#include "prj.h"`

Go to the source code of this file.

## Data Structures
struct | celprm
| Celestial transformation parameters. More...

## Macros
#define | CELLEN (sizeof(struct celprm)/sizeof(int))
| Size of the celprm struct in int units.
#define | celini_errmsg cel_errmsg
| Deprecated.
#define | celprt_errmsg cel_errmsg
| Deprecated.
#define | celset_errmsg cel_errmsg
| Deprecated.
#define | celx2s_errmsg cel_errmsg
| Deprecated.
#define | cels2x_errmsg cel_errmsg
| Deprecated.

## Enumerations
enum | celenq_enum { CELENQ_SET = 2 , CELENQ_BYP = 4 }
enum | cel_errmsg_enum { CELERR_SUCCESS = 0 , CELERR_NULL_POINTER = 1 , CELERR_BAD_PARAM = 2 , CELERR_BAD_COORD_TRANS = 3 , CELERR_ILL_COORD_TRANS = 4 , CELERR_BAD_PIX = 5 , CELERR_BAD_WORLD = 6 }

## Functions
int | celini (struct celprm *cel)
| Default constructor for the celprm struct.
int | celfree (struct celprm *cel)
| Destructor for the celprm struct.
int | celsize (const struct celprm *cel, int sizes[2])
| Compute the size of a celprm struct.
int | celenq (const struct celprm *cel, int enquiry)
| enquire about the state of a celprm struct.
int | celprt (const struct celprm *cel)
| Print routine for the celprm struct.
int | celperr (const struct celprm *cel, const char *prefix)
| Print error messages from a celprm struct.
int | celset (struct celprm *cel)
| Setup routine for the celprm struct.
int | celx2s (struct celprm *cel, int nx, int ny, int sxy, int sll, const double x[], const double y[], double phi[], double theta[], double lng[], double lat[], int stat[])
| Pixel-to-world celestial transformation.
int | cels2x (struct celprm *cel, int nlng, int nlat, int sll, int sxy, const double lng[], const double lat[], double phi[], double theta[], double x[], double y[], int stat[])
| World-to-pixel celestial transformation.

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

## Detailed Description

Routines in this suite implement the part of the FITS World Coordinate System (WCS) standard that deals with celestial coordinates, as 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)

These routines define methods to be used for computing celestial world coordinates from intermediate world coordinates (a linear transformation of image pixel coordinates), and vice versa. They are based on the celprm struct which contains all information needed for the computations. This struct contains some elements that must be set by the user, and others that are maintained by these routines, somewhat like a C++ class but with no encapsulation.

Routine celini() is provided to initialize the celprm struct with default values, celfree() reclaims any memory that may have been allocated to store an error message, celsize() computes its total size including allocated memory, celenq() returns information about the state of the struct, and celprt() prints its contents.

celperr() prints the error message(s), if any, stored in a celprm struct and the prjprm struct that it contains.

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

celx2s() and cels2x() implement the WCS celestial coordinate transformations. In fact, they are high level driver routines for the lower level spherical coordinate rotation and projection routines described in sph.h and prj.h.

## Macro Definition Documentation

## ◆ CELLEN

#define CELLEN (sizeof(struct celprm)/sizeof(int))

Size of the celprm struct in int units.

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

## ◆ celini_errmsg

#define celini_errmsg cel_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use cel_errmsg directly now instead.

## ◆ celprt_errmsg

#define celprt_errmsg cel_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use cel_errmsg directly now instead.

## ◆ celset_errmsg

#define celset_errmsg cel_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use cel_errmsg directly now instead.

## ◆ celx2s_errmsg

#define celx2s_errmsg cel_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use cel_errmsg directly now instead.

## ◆ cels2x_errmsg

#define cels2x_errmsg cel_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use cel_errmsg directly now instead.

## Enumeration Type Documentation

## ◆ celenq_enum

enum celenq_enum

Enumerator
CELENQ_SET |
CELENQ_BYP |

## ◆ cel_errmsg_enum

enum cel_errmsg_enum

Enumerator
CELERR_SUCCESS |
CELERR_NULL_POINTER |
CELERR_BAD_PARAM |
CELERR_BAD_COORD_TRANS |
CELERR_ILL_COORD_TRANS |
CELERR_BAD_PIX |
CELERR_BAD_WORLD |

## Function Documentation

## ◆ celini()

int celini | ( | struct celprm * | cel | ) |

Default constructor for the celprm struct.

celini() sets all members of a celprm struct to default values. It should be used to initialize every celprm struct.

PLEASE NOTE: If the celprm struct has already been initialized, then before reinitializing, it celfree() should be used to free any memory that may have been allocated to store an error message. A memory leak may otherwise result.

Parameters

  [out] | cel | Celestial transformation parameters.

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

## ◆ celfree()

int celfree | ( | struct celprm * | cel | ) |

Destructor for the celprm struct.

celfree() frees any memory that may have been allocated to store an error message in the celprm struct.

Parameters

  [in,out] | cel | Celestial transformation parameters.

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

## ◆ celsize()

int celsize | ( | const struct celprm * | cel,
|  | int | sizes[2] )

Compute the size of a celprm struct.

celsize() computes the full size of a celprm struct, including allocated memory.

Parameters

  [in] | cel | Celestial transformation 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 celprm). The second element is the total allocated size, in bytes. This figure includes memory allocated for the constituent struct, celprm::err. It is not an error for the struct not to have been set up via celset().

Returns
  Status return value:
  - 0: Success.

## ◆ celenq()

int celenq | ( | const struct celprm * | cel,
|  | int | enquiry )

enquire about the state of a celprm struct.

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

Parameters

  [in] | cel | Celestial transformation parameters.
  [in] | enquiry | Enquiry according to the following parameters: CELENQ_SET: the struct has been set up by celset(). CELENQ_BYP: the struct is in bypass mode (see celset()).

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

## ◆ celprt()

int celprt | ( | const struct celprm * | cel | ) |

Print routine for the celprm struct.

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

Parameters

  [in] | cel | Celestial transformation parameters.

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

## ◆ celperr()

int celperr | ( | const struct celprm * | cel,
|  | const char * | prefix )

Print error messages from a celprm struct.

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

Parameters

  [in] | cel | Coordinate transformation parameters.
  [in] | prefix | If non-NULL, each output line will be prefixed with this string.

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

## ◆ celset()

int celset | ( | struct celprm * | cel | ) |

Setup routine for the celprm struct.

celset() sets up a celprm struct according to information supplied within it.

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

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

Parameters

  [in,out] | cel | Celestial transformation parameters.

Returns
  Status return value:
  - 0: Success.
  - 1: Null celprm pointer passed.
  - 2: Invalid projection parameters.
  - 3: Invalid coordinate transformation parameters.
  - 4: Ill-conditioned coordinate transformation parameters.
  For returns > 1, a detailed error message is set in celprm::err if enabled, see wcserr_enable().

## ◆ celx2s()

int celx2s | ( | struct celprm * | cel,
|  | int | nx,
|  | int | ny,
|  | int | sxy,
|  | int | sll,
|  | const double | x[],
|  | const double | y[],
|  | double | phi[],
|  | double | theta[],
|  | double | lng[],
|  | double | lat[],
|  | int | stat[] )

Pixel-to-world celestial transformation.

celx2s() transforms coordinates in the plane of projection to celestial coordinates .

Parameters

  [in,out] | cel | Celestial transformation parameters.
  [in] | nx,ny | Vector lengths.
  [in] | sxy,sll | Vector strides.
  [in] | x,y | Projected coordinates in pseudo "degrees".
  [out] | phi,theta | Longitude and latitude in the native coordinate system of the projection [deg].
  [out] | lng,lat | Celestial longitude and latitude of the projected point [deg].
  [out] | stat | Status return value for each vector element: 0: Success. 1: Invalid value of .

Returns
  Status return value:
  - 0: Success.
  - 1: Null celprm pointer passed.
  - 2: Invalid projection parameters.
  - 3: Invalid coordinate transformation parameters.
  - 4: Ill-conditioned coordinate transformation parameters.
  - 5: One or more of the coordinates were invalid, as indicated by the stat vector.
  For returns > 1, a detailed error message is set in celprm::err if enabled, see wcserr_enable().

## ◆ cels2x()

int cels2x | ( | struct celprm * | cel,
|  | int | nlng,
|  | int | nlat,
|  | int | sll,
|  | int | sxy,
|  | const double | lng[],
|  | const double | lat[],
|  | double | phi[],
|  | double | theta[],
|  | double | x[],
|  | double | y[],
|  | int | stat[] )

World-to-pixel celestial transformation.

cels2x() transforms celestial coordinates to coordinates in the plane of projection.

Parameters

  [in,out] | cel | Celestial transformation parameters.
  [in] | nlng,nlat | Vector lengths.
  [in] | sll,sxy | Vector strides.
  [in] | lng,lat | Celestial longitude and latitude of the projected point [deg].
  [out] | phi,theta | Longitude and latitude in the native coordinate system of the projection [deg].
  [out] | x,y | Projected coordinates in pseudo "degrees".
  [out] | stat | Status return value for each vector element: 0: Success. 1: Invalid value of .

Returns
  Status return value:
  - 0: Success.
  - 1: Null celprm pointer passed.
  - 2: Invalid projection parameters.
  - 3: Invalid coordinate transformation parameters.
  - 4: Ill-conditioned coordinate transformation parameters.
  - 6: One or more of the coordinates were invalid, as indicated by the stat vector.
  For returns > 1, a detailed error message is set in celprm::err if enabled, see wcserr_enable().

## Variable Documentation

## ◆ cel_errmsg

const char* cel_errmsg[]
| extern

Status return messages.

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