NAME

Astro::Coords - Class for handling astronomical coordinates

SYNOPSIS

use Astro::Coords;

$c = new Astro::Coords( ra   => '05:22:56',
                        dec  => '-26:20:40.4',
                        type => 'B1950'
                        units=> 'sexagesimal');

$c = new Astro::Coords( long => '05:22:56',
                        lat  => '-26:20:40.4',
                        type => 'galactic');

$c = new Astro::Coords( planet => 'mars' );

$c = new Astro::Coords( elements => \%elements );

# Return FK5 J2000 coordinates in radians
($ra, $dec) = $c->fk5();

# in degrees or as sexagesimal string or arrays
($ra, $dec) = $c->fk5( "DEG" );
($ra, $dec) = $c->fk5( "STRING" );
($raref, $decref) = $c->fk5( "ARRAY" );

# in galactic coordinates
($long, $lat) = $c->gal;

# Specify a telescope
$c->telescope( 'JCMT' );

# Determine apparent RA/Dec for the current time and telescope
($appra, $appdec) = $c->apparent;

# and az el
($az, $el) = $c->azel;

# and ha, dec
($ha, $dec) = $c->hadec;

# obtain summary string of object
$summary = "$c";

# Obtain full summary as an array
@summary = $c->array;

# Calculate distance to another coordinate (in radians)
$distance = $c->distance( $c2 ); # not yet supported

DESCRIPTION

Class for manipulating and transforming astronomical coordinates. All fixed sky coordinates are converted to FK5 J2000 internally.

For time dependent calculations a telescope location and reference time must be provided.

METHODS

Constructor

new

This can be treated as an object factory. The object returned by this constructor depends on the arguments supplied to it. Coordinates can be provided as orbital elements, a planet name or an equatorial (or related) fixed coordinate specification (e.g. right ascension and declination).

A complete (for some definition of complete) specification for the coordinates in question must be provided to the constructor. The coordinates given as arguments will be converted to an internal format.

A planet name can be specified with:

$c = new Astro::Coords( planet => "sun" );

Orbital elements as:

$c = new Astro::Coords( elements => \%elements );

where %elements must contain the names of the elements as used in the SLALIB routine slaPlante.

Fixed coordinate frames can be specified using:

  $c = new Astro::Coords( ra => 
                          dec =>
			  long =>
			  lat =>
			  type =>
			  units =>
			);

ra and dec are used for HMSDeg systems (eg type=J2000). Long and Lat are used for degdeg systems (eg where type=galactic). type can be "galactic", "j2000", "b1950", and "supergalactic". The units can be specified as "sexagesimal" (when using colon or space-separated strings), "degrees" or "radians". The default is determined from context.

Returns undef if an object could not be created.

Accessor Methods

telescope

Telescope object (an instance of Astro::Telescope) to use for obtaining the position of the telescope to use for the determination of source elevation.

$c->telescope( new Astro::Telescope( 'JCMT' ));
$tel = $c->telescope;

This method checks that the argument is of the correct type.

datetime

Date/Time object to use when determining the source elevation.

$c->datetime( new Time::Piece() );

Argument must be of type Time::Piece (or Time::Object version 1.00). The method dies if this is not the case [it must support an mjd method].

If no argument is specified an object referring to the current time (GMT/UT) is returned.

General Methods

ra_app

Apparent RA for the current time. Arguments are similar to those specified for "dec".

$ra_app = $c->ra_app( format => "s" );

dec_app

Apparent Dec for the currently stored time. Arguments are similar to those specified for "dec".

$dec_app = $c->dec_app( format => "s" );

ha

Get the hour angle for the currently stored LST. Default units are in radians.

$ha = $c->ha;
$ha = $c->ha( format => "deg" );

az

Azimuth of the source for the currently stored time at the current telescope. Arguments are similar to those specified for "dec".

$az = $c->az();

If no telescope is defined the equator is used.

el

Elevation of the source for the currently stored time at the current telescope. Arguments are similar to those specified for "dec".

$el = $c->el();

If no telescope is defined the equator is used.

pa

Parallactic angle of the source for the currently stored time at the current telescope. Arguments are similar to those specified for "dec".

$pa = $c->pa();

If no telescope is defined the equator is used.

array

Return a summary of this object in the form of an array containing the following:

coordinate type (eg PLANET, RADEC, MARS)
ra2000          (J2000 RA in radians [for equatorial])
dec2000         (J2000 dec in radians [for equatorial])
elements        (up to 8 orbital elements)

_lst

Calculate the LST for the current date/time and telescope and return it (in radians).

If no date/time is specified the current time will be used. If no telescope is defined the LST will be from Greenwich.

This is labelled as an internal routine since it is not clear whether the method to determine LST should be here or simply placed into Time::Object. In practice this simply calls the Astro::SLA::ut2lst function with the correct args (and therefore does not need the MJD). It will need the longitude though so we calculate it here.

_azel

Return Azimuth and elevation for the currently stored time and telescope. If no telescope is present the equator is used.

Private Methods

_cvt_tohrs

Scale a value in radians such that it can be translated correctly to hours by routines that are assuming output is required in degrees (effectively dividing by 15).

$radhr = $c->_cvt_tohrs( \$format, $rad );

Format is modified to reflect the change expected by _cvt_fromrad().

_cvt_fromrad

Convert the supplied value (in radians) to the desired output format. Output options are:

sexagesimal - A string of format either dd:mm:ss
radians     - The default (no change)
degrees     - decimal degrees
array       - return a reference to an array containing the
              sign/degrees/minutes/seconds

If the output is required in hours, pre-divide the radians by 15.0 prior to calling this routine.

$out = $c->_cvt_fromrad( $rad, $format );

REQUIREMENTS

Astro::SLA is used for all internal astrometric calculations.

AUTHOR

Tim Jenness <t.jenness@jach.hawaii.edu>

COPYRIGHT

Copyright (C) 2001 Particle Physics and Astronomy Research Council. All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.