# E.S.O. - VLT project 
#
# "@(#) $Id: WCS.man3,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $" 
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  ----------------------------------------
# Allan Brighton  30 Sep 96  Created
#

NAME
WCS - Reference counted C++ wrapper class for managing World Coordinates

SYNOPSIS
#include "WCS.h"

class WCSRep;

class SAOWCS : public WCSRep {...};

class WCS {
...
public:
    WCS();
    WCS(const WCS&);
    WCS(WCSRep* rep);
    ~WCS();
    WCS& operator=(const WCS&);
    
    int isWcs() const;
    
    int pixWidth() const;
    int pixHeight() const;

    double dist(double ra0, double dec0, double ra1, double dec1) const;

    char* pix2wcs(double x, double y, char* buf, int bufsz, int hms_flag = 1) const;
    int pix2wcs(double x, double y, double& ra, double& dec) const;

    int wcs2pix(double ra, double dec, double &x, double &y) const;

    int set(double ra, double dec, double secpix, double xrefpix, double yrefpix,
            int nxpix, int nypix, double rotate, int equinox, double epoch,
            const char* proj);

    int shift(double ra, double dec, double equinox);

    double equinox() const;
    char* equinoxStr() const;
    double epoch() const;
    double rotate() const;
    double width() const;
    double height() const;
    double radius() const;
    double secPix() const;
    WorldCoords center() const;
    int initialized() const;
    int status() const;
};


DESCRIPTION
Class WCS is a reference counted wrapper class for managing world
coordinates for a given image. This class does not do anything itself,
but manages a pointer to a class derived from class WCSRep, which is
an abstract base class. Packages can add their own WCS implementations
by deriving new subclasses from WCSRep that meet the required
interface, which includes the same methods as class WCS. 

Since class WCS uses reference counting, you do not normally have to
worry about allocating and deleting it. You can jsut create an
instance and copy it. When the last copy goes out of scope or is
deleted, the memory is released.

The astrotcl package provides one implementation subclass of WCSRep,
class SAOWCS, which is based on Doug Mink's (saoimage) WCS C library
(Note: a Starlink based version is also available, see the GAIA plugin
for Skycat). The constructor for SAOWCS takes a pointer to a FITS
image header and uses that to set up world coordinates for the
image. Methods are implemented to convert between image pixel and
world coordinates and to set world coordinates when there is no FITS
header.

See the HTML documentation in

    http://tdc-www.harvard.edu/software/wcstools.html 

for information about the underlying C library used by SAOWCS. The
latest version of the wcs C library can be found under:

    ftp://cfa-ftp.harvard.edu/pub/gsc/WCS/.

METHODS

WCS()
WCS(WCSRep* rep)
	The default constructor creates a null WCS object.  If you
	pass the constructor a pointer to an object of a class derived
	from WCSRep (SAOWCS, for example), the object is initialized
	from it.

isWcs()
	Returns nozero if the image supports world coordinates (has
	the necessary FITS keywords in the image header or from some
	other source). Note that if this method returns 0, none of the
	other methods should be called.

pix2wcs(int x, int y, char* buf)
	Return the world coordinates string for the given image coords.

pix2wcs(int x, int y, double& ra, double& dec)
	Return the world coords (in degrees, as 2 doubles) for the
	image coords.

wcs2pix(double ra, double dec, int &x, int &y)
   	 Get the image coordinates for the given world coords.

dist(double ra0, double dec0, double ra1, double dec1)
    	Return the WCS distance between the 2 given WCS points in
    	arcmin.

width()
height()
radius()
   	Return the width, height, radius of the image in arc-minutes.

set(double ra, double dec, double secpix, double xrefpix, double yrefpix,
    int nxpix, int nypix, double rotate, int equinox, double epoch,
    const char* proj);

	Set up the WCS structure from the given information about the
	image. This method can be used to add world coordinate support
	to an image even if the image doesn't have it in the header.

    Arguments:
	ra      = Center right ascension in degrees 
	dec     = Center declination in degrees 
	secpix  = Number of arcseconds per pixel 
	xrefpix = Reference pixel X coordinate
	yrefpix	= Reference pixel Y coordinate
	nxpix   = Number of pixels along x-axis 
	nypix   = Number of pixels along y-axis 
	rotate  = Rotation angle (clockwise positive) in degrees 
	equinox = Equinox of coordinates, 1950 and 2000 supported 
	epoch   = Epoch of coordinates, used for FK4/FK5 conversion no effect if 0 
	proj    = Projection 

shift(double ra, double dec, double equinox)
    Reset the center of the WCS structure.

equinox()
equinoxStr()
	Return the WCS equinox as a double (1) or a string (2).

epoch()
	Return the WCS epoch as a double.
   
rotate()
	Return the rotation angle in degrees.
  
secPix()
	Return the number of world coordinate arcseconds per pixel.

center()
	Return the world coordinates of the center of the image.
    
pixWidth() const
pixHeight()
	Return image dimensions in pixels.

initialized()
	Returns true if WCS has been initialized (with a FITS header).

status()
status(int s)
	Get/set the status of the object (0 is OK).

SEE ALSO
ImageData, RtdImage(3C++), WorldCoords(3C++), FitsIO(3C++), 
ImageIO 
----------------------------------------------------------------------

