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

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

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

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

This is required because "datetime" always returns a time.

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

Defaults to false.

  $c->datetime_is_unsafe();
    

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

Always returns an empty string if undefined.

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

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

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

See "NOTES" for details on the supported format specifiers and default calling convention.

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

See "NOTES" for details on the supported format specifiers and default calling convention.

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

By default the Hour Angle will be normalised to +/- 12h if an explicit format is specified.

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.

  $el = $c->el();
    

If no telescope is defined the equator is used.

  $am = $c->airmass();
    

Value determined from the current elevation.

 ($ra, $dec) = $c->radec();
    

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

Calls the "radec" method. See "NOTES" for details on the supported format specifiers and default calling convention.

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

Calls the "radec" method. See "NOTES" for details on the supported format specifiers and default calling convention.

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

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

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

  $glat = $c->sglat( format => "s" );
    

  $eclong = $c->ecllong( format => "s" );
    

  $eclat = $c->ecllat( format => "s" );
    

 ($long, $lat) = $c->glonglat;
    

Answer is returned as two "Astro::Coords::Angle" objects.

 ($slong, $slat) = $c->sglonglat;
    

Answer is returned as two "Astro::Coords::Angle" objects.

 ($long, $lat) = $c->ecllonglat();
    

Answer is returned as two "Astro::Coords::Angle" objects.

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

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;
    

Results are returned as two "Astro::Coords::Angle" objects.

  $pa = $c->pa();
  $padeg = $c->pa( format => 'deg' );
    

If no telescope is defined the equator is used.

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

  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)
    

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

  $status = $c->status;
    

  @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]
  elevation
  azimuth
  parang
  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.

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.

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

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

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

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

  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.

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

  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.

  $vdefn = $c->vdefn();
    

Required for calculating the doppler correction. Defaults to 'OPTICAL'.

  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.

 $rv = $c->obsvel;
    

Note that the source velocity and observer velocity are simply added without any regard for relativistic effects for high redshift sources.

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

  $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', '' );
    

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

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

 $vhel = $c->vhelio;
    

 $vhel = $c->vbary;
    

  $vlsrk = $c->vlsrk();
    

  $vlsrd = $c->vlsrd();
    

  $vlsrd = $c->vgalc();
    

  $vlsrd = $c->vlg();