World Coordinate System

Macros
#define	CPL_WCS_REGEXP
	A regular expression that matches the FITS keys used for WCS.

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_ctype (const cpl_wcs *wcs)
	Accessor to get the CTYPE vector for a WCS.
const cpl_array *	cpl_wcs_get_cunit (const cpl_wcs *wcs)
	Accessor to get the CUNIT 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 (const cpl_propertylist *ilist, const cpl_matrix *cel, const 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"

Macro Definition Documentation

CPL_WCS_REGEXP

#define CPL_WCS_REGEXP

A regular expression that matches the FITS keys used for WCS.

Function Documentation

cpl_wcs_convert()

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, from, to or status 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. Alternatively, the number of columns in from and the NAXIS-value in wcs are different
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 input cpl_matrix from has to be filled with coordinates. The number of rows equals the number of objects and the number of columns has to be equal to the value of the NAXIS keyword in the wcs structure. The same convention is used for the output cpl_matrix to. For example, if an image contains NAXIS = 2 and 100 stars with positions X,Y, the new matrix will be created:

from = cpl_matrix_new(100, 2);

Each element in column 0 will take a X coordinate and each element in column 1 will take a Y coordinate.

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. For historical reasons, the output matrix and status arrays are allocated also in case of some (but not all) failures. If not allocated, they are set to NULL. Also for historical reasons, when allocated and regardless whether the call succeeds, the status array has all its elements defined yet all status elements are flagged as invalid.

References cpl_array_delete(), cpl_array_get_data_int(), cpl_array_new(), cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NO_WCS, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSPECIFIED, CPL_ERROR_UNSUPPORTED_MODE, cpl_matrix_get_ncol(), cpl_matrix_get_nrow(), cpl_matrix_wrap(), and CPL_TYPE_INT.

Referenced by cpl_wcs_platesol().

cpl_wcs_delete()

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.

References cpl_array_delete(), cpl_array_unwrap(), CPL_ERROR_NO_WCS, cpl_free(), and cpl_matrix_delete().

Referenced by cpl_wcs_platesol().

cpl_wcs_get_cd()

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, or NULL on error.

Errors

CPL_ERROR_NULL_INPUT	The parameter wcs is a NULL pointer.
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.

References cpl_ensure, CPL_ERROR_NO_WCS, and CPL_ERROR_NULL_INPUT.

cpl_wcs_get_crpix()

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, or NULL on error.

Errors

CPL_ERROR_NULL_INPUT	The parameter wcs is a NULL pointer.
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.

References cpl_ensure, CPL_ERROR_NO_WCS, and CPL_ERROR_NULL_INPUT.

cpl_wcs_get_crval()

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, or NULL on error.

Errors

CPL_ERROR_NULL_INPUT	The parameter wcs is a NULL pointer.
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.

References cpl_ensure, CPL_ERROR_NO_WCS, and CPL_ERROR_NULL_INPUT.

cpl_wcs_get_ctype()

const cpl_array * cpl_wcs_get_ctype

(

const cpl_wcs *

wcs

)

Accessor to get the CTYPE vector for a WCS.

Parameters

wcs	The WCS structure to examine

Returns

A handle to an array with the CTYPEja keyvalues for each pixel axis, or NULL on error.

Errors

CPL_ERROR_NULL_INPUT	The parameter wcs is a NULL pointer.
CPL_ERROR_NO_WCS	The WCS sub library is not available.

The function returns a handle to an array with the CTYPE vector defined for this WCS.

References cpl_ensure, CPL_ERROR_NO_WCS, and CPL_ERROR_NULL_INPUT.

cpl_wcs_get_cunit()

const cpl_array * cpl_wcs_get_cunit

(

const cpl_wcs *

wcs

)

Accessor to get the CUNIT vector for a WCS.

Parameters

wcs	The WCS structure to examine

Returns

A handle to an array with the CUNITja keyvalues for each pixel axis, or NULL on error.

Errors

CPL_ERROR_NULL_INPUT	The parameter wcs is a NULL pointer.
CPL_ERROR_NO_WCS	The WCS sub library is not available.

The function returns a handle to an array with the CUNIT vector defined for this WCS.

References cpl_ensure, CPL_ERROR_NO_WCS, and CPL_ERROR_NULL_INPUT.

cpl_wcs_get_image_dims()

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, or NULL on error.

Errors

CPL_ERROR_NULL_INPUT	The parameter wcs is a NULL pointer.
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.

References cpl_ensure, CPL_ERROR_NO_WCS, and CPL_ERROR_NULL_INPUT.

cpl_wcs_get_image_naxis()

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, or zero on error

Errors

CPL_ERROR_NULL_INPUT	The parameter wcs is a NULL pointer.
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.

References cpl_ensure, CPL_ERROR_NO_WCS, and CPL_ERROR_NULL_INPUT.

cpl_wcs_new_from_propertylist()

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.

It is allowed to pass a cpl_propertylist with a valid WCS structure and NAXIS = 0, such a propertylist can be created by cpl_wcs_platesol(). In this case a cpl_wcs object is returned for which the dimensional information (accessible via cpl_wcs_get_image_dims()) will be NULL.

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

See also

cpl_wcs_delete()

References cpl_ensure, CPL_ERROR_NO_WCS, and CPL_ERROR_NULL_INPUT.

cpl_wcs_platesol()

cpl_error_code cpl_wcs_platesol	(	const cpl_propertylist *	ilist,
		const cpl_matrix *	cel,
		const 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 property list 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_ILLEGAL_INPUT	The parameter niter is non-positive.
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_DATA_NOT_FOUND	The threshold is so low that no valid points are found. If the threshold is not positive, this error is certain to occur.
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 function 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 property list contains WCS relevant information only.

The matrices cel, and xy have to be set up in the same way as it is required for cpl_wcs_convert(). See the documentation of cpl_wcs_convert() for details.

See also

cpl_wcs_convert()

References cpl_array_delete(), cpl_array_get_data_double_const(), cpl_array_wrap_int(), cpl_calloc(), cpl_ensure_code, CPL_ERROR_DATA_NOT_FOUND, cpl_error_get_code(), CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NO_WCS, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSPECIFIED, CPL_ERROR_UNSUPPORTED_MODE, cpl_errorstate_get(), cpl_errorstate_is_equal(), cpl_free(), cpl_malloc(), cpl_matrix_delete(), cpl_matrix_get(), cpl_matrix_get_data_const(), cpl_matrix_get_nrow(), cpl_property_delete(), cpl_property_set_double(), cpl_propertylist_insert_after_property(), cpl_propertylist_new(), CPL_SIZE_FORMAT, CPL_TYPE_DOUBLE, cpl_wcs_convert(), and cpl_wcs_delete().