World Coordinate System


Functions

cpl_error_code cpl_wcs_convert (const cpl_wcs *wcs, const cpl_matrix *from, cpl_matrix **to, cpl_array **status, cpl_wcs_trans_mode transform)
 Convert between physical and world coordinates.
void cpl_wcs_delete (cpl_wcs *wcs)
 Destroy a WCS structure.
const cpl_matrix * cpl_wcs_get_cd (const cpl_wcs *wcs)
 Accessor to get the CD matrix for a WCS.
const cpl_array * cpl_wcs_get_crpix (const cpl_wcs *wcs)
 Accessor to get the CRPIX vector for a WCS.
const cpl_array * cpl_wcs_get_crval (const cpl_wcs *wcs)
 Accessor to get the CRVAL vector for a WCS.
const cpl_array * cpl_wcs_get_image_dims (const cpl_wcs *wcs)
 Accessor to get the axis lengths of the image associated with a WCS.
int cpl_wcs_get_image_naxis (const cpl_wcs *wcs)
 Accessor to get the dimensionality of the image associated with a WCS.
cpl_wcs * cpl_wcs_new_from_propertylist (const cpl_propertylist *plist)
 Create a wcs structure by parsing a propertylist.
cpl_error_code cpl_wcs_platesol (cpl_propertylist *ilist, cpl_matrix *cel, cpl_matrix *xy, int niter, float thresh, cpl_wcs_platesol_fitmode fitmode, cpl_wcs_platesol_outmode outmode, cpl_propertylist **olist)
 Do a 2d plate solution given physical and celestial coordinates.

Detailed Description

This module provides functions to manipulate FITS World Coordinate Systems

A cpl_wcs is an object containing a pointer to the WCSLIB structure and the physical dimensions of the image from which the WCS was read. The functionality provided includes general transformations between physical and world coordinates as well as a few convenience routines for x,y <=> RA,Dec transformations.

Synopsis:
   #include "cpl_wcs.h"

Function Documentation

cpl_error_code cpl_wcs_convert ( const cpl_wcs *  wcs,
const cpl_matrix *  from,
cpl_matrix **  to,
cpl_array **  status,
cpl_wcs_trans_mode  transform 
)

Convert between physical and world coordinates.

Parameters:
wcs The input cpl_wcs structure
from The input coordinate matrix
to The output coordinate matrix
status The output status array
transform The transformation mode
Returns:
An appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter wcs is a NULL pointer, the parameter from is a NULL pointer or wcs is missing some of its information.
CPL_ERROR_UNSPECIFIED No rows or columns in the input matrix, or an unspecified error has occurred in the WCSLIB routine
CPL_ERROR_UNSUPPORTED_MODE The input conversion mode is not supported
CPL_ERROR_NO_WCS The WCS sub library is not available.

This function converts between several types of coordinates. These include: -- physical coordinates: The physical location on a detector (i.e. pixel coordinates) -- world coordinates: The real astronomical coordinate system for the observations. This may be spectral, celestial, time, etc. -- standard coordinates: These are an intermediate relative coordinate representation, defined as a distance from a reference point in the natural units of the world coordinate system. Any defined projection geometry will have already been included in the definition of standard coordinates.

The supported conversion modes are: -- CPL_WCS_PHYS2WORLD: Converts input physical to world coordinates -- CPL_WCS_WORLD2PHYS: Converts input world to physical coordinates -- CPL_WCS_WORLD2STD: Converts input world to standard coordinates -- CPL_WCS_PHYS2STD: Converts input physical to standard coordinates The output matrix and status arrays will be allocated here, and thus will need to be freed by the calling routine. The status array is used to flag input coordinates where there has been some sort of failure in the transformation.

void cpl_wcs_delete ( cpl_wcs *  wcs  ) 

Destroy a WCS structure.

Parameters:
wcs The WCS structure to destroy
Returns:
Nothing.
Errors:
CPL_ERROR_NO_WCS The WCS sub library is not available.
The function destroys the WCS structure wcs and its whole contents. If wcs is NULL, nothing is done and no error is set.

const cpl_matrix* cpl_wcs_get_cd ( const cpl_wcs *  wcs  ) 

Accessor to get the CD matrix for a WCS.

Parameters:
wcs The WCS structure to examine
Returns:
A handle to a matrix with the CDi_ja linear transformation matrix.
Errors:
CPL_ERROR_NO_WCS The WCS sub library is not available.
The function returns a handle to a matrix with the CD matrix defined for this WCS.

