Astro::Coords - Class for handling astronomical coordinates
$c = new Astro::Coords( name => "My target",
ra => '05:22:56',
dec => '-26:20:40.4',
type => 'B1950'
$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 );
# Associate with an observer location
$c->telescope( new Astro::Telescope( 'JCMT' ));
# ...and a reference epoch for all calculations
$date = Time::Piece->strptime($string, $format);
$c->datetime( $date );
# or use DateTime
$date = DateTime->from_epoch( epoch => $epoch, time_zone => 'UTC' );
$c->datetime( $date );
# Return coordinates J2000, for the epoch stored in the datetime
# object. This will work for all variants.
($ra, $dec) = $c->radec();
$radians = $ra->radians;
# or individually
$ra = $c->ra(); # returns Astro::Coords::Angle::Hour object
$dec = $c->dec( format => 'deg' );
# Return coordinates J2000, epoch 2000.0
$ra = $c->ra2000();
$dec = $c->dec2000();
# Return coordinats apparent, reference epoch, from location
# In sexagesimal format.
($ra_app, $dec_app) = $c->apparent;
$ra_app = $c->ra_app( format => 's');
$dec_app = $c->dec_app( format => 's' );
# Azimuth and elevation for reference epoch from observer location
($az, $el) = $c->azel;
my $az = $c->az;
my $el = $c->el;
# 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 );
# Calculate the rise and set time of the source
$tr = $c->rise_time;
$ts = $c->set_time;
# transit elevation
$trans = $c->transit_el;
# transit time
$mtime = $c->meridian_time();
Class for manipulating and transforming astronomical coordinates. Can handle the following coordinate types:
+ Equatorial RA/Dec, galactic (including proper motions and parallax)
+ Fixed locations in azimuth and elevations
+ interpolated apparent coordinates
For time dependent calculations a telescope location and reference time must be provided. See Astro::Telescope and DateTime for details on specifying location and reference epoch.
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 );
$c = new Astro::Coords( elements => \@array );
where %elements must contain the names of the elements as used in the PAL routine palPlante, and @array is the contents of the array returned by calling the array() method on another Elements object.
Fixed astronomical oordinate frames can be specified using:
$c = new Astro::Coords( ra =>
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 =>
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.
Name of the target associated with the coordinates.
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.
Date/Time object to use when determining the source elevation.
$c->datetime( new Time::Piece() );
Argument must be an object that has the mjd method. Both DateTime and Time::Piece objects are allowed. 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 and no Date/Time object had already been supplied, or usenow is set to true, an object referring to the current time (GMT/UT) is returned. This object may be either a Time::Piece object or a DateTime object depending on current implementation (but in modern versions it will be a DateTime object). If a Date/Time object had already been specified then the object returned will be of the same type as the supplied object (DateTime or Time::Piece). If a new argument is supplied usenow is always set to false.
A copy of the input argument is created, guaranteeing a UTC representation.
Note that due to the possibility of an optimized caching scheme being used, you should not adjust this object after it has been cloned. The object is assumed to be immutable by the module internals. If you really do require that it be adjusted externally, use the datetime_is_unsafe method to indicate this to the module.
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.
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.
If true, indicates that the DateTime object stored in this object is not guranteed to be immutable by the externally user. This effectively turns off the internal cache.
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.
Returns the name of the method that should be called to return the coordinates in a form as close as possible to those that were supplied to the constructor. This method is useful if, say, the object is created from Galactic coordinates but internally represented in a different coordinate frame.
$native_method = $c->native;
This method can then be called to retrieve the coordinates:
($c1, $c2) = $c->$native_method();
Currently, the native form will not exactly match the supplied form if a non-standard equinox has been used, or if proper motions and parallax are present, but the resulting answer can be used as a guide.
If no native method is obvious (e.g. for a planet), 'apparent' will be returned.
Return Azimuth and elevation for the currently stored time and telescope. If no telescope is present the equator is used. Returns the Az and El as Astro::Coords::Angle objects.
($az, $el) = $c->azel();
Apparent RA for the current time.
$ra_app = $c->ra_app( format => "s" );
See "NOTES" for details on the supported format specifiers and default calling convention.
Apparent Dec for the currently stored time.
$dec_app = $c->dec_app( format => "s" );
Get the hour angle for the currently stored LST. By default HA is returned as an Astro::Coords::Angle::Hour object.
$ha = $c->ha;
$ha = $c->ha( format => "h" );
By default the Hour Angle will be normalised to +/- 12h if an explicit format is specified.
Azimuth of the source for the currently stored time at the current telescope. See "NOTES" for details on the supported format specifiers and default calling convention.
$az = $c->az();
If no telescope is defined the equator is used.
Elevation of the source for the currently stored time at the current telescope. See "NOTES" for details on the supported format specifiers and default calling convention.
$el = $c->el();
Airmass of the source for the currently stored time at the current telescope.
$am = $c->airmass();
Value determined from the current elevation.
Return the J2000 Right Ascension and Declination for the target. Unless overridden by a subclass, this converts from the apparent RA/Dec to J2000. Returns two Astro::Coords::Angle objects.
($ra, $dec) = $c->radec();
Return the J2000 Right ascension for the target. Unless overridden by a subclass this converts the apparent RA/Dec to J2000.
$ra2000 = $c->ra( format => "s" );
Calls the radec method. See "NOTES" for details on the supported format specifiers and default calling convention.
Return the J2000 declination for the target. Unless overridden by a subclass this converts the apparent RA/Dec to J2000.
$dec2000 = $c->dec( format => "s" );
Return Galactic longitude. See "NOTES" for details on the supported format specifiers and default calling convention.
$glong = $c->glong( format => "s" );
Return Galactic latitude. See "NOTES" for details on the supported format specifiers and default calling convention.
$glat = $c->glat( format => "s" );
Return SuperGalactic longitude. See "NOTES" for details on the supported format specifiers and default calling convention.
$sglong = $c->sglong( format => "s" );
Return SuperGalactic latitude. See "NOTES" for details on the supported format specifiers and default calling convention.
$glat = $c->sglat( format => "s" );
Return Ecliptic longitude. See "NOTES" for details on the supported format specifiers and default calling convention.
$eclong = $c->ecllong( format => "s" );
Return ecliptic latitude. See "NOTES" for details on the supported format specifiers and default calling convention.
$eclat = $c->ecllat( format => "s" );
Calculate Galactic longitude and latitude. Position is calculated for the current ra/dec position (as returned by the radec method).
($long, $lat) = $c->glonglat;
Answer is returned as two Astro::Coords::Angle objects.
Calculate Super Galactic longitude and latitude.
($slong, $slat) = $c->sglonglat;
Calculate the ecliptic longitude and latitude for the epoch stored in the object. Position is calculated for the current ra/dec position (as returned by the radec method.
($long, $lat) = $c->ecllonglat();
Convenience wrapper routine to return the J2000 coordinates for epoch 2000.0. This is not the same as calling the radec method with equinox J2000.0.
($ra2000, $dec2000) = $c->radec2000;
It is equivalent to setting the epoch in the object to 2000.0 (ie midday on 2000 January 1) and then calling radec.
The answer will be location dependent in most cases.
Results are returned as two Astro::Coords::Angle objects.
Convenience wrapper to return the FK4 B1950 coordinates for the currently defined epoch. Since the FK4 to FK5 conversion requires an epoch, the J2000 coordinates are first calculated for the current epoch and the frame conversion is done to epoch B1950.
This is technically not the same as calling the radec() method with equinox B1950 since that would use the current epoch associated with the coordinates when converting from FK4 to FK5.
In the base class these are calculated by precessing the J2000 RA/Dec for the current date and time, which are themselves derived from the apparent RA/Dec for the current time.
($ra, $dec) = $c->radec1950;
Parallactic angle of the source for the currently stored time at the current telescope. See "NOTES" for details on the supported format specifiers and default calling convention.
$pa = $c->pa();
$padeg = $c->pa( format => 'deg' );
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.
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)
Calculate the distance (on the tangent plane) between the current coordinate and a supplied coordinate.
$dist = $c->distance( $c2 );
@dist = $c->distance( $c2 );
In scalar context the distance is returned as an Astro::Coords::Angle object In list context returns the individual "x" and "y" offsets (as Astro::Coords::Angle objects).
Returns undef if there was an error during the calculation (e.g. because the new coordinate was too far away).
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 target positions for a range of times.
@data = $c->calculate( start => $start,
end => $end,
inc => $increment,
units => 'deg'
The start and end times are either Time::Piece or DateTime objects and the increment is either a Time::Seconds object, a DateTime::Duration object (in fact, an object that implements the seconds method) 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 [same object class as provided as argument]
lst [always in radians]
The angles are in the units specified (radians, degrees or sexagesimal). They will be Angle objects if no units are specified.
Note that this method returns DateTime objects if it was given DateTime objects, else it returns Time::Piece objects.
After running, the original time associated with the object will be retained.
Time at which the target will appear above the horizon. By default the calculation is for the next rise time relative to the current reference time. If the "event" key is used, this can control which rise time will be returned. For event=1, this indicates the following rise (the default), event=-1 indicates a previous rise and event=0 indicates the nearest source rising to the current reference time.
If the "nearest" key is set in the argument hash, this is synonymous with event=0 and supercedes the event key.
Returns undef if the target is never visible or never sets. 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 );
$t = $c->set_time( nearest => 1 );
$t = $c->set_time( event => -1 );
Returns a Time::Piece object or a DateTime object depending on the type of object that is returned by the datetime method.
For some occasions the calculation will be performed twice, once for the meridian transit before the reference time and once for the transit after the reference time.
Does not distinguish a source that never rises from a source that never sets. Both will return undef for the rise time.
Next and previous depend on the adjacent transits. The routine will not step forward multiple days looking for a rise time if the source is not going to rise before the next or previous transit.
Time at which the target will set below the horizon. By default the calculation is the next set time from the current reference time. If the "event" key is used, this can control which set time will be returned. For event=1, this indicates the following set (the default), event=-1 indicates a previous set and event=0 indicates the nearest source setting to the current reference time.
Does not distinguish a source that never rises from a source that never sets. Both will return undef for the set time.
Next and previous depend on the adjacent transits. The routine will not step forward multiple days looking for a set time if the source is not going to set following the next or previous transit.
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 (except for the Sun and Moon which are special-cased). 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 by default as an Astro::Coords::Angle::Hour object unless an explicit "format" is specified.
$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).
For the Sun and moon this calculation will not be very accurate since it depends on the time for which the calculation is to be performed (the time is not used by this routine) and the rise Hour Angle and setting Hour Angle will differ (especially for the moon) . These effects are corrected for by the rise_time and set_time methods.
In some cases for the Moon, an iterative technique is used to calculate the hour angle when the Moon is near transit (the simple geometrical arguments do not correctly calculate the transit elevation).
Calculate the meridian time for this target (the time at which the source transits).
MT(UT) = apparent RA - LST(UT=0)
By default the next transit following the current time is calculated and returned as a Time::Piece or DateTime object (depending on what is stored in datetime).
If you want control over which transit should be calculated this can be specified using the "event" hash key:
$mt = $c->meridian_time( event => 1 );
$mt = $c->meridian_time( event => 0 );
$mt = $c->meridian_time( event => -1 );
A value of "1" indicates the next transit following the current reference time (this is the default behaviour for reasons of backwards compatibility). A value of "-1" indicates that the closest transit event before the reference time should be used. A valud of "0" indicates that the nearest transit event should be returned. If the parameter value is not one of the above, it will default to "1".
A synonym for event=>0 is provided by using the "nearest" key. If present and true, this key overrides "event". If present and false the "event" key is used (defaulting to "1" if event indicates "nearest"=1).
$mt = $c->meridian_time( nearest => 1 );
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. See "NOTES" for details on the supported format specifiers and default calling convention.
$el = $c->transit_el( format => 'deg' );
Applies the offsets of an Astro::Coords::Offset object.
my $coords_offset = $coords->apply_offset($offset);
The current implementation works by calling radec2000 or glonglat on the original object and will return a new Astro::Coords::Equatorial object.
This sections describes the available methods for determining the velocities of each of the standard velocity frames in the direction of the reference target relative to the current observer position and reference time.
Return the radial velocity of the target (not the observer) in km/s. This will be used for parallax corrections (if relevant) and for calculating the doppler correction factor.
$rv = $c->rv();
If the velocity was originally specified as a redshift it will be returned here as optical velocity (and may not be a physical value).
If no radial velocity has been specified, returns 0 km/s.
Redshift is defined as the optical velocity as a fraction of the speed of light:
v(opt) = c z
Returns the reshift if the velocity definition is optical. If the velocity definition is radio, redshift can only be calculated for small radio velocities. An attempt is made to calculate redshift from radio velocity using
v(opt) = v(radio) / ( 1 - v(radio) / c )
but only if v(radio)/c is small. Else returns undef.
The velocity definition used to specify the target radial velocity. This is a readonly parameter set at object creation (depending on subclass) and can be one of RADIO, OPTICAL, RELATIVISTIC or REDSHIFT (which is really optical but specified in a different way).
$vdefn = $c->vdefn();
Required for calculating the doppler correction. Defaults to 'OPTICAL'.
The velocity frame used to specify the radial velocity. This attribute is readonly and set during object construction. Abbreviations are used for the first 3 characters of the standard frames (4 to distinguish LSRK from LSRD):
HEL - Heliocentric (the Sun)
BAR - Barycentric (the Solar System barycentre)
GEO - Geocentric (Centre of the Earth)
TOP - Topocentric (Surface of the Earth)
LSR - Kinematical Local Standard of Rest
LSRK - As for LSR
LSRD - Dynamical Local Standard of Rest
The usual definition for star catalogues is Heliocentric. Default is Heliocentric.
Calculates the observed velocity of the target as seen from the observer's location. Includes both the observer velocity and target velocity.
$rv = $c->obsvel;
Note that the source velocity and observer velocity are simply added without any regard for relativistic effects for high redshift sources.
Calculates the doppler factor required to correct a rest frequency to an observed frequency. This correction is calculated for the observer location and specified date and uses the velocity definition provided to the object constructor. Both the observer radial velocity, and the target radial velocity are taken into account (see the obsvel method).
$dopp = $c->doppler;
Default definitions and frames will be used if none were specified.
The doppler factors (defined as frequency/rest frequency or rest wavelength / wavelength) are calculated as follows:
RADIO: 1 - v / c
OPTICAL 1 - v / ( v + c )
REDSHIFT ( 1 / ( 1 + z ) ) * ( 1 - v(hel) / ( v(hel) + c ) )
ie in order to observe a line in the astronomical target, multiply the rest frequency by the doppler correction to select the correct frequency at the telescope to tune the receiver.
For high velocity optical sources ( v(opt) << c ) and those sources specified using redshift, the doppler correction is properly calculated by first correcting the rest frequency to a redshifted frequency (dividing by 1 + z) and then separately correcting for the telescope motion relative to the new redshift corrected heliocentric rest frequency. The REDSHIFT equation, above, is used in this case and is used if the source radial velocity is > 0.01 c. ie the Doppler correction is calculated for a source at 0 km/s Heliocentric and combined with the redshift correction.
The Doppler correction is invalid for large radio velocities.
Simple wrapper around the individual velocity methods (vhelio, vlsrk etc) to report the difference in velocity between two arbitrary frames.
$vd = $c->vdiff( 'HELIOCENTRIC', 'TOPOCENTRIC' );
$vd = $c->vdiff( 'HEL', 'LSRK' );
Note that the velocity methods all report their velocity relative to the observer (ie topocentric correction), equivalent to specifiying 'TOP' as the second argument to vdiff.
The two arguments are mandatory but if either are 'undef' they are converted to the target velocity frame (see vdefn method).
The second example is simply equivalent to
$vd = $c->vhelio - $c->vlsrk;
but the usefulness of this method really comes into play when defaulting to the target frame since it removes the need for logic in the main program.
$vd = $c->vdiff( 'HEL', '' );
The velocity component of the Earth's rotation in the direction of the target (in km/s).
$vrot = $c->verot();
Current time will be assumed if none is set. If no observer location is specified, the equator at 0 deg lat will be used.
Velocity component of the Earth's orbit in the direction of the target (in km/s) for the current date and time.
$vorb = $c->vorb;
By default calculates the velocity component relative to the Sun. If an optional parameter is true, the calculation will be relative to the solary system barycentre.
$vorb = $c->vorb( $usebary );
Velocity of the observer with respect to the Sun in the direction of the target (ie the heliocentric frame). This is simply the sum of the component due to the Earth's orbit and the component due to the Earth's rotation.
$vhel = $c->vhelio;
Velocity of the observer with respect to the Solar System Barycentre in the direction of the target (ie the barycentric frame). This is simply the sum of the component due to the Earth's orbit and the component due to the Earth's rotation.
$vhel = $c->vbary;
Velocity of the observer with respect to the kinematical Local Standard of Rest in the direction of the target.
$vlsrk = $c->vlsrk();
Velocity of the observer with respect to the dynamical Local Standard of Rest in the direction of the target.
$vlsrd = $c->vlsrd();
Velocity of the observer with respect to the centre of the Galaxy in the direction of the target.
$vlsrd = $c->vgalc();
Velocity of the observer with respect to the Local Group in the direction of the target.
$vlsrd = $c->vlg();
Many of the methods described in these classes return results as either Astro::Coords::Angle and Astro::Coords::Angle::Hour objects. This provides to the caller much more control in how to represent the answer, especially when the default stringification may not be suitable. Whilst methods such as radec and apparent always return objects, methods to return individual coordinate values such as ra, dec, and az can return the result in a variety of formats. The default format is simply to return the underlying Angle object but an explicit format can be specified if you are simply interested in the value in degrees, say, or are instantly stringifying it. The supported formats are all documented in the in_format method documentation in the Astro::Coords::Angle man page but include all the standard options that have been available in early versions of Astro::Coords: 'sexagesimal', 'radians', 'degrees'.
$radians = $c->ra( format => 'rad' );
$string = $c->ra( format => 'sex' );
$deg = $c->ra( format => 'deg' );
$object = $c->ra();
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)
$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.
For the Sun and Moon the expected defaults are used if no horizon is specified (ie SUN_RISE_SET is used for the Sun).
Astro::PAL is used for all internal astrometric calculations.
Astro::Telescope and DateTime are used to specify observer location and reference epoch respectively.
Astro::Coords::Equatorial, Astro::Coords::Planet, Astro::Coords::Fixed, Astro::Coords::Interpolated, Astro::Coords::Calibration, Astro::Coords::Angle, Astro::Coords::Angle::Hour.
Tim Jenness <email@example.com>
Copyright (C) 2008, 2010, 2012 Science & Technology Facilities Council. Copyright (C) 2001-2005 Particle Physics and Astronomy Research Council. 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 3 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
To install Astro::Coords, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.