/ 
Astro-Coords-0.03
River stage one • 4 direct dependents • 5 total dependents
/ Astro::Coords

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 );

$c = new Astro::Coords( az => 345, el => 45 );

# 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;

# See if the target is observable for the current time
# and telescope
$obs = 1 if $c->isObservable;

# 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 astronomical oordinate 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.

Fixed (as in fixed on Earth) coordinate frames can be specified using:

$c = new Astro::Coords( dec =>
                        ha =>
                        tel =>
                        az =>
                        el =>
                        units =>
                      );

where az and el are the Azimuth and Elevation. Hour Angle and Declination require a telescope. Units are as defined above.

Finally, if no arguments are given the object is assumed to be of type Astro::Coords::Calibration.

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 => "h" );

If you wish to normalize the Hour Angle to +/- 12h use the normalize key.

$ha = $c->ha( normalize => 1 );
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.

airmass

Airmass of the source for the currently stored time at the current telescope.

$am = $c->airmass();

Value determined from the current elevation.

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.

isObservable

Determine whether the coordinates are accessible for the current time and telescope.

$isobs = $c->isObservable;

Returns false if a telescope has not been specified (see the telescope method) or if the specified telescope does not know its own limits.

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)
status

Return a status string describing the current coordinates. This consists of the current elevation, azimuth, hour angle and declination. If a telescope is defined the observability of the target is included.

$status = $c->status;
_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 );
_cvt_torad

Convert from the supplied units to radians. The following units are supported:

sexagesimal - A string of format either dd:mm:ss or "dd mm ss"
degrees     - decimal degrees
radians     - radians
hours       - decimal hours

If units are not supplied (undef) default is to assume "sexagesimal" if the supplied string contains spaces or colons, "degrees" if the supplied number is greater than 2*PI (6.28), and "radians" for all other values.

$radians = Astro::Coords::Equatorial->_cvt_torad("sexagesimal",
                                                 "5:22:63")

An optional final argument can be used to indicate that the supplied string is in hours rather than degrees. This is only used when units is set to "sexagesimal".

Returns undef on error.

REQUIREMENTS

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

AUTHOR

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

COPYRIGHT

Copyright (C) 2001-2002 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.