High level functions

The starlink.Atl module within PyAST provides a small number of high level functions and classes that wrap up various other PyAST calls to perform commonly required operations.

Utility functions

readfitswcs: Reads an AST FrameSet from a FITS header.
writefitswcs: Write an AST FrameSet to a FITS file.
plotframeset: Plot an annotated coordinate grid in a matplotlib axes area.
plotfitswcs: Read WCS from a PyFITS HDU and plot an annotated coordinate grid in a matplotlib axes area.

Utility classes

PyFITSAdapter: Allows PyAST FitsChan objects to read and write headers to and from a PyFITS HDU.

Utility functions

readfitswcs:

Reads an AST FrameSet from a FITS header.

The header from the specified PyFITS HDU is read, and an AST FrameSet describing the WCS information in the header is returned. None is returned instead of a FrameSet if WCS information cannot be read from the header. A string identifying the scheme used to describe WCS information in the header (the encoding) is also returned.

Synopsis:

(frameset,encoding) = starlink.Atl.readfitswcs( hdu )

hdu: An element of the hdulist associated with a FITS file opened using pyfits.open(). If the entire hdulist is supplied, rather than an element of the hdulist, then the primary HDU (element zero) will be used.
frameset: A reference to the FrameSet describing the pixel and world coordinate systems read from the FITS header, or None if no WCS could be read.
encoding: Indicates how the WCS information was encoded in the header. For possible values, see the documentation for the " Encoding" attribute in SUN/211.

Example:

>>> import pyfits
>>> import starlink.Atl as Atl
>>>
>>> hdulist = pyfits.open( 'test.fit' )
>>> frameset = Atl.readfitswcs( hdulist )
>>> if frameset == None:
>>>    print( "Cannot read WCS from test.fit" )

plotfitswcs:

Read WCS from a PyFITS HDU and plot an annotated coordinate grid in a matplotlib axes area. The grid covers the entire image. The function returns a reference to the Plot that was used to draw the axes.

Synopsis:

plot = starlink.Atl.plotfitswcs( axes, gbox, hdu, options="" )

axes: A matplot lib "Axes" object. The annotated axes normally produced by matplotlib will be removed, and axes will instead be drawn by the AST Plot class
gbox: A list of four values giving the bounds of the new annotated axes within the matplotlib Axes object. The supplied values should be in the order (xleft,ybottom,xright,ytop) and should be given in the matplotlib "axes" coordinate system.
hdu: An element of the hdulist associated with a FITS file opened using pyfits.open(). If the entire hdulist is supplied, rather than an element of the hdulist, then the primary HDU (element zero) will be used.
options: An optional string holding a comma-separated list of Plot attribute settings. These control the appearance of the annotated axes.
plot: A reference to the Ast.Plot that was used to draw the axes.

Example:

>>> import pyfits
>>> import starlink.Atl as Atl
>>> import matplotlib.pyplot
>>>
>>> hdulist = pyfits.open( 'test.fit' )
>>> Atl.plotfitswcs( matplotlib.pyplot.figure().add_subplot(111),
>>>                  [ 0.1, 0.1, 0.9, 0.9 ], hdulist )
>>> matplotlib.pyplot.show()

plotframeset:

Plot an annotated coordinate grid in a matplotlib axes area.The function returns a reference to the Plot that was used to draw the axes.

Synopsis:

plot =  starlink.Atl.plotframeset( axes, gbox, bbox, frameset, options="" )

axes: A matplotlib "Axes" object. The annotated axes normally produced by matplotlib will be removed, and axes will instead be drawn by the AST Plot class
gbox: A list of four values giving the bounds of the new annotated axes within the matplotlib Axes object. The supplied values should be in the order (xleft,ybottom,xright,ytop) and should be given in the matplotlib "axes" coordinate system.
bbox: A list of four values giving the bounds of the new annotated axes within the coordinate system represented by the base Frame of the supplied FrameSet. The supplied values should be in the order (xleft,ybottom,xright,ytop).
frameset: An AST FrameSet such as returned by the starlink.Atl.readfits function. Its base Frame should be 2-dimensional.
options: An optional string holding a comma-separated list of Plot attribute settings. These control the appearance of the annotated axes.
plot: A reference to the Ast.Plot that was used to draw the axes.

Example:

