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 coordiantes.
void cpl_wcs_delete (cpl_wcs *wcs)
 Destroy a WCS structure.
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 coordiantes.

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.

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_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 Thu Mar 6 17:29:21 2008 for Common Pipeline Library Reference Manual by  doxygen 1.5.1