WCSUTIL

The wcsutil module provides a stand-alone implementation of a WCS object which provides a number of basic transformations and query methods. Most (if not all) of these functions can be obtained from the use of the PyWCS or STWCS WCS object if those packages have been installed.

class stsci.tools.wcsutil.WCSObject(rootname, header=None, shape=None, pa_key='PA_V3', new=False, prefix=None)

This class should contain the WCS information from the input exposure’s header and provide conversion functionality from pixels to RA/Dec and back.

The basic syntax for using this object is:

>>> wcs = wcsutil.WCSObject(
...     rootname, header=None, shape=None,
...     pa_key='PA_V3', new=no, prefix=None)  

This will create a WCSObject which provides basic WCS functions.

Parameters:

rootname: string

filename in a format supported by IRAF, specifically:

filename.hhh[group] -or-
filename.fits[ext] -or-
filename.fits[extname,extver]

header: object

PyFITS header object from which WCS keywords can be read

shape: tuple

tuple giving (nx,ny,pscale)

pa_key: string

name of keyword to read in telescopy orientation

new: boolean

specify a new object rather than creating one by reading in keywords from an existing image

prefix: string

string to use as prefix for creating archived versions of WCS keywords, if such keywords do not already exist

Notes

Setting ‘new=yes’ will create a WCSObject from scratch regardless of any input rootname. This avoids unexpected filename collisions.

Methods

print_archive(format=True)	print out archive keyword values
get_archivekw(keyword)	return archived value for WCS keyword
set_pscale()	set pscale attribute for object
compute_pscale(cd11,cd21)	compute pscale value
get_orient()	return orient computed from CD matrix
updateWCS(pixel_scale=None,orient=None,refpos=None,refval=None,size=None)	reset entire WCS based on given values
xy2rd(pos)	compute RA/Dec position for given (x,y) tuple
rd2xy(skypos,hour=no)	compute X,Y position for given (RA,Dec)
rotateCD(orient)	rotate CD matrix to new orientation given by ‘orient’
recenter()	Reset reference position to X,Y center of frame
write(fitsname=None,archive=True,overwrite=False,quiet=True)	write out values of WCS to specified file
restore()	reset WCS keyword values to those from archived values
read_archive(header,prepend=None)	read any archive WCS keywords from PyFITS header
archive(prepend=None,overwrite=no,quiet=yes)	create archived copies of WCS keywords.
write_archive(fitsname=None,overwrite=no,quiet=yes)	write out the archived WCS values to the file
restoreWCS(prepend=None)	resets WCS values in file to original values
createReferenceWCS(refname,overwrite=yes)	write out values of WCS keywords to NEW FITS file without any image data
copy(deep=True)	create a copy of the WCSObject.
help()	prints out this help message

archive(prepend=None, overwrite=False, quiet=True)

Create backup copies of the WCS keywords with the given prepended string. If backup keywords are already present, only update them if ‘overwrite’ is set to ‘yes’, otherwise, do warn the user and do nothing. Set the WCSDATE at this time as well.

compute_pscale(cd11, cd21)

Compute the pixel scale based on active WCS values.

copy(deep=True)

Makes a (deep)copy of this object for use by other objects.

createReferenceWCS(refname, overwrite=True)

Write out the values of the WCS keywords to the NEW specified image ‘fitsname’.

createWcsHDU()

Generate a WCS header object that can be used to populate a reference WCS HDU.

get_archivekw(keyword)

Return an archived/backup value for the keyword.

get_orient()

Return the computed orientation based on CD matrix.

help()

Prints out help message.

print_archive(format=True)

Prints out archived WCS keywords.

rd2xy(skypos, hour=False)

This method would use the WCS keywords to compute the XY position from a given RA/Dec tuple (in deg).

NOTE: Investigate how to let this function accept arrays as well as single positions. WJH 27Mar03

read_archive(header, prepend=None)

Extract a copy of WCS keywords from an open file header, if they have already been created and remember the prefix used for those keywords. Otherwise, setup the current WCS keywords as the archive values.

recenter()

Reset the reference position values to correspond to the center of the reference frame. Algorithm used here developed by Colin Cox - 27-Jan-2004.

restore()

Reset the active WCS keywords to values stored in the backup keywords.

restoreWCS(prepend=None)

Resets the WCS values to the original values stored in the backup keywords recorded in self.backup.

rotateCD(orient)

Rotates WCS CD matrix to new orientation given by ‘orient’

scale_WCS(pixel_scale, retain=True)

Scale the WCS to a new pixel_scale. The ‘retain’ parameter [default value: True] controls whether or not to retain the original distortion solution in the CD matrix.

set_orient()

Return the computed orientation based on CD matrix.

set_pscale()

Compute the pixel scale based on active WCS values.

update()

Update computed values of WCS based on current CD matrix.

updateWCS(pixel_scale=None, orient=None, refpos=None, refval=None, size=None)

Create a new CD Matrix from the absolute pixel scale and reference image orientation.

write(fitsname=None, wcs=None, archive=True, overwrite=False, quiet=True)

Write out the values of the WCS keywords to the specified image.

If it is a GEIS image and ‘fitsname’ has been provided, it will automatically make a multi-extension FITS copy of the GEIS and update that file. Otherwise, it throw an Exception if the user attempts to directly update a GEIS image header.

If archive=True, also write out archived WCS keyword values to file. If overwrite=True, replace archived WCS values in file with new values.

If a WCSObject is passed through the ‘wcs’ keyword, then the WCS keywords of this object are copied to the header of the image to be updated. A use case fo rthis is updating the WCS of a WFPC2 data quality (_c1h.fits) file in order to be in sync with the science (_c0h.fits) file.

write_archive(fitsname=None, overwrite=False, quiet=True)

Saves a copy of the WCS keywords from the image header as new keywords with the user-supplied ‘prepend’ character(s) prepended to the old keyword names.

If the file is a GEIS image and ‘fitsname’ is not None, create a FITS copy and update that version; otherwise, raise an Exception and do not update anything.

xy2rd(pos)

This method would apply the WCS keywords to a position to generate a new sky position.

The algorithm comes directly from ‘imgtools.xy2rd’

translate (x,y) to (ra, dec)

stsci.tools.wcsutil.ddtohms(xsky, ysky, verbose=False)

Convert sky position(s) from decimal degrees to HMS format.

stsci.tools.wcsutil.help()

stsci.tools.wcsutil.troll(roll, dec, v2, v3)

Computes the roll angle at the target position based on:

the roll angle at the V1 axis(roll),
the dec of the target(dec), and
the V2/V3 position of the aperture (v2,v3) in arcseconds.

Based on the algorithm provided by Colin Cox that is used in Generic Conversion at STScI.