/ 
Astro-Coords-0.05
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( name => "My target",
                        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 );

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

name

Name of the target associated with the coordinates.

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]. A value of undef is supported. This will clear the time and force the current time to be used on subsequent calls.

$c->datetime( undef );

If no argument is specified, or usenow is set to true, an object referring to the current time (GMT/UT) is returned. If a new argument is supplied usenow is always set to false.

has_datetime

Returns true if a specific time is stored in the object, returns false if no time is stored. (The value of usenow is ignored).

This is required because datetime always returns a time.

usenow

Flag to indicate whether the current time should be used for calculations regardless of whether an explicit time object is stored in datetime. This is useful when trying to determine the current position of a target without affecting previous settings.

$c->usenow( 1 );
$usenow = $c->usenow;

Defaults to false.

comment

A textual comment associated with the coordinate (optional). Defaults to the empty string.

$comment = $c->comment;
$c->comment("An inaccurate coordinate");

Always returns an empty string if undefined.

General Methods

ra_app

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

$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.

ra

Return the J2000 Right ascension for the target. Unless overridden by a subclass this converts the apparrent RA/Dec to J2000.

$ra2000 = $c->ra( format => "s" );
dec

Return the J2000 declination for the target. Unless overridden by a subclass this converts the apparrent RA/Dec to J2000.

$dec2000 = $c->dec( format => "s" );
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)
distance

Calculate the distance (on the tangent plane) between the current coordinate and a supplied coordinate.

$dist = $c->distance( $c2 );
@dist = $c->distance( $c2 );

The distance is returned in radians (but should be some form of angular object as should all of the RA and dec coordinates). In list context returns the individual "x" and "y" offsets (in radians). In scalar context returns the distance.

Returns undef if there was an error during the calculation (e.g. because the new coordinate was too far away).

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

Calculate target positions for a range of times.

  @data = $c->calculate( start => $start,
			 end => $end,
			 inc => $increment,
		         units => 'deg'
		       );

The start and end times are Time::Piece objects and the increment is a Time::Seconds object or an integer. If the end time will not necessarily be used explictly if the increment does not divide into the total time gap exactly. None of the returned times will exceed the end time. The increment must be greater than zero but the start and end times can be identical.

Returns an array of hashes. Each hash contains

time [Time::Piece object]
elevation
azimuth
parang
lst [always in radians]

The angles are in the units specified (radians, degrees or sexagesimal).

rise_time

Next time the target will appear above the horizon (starting from the time stored in datetime). Returns undef if the target is already up. An optional argument can be given (as a hash with key "horizon") specifying a different elevation to the horizon (in radians).

$t = $c->rise_time();
$t = $c->rise_time( horizon => $el );

Returns a Time::Piece object.

BUG: Does not distinguish a source that never rises from a source that never sets.

set_time

Time at which the target will set below the horizon. (starting from the time stored in datetime). Returns undef if the target is already down. An optional argument can be given specifying a different elevation to the horizon (in radians).

$t = $c->set_time();
$t = $c->set_time( horizon => $el );

Returns a Time::Piece object.

BUG: Does not distinguish a source that never rises from a source that never sets.

ha_set

Hour angle at which the target will set. Negate this value to obtain the rise time. By default assumes the target sets at an elevation of 0 degrees. An optional hash can be given with key of "horizon" specifying a different elevation (in radians).

$ha = $c->ha_set;
$ha = $c->ha_set( horizon => $el );

Returned in radians, unless overridden with the "format" key. (See the ha method for alternatives).

$ha = $c->ha_set( horizon => $el, format => 'h');

There are predefined elevations for events such as Sun rise/set and Twilight (only relevant if your object refers to the Sun). See "Constants" for more information.

Returns undef if the target never reaches the specified horizon. (maybe it is circumpolar).

meridian_time

Calculate the meridian time for this target (the time at which the source transits).

MT(UT) = RA - LST(UT=0)

The next transit following the current time is calculated and returned as a Time::Piece object.

transit_el

Elevation at transit. This is just the elevation at Hour Angle = 0.0. (ie at meridian_time).

Format is supported as for the el method.

$el = $c->transit_el( format => 'deg' );
_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 );

If the input value is undefined the return value will be undefined.

_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". Warnings are issued if the string can not be parsed or the values are out of range.

Returns undef on error.

_mjd_tt

Retrieve the MJD in TT (Terrestrial time) rather than UTC time.

CONSTANTS

In some cases when calculating events such as sunrise, sunset or twilight time it is useful to have predefined constants containing the standard elevations. These are available in the Astro::Coords namespace as:

SUN_RISE_SET: Position of Sun for sunrise or sunset (-50 arcminutes)
CIVIL_TWILIGHT: Civil twilight (-6 degrees)
NAUT_TWILIGHT: Nautical twilight (-12 degrees)
AST_TWILIGHT: Astronomical twilight (-18 degrees)

For example:

$set = $c->set_time( horizon => Astro::Coords::AST_TWILIGHT );

These are usually only relevant for the Sun. Note that refraction effects may affect the actual answer and these are simply average definitions.

REQUIREMENTS

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

AUTHOR

Tim Jenness <tjenness@cpan.org>

COPYRIGHT

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