>>> import pyfits
>>> import starlink.Atl as Atl
>>> import matplotlib.pyplot
>>>
>>> hdulist = pyfits.open( 'test.fit' )
>>> frameset = starlink.Atl.readfitswcs( hdulist )
>>> if frameset != None:
>>>    naxis1 = hdulist[0].header['NAXIS1']
>>>    naxis2 = hdulist[0].header['NAXIS2']
>>>    Atl.plotframeset( matplotlib.pyplot.figure().add_subplot(111),
>>>                      [ 0.1, 0.1, 0.9, 0.9 ],
>>>                      [ 0.5, 0.5, naxis1+0.5, naxis2+0.5 ], frameset )
>>>    matplotlib.pyplot.show()

writefitswcs:

Writes an AST FrameSet to a FITS header.

The WCS information described by the supplied FrameSet is converted into a set of FITS header cards which are stored in the supplied PyFITS HDU (all cards in the header are first removed).

Synopsis:

nobj = starlink.Atl.writefitswcs( frameset, hdu, encoding="FITS-WCS" )

frameset: A reference to the FrameSet to be written out to the FITS header.
hdu: An element of the PyFITS hdulist associated with a FITS file. The header cards generated from the FrameSet are stored in the header associated with this HDU. All cards are first removed from the header. If the entire hdulist is supplied, rather than an element of the hdulist, then the primary HDU (element zero) will be used.
encoding: Indicates how the WCS information is to be encoded in the header. For possible values, see the documentation for the " Encoding" attribute in SUN/211.
nobj: Returned equal to 1 if the FrameSet was converted successfully to FITS headers using the requested encoding, and zero otherwise.

Example:

>>> import starlink.Atl as Atl
>>>
>>> (frameset,encoding) = Atl.readfitswcs( hdu1 )
>>> if Atl.writefitswcs( frameset, hdu2, encoding="FITS-AIPS" ) == 0:
>>> if frameset == None:
>>>    print( "Cannot convert WCS to FITS-AIPS encoding" )

Utility classes

PyFITSAdapter:

This class allows a PyFITS HDU to be used as the source or sink object with a FitsChan.

When used as a FitsChan source, the PyFITSAdapter will allow the FitsChan to read each of the cards in the associated PyFITS header, thus allowing the cards to be copied into the FitsChan. This happens when the newly created, empty FitsChan is used for the first time (i.e. when any of its methods is invoked), and subsequently whenever the FitsChan.readfits() method is invoked.

When used as a FitsChan sink, the PyFITSAdapter will allow the FitsChan to copy its own header cards into the PyFITS header. This happens when the FitsChan is deleted or when the FitsChan.writefits() method is invoked. If the PyFITSAdapter.clear property is true, then the PyFITS header is first emptied of all existing headers, and the contents of the FitsChan are then stored in the PyFITS header. If the PyFITSAdapter.clear property is False, the original contents of the PyFITS header are retained. In this case each FitsChan card replaces any existing card that refers to the same keyword (if there is no card for the keyword already in the PyFITS header, the FitsChan card will be appended to the end of the header).

The class provides a public constructor, but no public methods.

Synopsis:

pyfitsadapter =  starlink.Atl.PyFITSAdapter( hdu, clear=True )

hdu: An element of the hdulist associated with a FITS file opened using "pyfits.open()". If the entire hdulist is supplied, rather than an element of the hdulist, then the primary HDU (element zero) will be used.
clear: This value is only used when using the PyFITSAdapter as a sink function with a FitsChan. If "clear" is True, the original contents of the PyFITS header are deleted immediately before the first FitsChan card is copied into the PyFITS header. If "clear" is False, the original contents of the PyFITS heasder are retained, with the FitsChan keywords over-writing any existing values for the same keywords.

Example:

>>> import pyfits
>>> import starlink.Atl as Atl
>>> import starlink.Ast as Ast
>>>
>>> hdulist = pyfits.open( 'test.fit' )
>>> adapter = Atl.PyFITSAdapter( hdulist[ 1 ] )
>>> fc = Ast.FitsChan( adapter, adapter )
>>> frameset = fc.read()
>>> fc.writefits()

This example fills a FitsChan with the headers from the first extension in 'test.fit'. It then reads WCS information from the FitsChan. Since FitsChan reads are destructive, this causes all the WCS-related keywords to be deleted from the FitsChan. The remaining non-WCS keywords are then written out to the original PyAST header (the PyAST header is empted first). The net effect is to remove all WCS keywords from the PyAST header.