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::Channel" using 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 interface

AUTHOR

Tim Jenness <tjenness@cpan.org>

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