NAME
Starlink::AST - Interface to the Starlink AST library
SYNOPSIS
use Starlink::AST;
my $zmap = new Starlink::AST::ZoomMap( 2, 5, "" );
$zmap->Set( Zoom => 5 );
my ($xout, $yout ) = $zmap->Tran2( [1,2], [4,6], 1);
my $fchan = new Starlink::AST::FitsChan();
for (<DATA>) {
$fchan->PutFits( $_, 0);
}
$fchan->Clear( "Card" );
$wcs = $fchan->Read();
tie %hash, "Starlink::AST::KeyMap";
$hash{KEYWORD} = $value;
$km = Starlink::AST::KeyMap->new( "" );
tie %hash, $km;DESCRIPTION
Starlink::AST provides a perl wrapper to the Starlink AST library. The Starlink AST library provides facilities for transforming coordinates from one system to another in an object oriented manner. Multiple coordinate frames can be associated with a data set and it is also possible to generate automatic mappings between frames.
Coordinate frame objects can be imported from FITS headers and from NDF files.
CALLING CONVENTIONS
In general the method names used in the Perl interface match the function names in the C library with the "ast" prefix dropped. Functions that require C arrays, should take references to Perl arrays. AST functions that return values/arrays now return these values/arrays onto the perl stack rather than the argument stack.
The constructor functions are now replaced with new methods in the relevant class. e.g rather than calling astZoomMap(), the Perl interface uses the new method in the Starlink::AST::ZoomMap namespace.
Constructors
The following constructors are available. Currently, these constructors match the C constructors fairly closely.
This is one area which may change when the class comes out of alpha release. The main problem with the constructors is the options string (a standard AST option string with comma-separated keyword value pairs). It would make more sense to replace these constructors with hash constructors that take the mandatory arguments in the correct order and hash arguments for the options.
- Starlink::AST::Frame
-
Instantiate an astFrame() object.
$frame = new Starlink::AST::Frame( $naxes, $options ); - Starlink::AST::FrameSet
-
$frameSet = new Starlink::AST::FrameSet( $frame, $options ); - Starlink::AST::CmpFrame
-
$cmpFrame = new Starlink::AST::CmpFrame( $frame1, $frame2, $options ); - Starlink::AST::CmpMap
-
$cmpMap = new Starlink::AST::CmpMap( $map1, $map2, $series, $options ); - Starlink::AST::Channel
-
The astChannel contructor takes a hash argument. There are no mandatory keys to the hash. Sink and Source callbacks for the channel can be supplied using the keys "sink" and "source". All other keys are expected to correspond to attributes of the channel object (e.g. Comment, Full and Skip for astChannel).
$chann = new Starlink::AST::Channel( %options ); $chann = new Starlink::AST::Channel( sink => sub { print "$_[0]\n"; } );The "sink" callback expects to be given a single argument as a string. The "source" callback takes no arguments and should return a single string.
- Starlink::AST::FitsChan
-
Same calling signature as
Starlink::AST::Channel. - Starlink::AST::XmlChan
-
Same calling signature as
Starlink::AST::Channel. Note that xmlChan is only available for AST v3.1 and newer. - Starlink::AST::StcsChan
-
A
Starlink::AST::Channelusing IVOA STC-S descriptions. - Starlink::AST::GrisMap
-
Only available in AST v3.0 and newer.
$grismMap = new Starlink::AST::GrisMap( $options ); - Starlink::AST::IntraMap
-
Not Yet Implemented.
$intraMap = new Starlink::AST::IntraMap( $name, $nin, $nout, $options );
Base class methods
These methods will work on all classes of AST objects.
Mapping methods
TODO
FrameSet methods
TODO
EXCEPTIONS
Rather than using the astOK function provided to the C interface (which is not thread safe) AST errors are converted to Perl exceptions (currently croaks) which can be caught with an eval.
TODO
+ Convert AST croaks to true exceptions of class Starlink::AST::Error
+ Tidy up the interfaces to the constructors
+ Properly document the Perl interface
+ Finalise the interfaceSEE ALSO
The AST library can be downloaded from http://www.starlink.ac.uk/ast
AUTHOR
Tim Jenness <tjenness@cpan.org>
Copyright (C) 2004-2011 Tim Jenness. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA