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

 


- - - - - -
Last change: 08 Sep 98