const cpl_array* cpl_wcs_get_crpix ( const cpl_wcs *  wcs  ) 

Accessor to get the CRPIX vector for a WCS.

Parameters:
wcs The WCS structure to examine
Returns:
A handle to an array with the CRPIXja keyvalues for each pixel axis.
Errors:
CPL_ERROR_NO_WCS The WCS sub library is not available.
The function returns a handle to an array with the CRPIX vector defined for this WCS.

const cpl_array* cpl_wcs_get_crval ( const cpl_wcs *  wcs  ) 

Accessor to get the CRVAL vector for a WCS.

Parameters:
wcs The WCS structure to examine
Returns:
A handle to an array with the CRVALia keyvalues for each coord axis.
Errors:
CPL_ERROR_NO_WCS The WCS sub library is not available.
The function returns a handle to an array with the CRVAL vector defined for this WCS.

const cpl_array* cpl_wcs_get_image_dims ( const cpl_wcs *  wcs  ) 

Accessor to get the axis lengths of the image associated with a WCS.

Parameters:
wcs The WCS structure to examine
Returns:
An array with the image axis sizes
Errors:
CPL_ERROR_NO_WCS The WCS sub library is not available.
The function returns a handle to an array with the axis lengths of the image associated with this WCS. If no image was used to define the WCS then a NULL value will be returned.

int cpl_wcs_get_image_naxis ( const cpl_wcs *  wcs  ) 

Accessor to get the dimensionality of the image associated with a WCS.

Parameters:
wcs The WCS structure to examine
Returns:
The image dimensionality
Errors:
CPL_ERROR_NO_WCS The WCS sub library is not available.
The function returns the dimensionality of the image associated with a WCS. If no image was used to define the WCS then a value of zero is returned.

cpl_wcs* cpl_wcs_new_from_propertylist ( const cpl_propertylist plist  ) 

Create a wcs structure by parsing a propertylist.

Parameters:
plist The input propertylist
Returns:
The newly created and filled cpl_wcs object or NULL if it could not be created. In the latter case an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter plist is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH NAXIS information in image propertylist is not an integer
CPL_ERROR_DATA_NOT_FOUND Error in getting NAXIS information for image propertylists
CPL_ERROR_UNSPECIFIED An unspecified error occurred in the WCSLIB routine.
CPL_ERROR_NO_WCS The WCS sub library is not available.

The function allocates memory for a WCS structure. A pointer to the WCSLIB header information is created by parsing the FITS WCS keywords from the header of a file. A few ancillary items are also filled in.

The returned property must be destroyed using the wcs destructor cpl_wcs_delete().

See also:
cpl_wcs_delete()

cpl_error_code cpl_wcs_platesol ( cpl_propertylist ilist,
cpl_matrix *  cel,
cpl_matrix *  xy,
int  niter,
float  thresh,
cpl_wcs_platesol_fitmode  fitmode,
cpl_wcs_platesol_outmode  outmode,
cpl_propertylist **  olist 
)

Do a 2d plate solution given physical and celestial coordinates.

Parameters:
ilist The input property list containing the first pass WCS
cel The celestial coordinate matrix
xy The physical coordinate matrix
niter The number of fitting iterations
thresh The threshold for the fitting rejection cycle
fitmode The fitting mode (see below)
outmode The output mode (see below)
olist The output propertylist containing the new WCS
Returns:
An appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter cel is a NULL pointer, the parameter xy is a NULL pointer or ilist is a NULL pointer.
CPL_ERROR_UNSPECIFIED Unable to parse the input propertylist into a proper FITS WCS or there are too few points in the input matrices for a fit.
CPL_ERROR_INCOMPATIBLE_INPUT The matrices cel and xy have different sizes.
CPL_ERROR_UNSUPPORTED_MODE Either fitmode or outmode are specified incorrectly
CPL_ERROR_NO_WCS The WCS sub library is not available.

This function allows for the following type of fits: -- CPL_WCS_PLATESOL_4: Fit for zero point, 1 scale and 1 rotation. -- CPL_WCS_PLATESOL_6: Fit for zero point, 2 scales, 1 rotation, 1 shear.

This fucntion allows the zeropoint to be defined by shifting either the physical or the celestial coordinates of the reference point: -- CPL_WCS_MV_CRVAL: Keeps the physical point fixed and shifts the celestial -- CPL_WCS_MV_CRPIX: Keeps the celestial point fixed and shifts the physical

The output propertylist contains WCS relevant information only.


Generated on Wed Mar 18 09:40:13 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7