Loading...
Searching...
No Matches
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.
cpl_wcs * | cpl_wcs_duplicate (const cpl_wcs *self)
| Create a copy of the given wcs.
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);
cpl_matrix_new
cpl_matrix * cpl_matrix_new(cpl_size rows, cpl_size columns)
Create a zero matrix of given size.
Definition cpl_matrix.c:400

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_duplicate()

cpl_wcs * cpl_wcs_duplicate | ( | const cpl_wcs * | self | ) |

Create a copy of the given wcs.

Parameters

  self | The input wcs object to copy.

Returns
  The created copy or `NULL` in case an error occurred.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The parameter self does not contain WCS information.

The function creates a deep copy of the given wcs self, i.e the created copy and the original wcs self do not share any resources.

References cpl_array_get_int(), cpl_array_set_int(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

## 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().