wcs.c

 WCSTools subroutines to convert FITS WCS to pixels and vice versa:

Subroutines

  • wcsxinit (cra,cdec,secpix,nxpix,nypix,rotate,equinox,epoch) sets a WCS structure from arguments
  • wcskinit (nxpix,nypix,ctype1,ctype2,crpix1,crpix2,crval1,crval2, cd,cdelt1,cdelt2,crota,equinox,epoch) sets a WCS structure from keyword-based arguments
  • iswcs(wcs) returns 1 if WCS structure is filled, else 0
  • nowcs(wcs) returns 0 if WCS structure is filled, else 1
  • wcscent (wcs) prints the image center and size in WCS units
  • wcssize (wcs, cra, cdec, dra, ddec) returns image center and size
  • wcsfull (wcs, cra, cdec, width, height) returns image center and size
  • wcsshift (wcs,cra,cdec) resets the center of a WCS structure
  • wcsdist (x1,y1,x2,y2) compute angular distance between ra/dec or lat/long
  • wcscominit (wcs,i,command) sets up a command format for execution by wcscom
  • wcsoutinit (wcs,coor) sets up the output coordinate system
  • getwcsout (wcs) returns current output coordinate system used by pix2wcs( )
  • wcsininit (wcs,coor) sets up the coordinate system used by wcs2pix( )
  • getwcsin (wcs) returns current input coordinate system used by wcs2pix( )
  • setdegout (wcs, new) sets WCS output in degrees or hh:mm:ss
  • getradecsys (wcs) returns current coordinate system type
  • setlinmode (wcs, mode) sets output string mode for LINEAR coordinates
  • wcscom (wcs,file,x,y) executes a command using the current world coordinates
  • pix2wcs (wcs,xpix,ypix,xpos,ypos) pixel coordinates -> sky coordinates
  • pix2wcst (wcs,xpix,ypix,wcstring,lstr) pixels -> sky coordinate string
  • wcs2pix (wcs,xpos,ypos,xpix,ypix,offscl) sky coordinates -> pixel coordinates
  • wcspos (xpix,ypix,wcs,xpos,ypos) pixel to sky coordinate using WCSLIB
  • wcspix (xpos,ypos,wcs,xpix,ypix) sky to pixel coordinates using WCSLIB
  • setdefwcs (oldwcs) sets flag to use AIPS projections instead of WCSLIB projections

    wcsninit (char *hstring, int lhstring)

    Set up a WCS structure from a FITS image header lhstring bytes long.
    Returns a pointer to struct WorldCoor
    hstring
    Character string containing FITS header information in the format keyword= value [/comment]
    lhstring
    Length of FITS header in bytes

    wcsinit (char *hstring)

    Set up a WCS structure from a FITS image header
    Returns a pointer to struct WorldCoor
    hstring
    Character string containing FITS header information in the format keyword= value [/comment]
    Assumed to be null-terminated
    Use Digitized Sky Survey header information, FITS WCS keywords for 8 (AIPS) or 26 (proposed FITS) projections, or an approximate plane-tangent projection. The approximation uses the RA and DEC keywords as the coordinates of the central pixel of the image and SECPIX (or SECPIX1 and SECPIX2) keywords as the plate scale at the center in arcseconds per pixel.

    Set the equinox and radecsys variables in the wcs data structure based on image header keyword values. If RADECSYS is not present, the coordinate system is set from EQUINOX (1950 implies FK4, 2000 implies FK5) or EPOCH, if EQUINOX is not present.

    wcsxinit (double cra, double cdec, double secpix, int nxpix, int nypix, double rotate, int equinox, double epoch)

    Set up a WCS structure from basic information about an image
    Returns a pointer to struct WorldCoor
    cra
    Center right ascension in degrees
    cdec
    Center declination in degrees
    secpix
    Number of arcseconds per pixel
    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

    wcskinit (int nxpix, int nypix, char *ctype1, char *ctype2, double crpix1, double crpix2, double crval1, double crval2, double *cd, double cdelt1, double cdelt2, double crota, double equinox, double epoch)

    Set up a WCS structure from keyword-based arguments
    Returns a pointer to struct WorldCoor
    naxis1
    Number of pixels along x-axis
    naxis2
    Number of pixels along y-axis
    ctype1
    FITS WCS projection for axis 1
    ctype2
    FITS WCS projection for axis 2
    crpix1, crpix2
    Reference pixel coordinates
    crval1, crval2
    Coordinates at reference pixel in degrees
    cd
    Rotation matrix, used if not NULL
    cdelt1, cdelt2
    scale in degrees/pixel, ignored if cd is not NULL
    crota
    Rotation angle in degrees, ignored if cd is not NULL
    equinox
    Equinox of coordinates, 1950 and 2000 supported
    epoch
    Epoch of coordinates, used for FK4/FK5 conversion (no effect if 0)

    wcsreset (struct WorldCoor *wcs, double crpix1, double crpix2, double crval1, double crval2, double cdelt1, double cdelt2, double crota, double *cd, double equinox)

    Reset an existing WCS structure from arguments
    crpix1, crpix2
    Reference pixel coordinates
    crval1, crval2
    Coordinates at reference pixel in degrees
    cdelt1, cdelt2
    scale in degrees/pixel, ignored if cd is not NULL
    crota
    Rotation angle in degrees, ignored if cd is not NULL
    cd
    Rotation matrix, used if not NULL
    equinox
    Equinox of coordinates, 1950 and 2000 supported

    iswcs (struct WorldCoor *wcs)

    Return int 1 if WCS structure is filled, else int 0
    wcs
    World coordinate system structure

    nowcs (struct WorldCoor *wcs)

    Return int 0 if WCS structure is filled, else int 1
    wcs
    World coordinate system structure

    wcsshift (struct WorldCoor *wcs, double cra, double cdec, char *coorsys)

    Reset the center of a WCS structure
    wcs
    World coordinate system structure
    cra
    New center right ascension in degrees
    cdec
    New center declination in degrees
    coorsys
    FK4 or FK5 coordinates (1950 or 2000)

    wcscent (struct WorldCoor *wcs)

    Print position of WCS center to stderr, if WCS is set
    wcs
    World coordinate system structure

    wcssize (struct WorldCoor *wcs, double *cra, double *cdec, double *dra, double *ddec)

    Return RA and Dec of image centerin degrees, plus half-width and half-height in RA and Dec degrees
    wcs
    World coordinate system structure
    cra
    Right ascension of image center (deg) (returned)
    cdec
    Declination of image center (deg) (returned)
    dra
    Half-width in right ascension (deg) (returned)
    ddec
    Half-width in declination (deg) (returned)

    wcsfull (struct WorldCoor *wcs, double *cra, double *cdec, double *width, double *height)


    Return RA and Dec of image center in degrees, plus width and height in sky degrees
    wcs
    World coordinate system structure
    cra
    Right ascension of image center (deg) (returned)
    cdec
    Declination of image center (deg) (returned)
    width
    Width in degrees (returned)
    height
    Height in degrees (returned)

    wcsdist (double x1, double y1, double x2, double y2)

    Return distance in degrees between two sky coordinates as double
    x1
    Right ascension or longitude of first point in degrees
    y1
    Declination or latitude of first point in degrees
    x2
    Right ascension or longitude of second point in degrees
    y2
    Declination or latitude of second point in degrees

    wcscominit (struct WorldCoor *wcs, int i, char *command)

    Initialize Unix command invoked to use world coordinates and/or file name
    wcs
    World coordinate system structure
    i
    Number of command (0-9) to initialize
    command
    command with %s where coordinates will go and/or %f where file name will go and/or %x where image x and y coordinates will go

    wcscom (struct WorldCoor *wcs, char *filename, double xfile, double yfile)

    Execute Unix command with world coordinates (from x,y) and/or filename
    %s in command is replaced by world coordinates in current system
    %f in command is replaced by the name of the current file
    wcs
    World coordinate system structure
    filename
    Image file name
    xfile, yfile
    Image pixel coordinates for WCS command

    wcsoutinit (struct WorldCoor *wcs, char *coorsys)

    Initialize WCS output coordinate system used by pix2wcs( )
    wcs
    World coordinate system structure
    coorsys
    Output coordinate system:
    FK4 or B1950 or fk4 or b1950
    FK5 or J2000 or fk5 or j2000
    GALACTIC or galactic

    getwcsout (struct WorldCoor *wcs)

    Return current output coordinate system used by pix2wcs( )
    WCS_J2000 0
    WCS_B1950 1
    WCS_GALACTIC 2
    WCS_ECLIPTIC 3
    WCS_ALTAZ 4
    WCS_LINEAR 5
    wcs
    World coordinate system structure

    wcsininit (struct WorldCoor *wcs, char *coorsys)

    Set the coordinate system used by wcs2pix( )
    wcs
    World coordinate system structure
    coorsys
    Input coordinate system:
    FK4 or B1950 or fk4 or b1950
    FK5 or J2000 or fk5 or j2000
    GALACTIC or galactic

    getwcsin (struct WorldCoor *wcs)

    Return current input coordinate system used by wcs2pix( )
    WCS_J2000 0
    WCS_B1950 1
    WCS_GALACTIC 2
    WCS_ECLIPTIC 3
    WCS_ALTAZ 4
    WCS_LINEAR 5
    wcs
    World coordinate system structure

    getradecsys (struct WorldCoor *wcs)

    Return current coordinate system of image
    WCS_J2000 0
    WCS_B1950 1
    WCS_GALACTIC 2
    WCS_ECLIPTIC 3
    WCS_ALTAZ 4
    WCS_LINEAR 5
    wcs
    World coordinate system structure

    setdegout (struct WorldCoor *wcs, int new)

    Set WCS output from pix2wcst( ) to be in degrees or hh:mm:ss / dd:mm:ss
    wcs
    World coordinate system structure
    new
    0 for output in sexagesimal, else output in degrees

    wcsndec (struct WorldCoor *wcs, int mode)

    Set number of decimal places in pix2wcst output string, and return current value.
    wcs
    World coordinate system structure
    ndec
    Number of decimal places in output string. If < 0, return current unchanged value.

    setwcslin (struct WorldCoor *wcs, int mode)

    Set output string mode for LINEAR coordinates in pix2wcst( )
    wcs
    World coordinate system structure
    mode
    0: x y linear
    1: x units x units
    2: x y linear units */

    pix2wcst (struct WorldCoor *wcs, double xpix, double ypix, char *wcstring, int lstr)

    Convert pixel coordinates to World Coordinate string
    Returns int 1 if string is set successfully, else int 0
    wcs
    World coordinate system structure
    xpix, ypix
    Image coordinates in pixels
    wcstring
    World coordinate string (returned)
    lstr
    Maximum length of world coordinate string

    pix2wcs (struct WorldCoor *wcs, double xpix, double ypix, double *xpos, double *ypos)

    Convert pixel coordinates to World Coordinates
    wcs
    World coordinate system structure
    xpix,ypix
    x and y image coordinates in pixels
    xpos,ypos
    RA and Dec in degrees (returned)

    wcs2pix (struct WorldCoor *wcs, double xpos, double ypos, double *xpix, double *ypix, int *offscl)

    wcsc2pix (struct WorldCoor *wcs, double xpos, double ypos, double *xpix, double *ypix, int *offscl)wcs2pix (struct WorldCoor *wcs, double xpos, double ypos, double *xpix, double *ypix, int *offscl)wcserr () Print most recent error message generated by wcs.c subroutines

    wcspos (double xpix, double ypix, struct WorldCoor wcs, double *xpos, double *ypos)

    Convert image to sky coordinates using WCSLIB projections, returning 0 if not out of range of projection
    xpix, ypix
    Image position in pixels
    wcs
    World coordinate system structure
    xpos, ypos
    Sky position in degrees (returned)

    wcspix (double *xpos, double *ypos, struct WorldCoor wcs, double *xpix, double *ypix)

    Convert sky to image coordinates using WCSLIB projections, returning 0 if not out of range of projection
    xpos, ypos
    Sky position in degrees
    wcs
    World coordinate system structure
    xpix, ypix
    Image position in pixels (returned)

    wcszin (int izpix) Set third dimension for cube projections
    izpix
    Current coordinate in third dimension (if <= 0, return current value without changing it

    wcszout (struct WorldCoor wcs) return third dimension for cube projections
    wcs
    World coordinate system structure

    setwcserr (char *errmsg) Set error message for later retrieval
    errmsg
    String containing the error message.

    wcserr () Print most recent error message to standard error

    setdefwcs (int oldwcs)

    Set flag to select WCS projection subroutines to use
    oldwcs
    If 1, use Bill Cotton's AIPS projection code instead of Mark Calabretta's WCSLIB code, getting 8 possible projections instead of 26.

    Last updated 15 September 1998 by Doug Mink dmink@cfa.harvard.edu

    Telescope Data Center [WCSTools] [WCSTools Subroutines] [WCS Subroutines]