Astro::Coords(3pm)

📦 version 0.23, in alpine 3.24

💖 NAME 💖

Astro::Coords(3pm) is the manual page for Astro::Coords, aka the class for handling astronomical coordinates. That’s the whole name vibe: coordinates, handled. ✨

🌈 SYNOPSIS 🌈

okay so here’s the group-chat cheat sheet — all of this is literal Perl, bestie:

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

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

🦋 DESCRIPTION 🦋

Class for manipulating and transforming astronomical coordinates. It can handle these coordinate types, no cap:

Equatorial RA/Dec, galactic (including proper motions and parallax)
Planets
Comets/Asteroids
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.

👑 METHODS 👑

🧚 Constructor

`new`

This can be treated as an object factory, bestie. 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 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.

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. the label on your cosmic fave 💅

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

okay so important caveat: 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. 🫶

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

`datetime_is_unsafe`

If true, indicates that the DateTime object stored in this object is not guaranteed to be immutable by the external user. This effectively turns off the internal cache.

  $c->datetime_is_unsafe();

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

`native`

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.

⭐ General Methods

`azel`

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

`ra_app`

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.

`dec_app`

Apparent Dec for the currently stored time.

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

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

`ha`

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.

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

`az`

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.

`el`

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

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. ✨ (Yes bestie, we're still mid-list — carry on.)

radec — hands you the J2000 Right Ascension and Declination for your target. Unless a subclass overrides it, this converts from the apparent RA/Dec on over to J2000. You get back two Astro::Coords::Angle objects, cute and packaged. 💖

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

ra — just the J2000 Right Ascension, nothing else. Unless a subclass overrides it, it converts the apparent RA/Dec to J2000. Under the hood it calls the radec method — so peep the NOTES section for all the deets on supported format specifiers and the default calling convention. 🌸

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

dec — the J2000 declination only. Unless a subclass overrides it, it converts the apparent RA/Dec to J2000. Also calls radec. Again: NOTES for format specifiers and the default calling convention. 🦋

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

glong — Galactic longitude, served fresh. Format specifiers + default calling convention live in NOTES. ⭐

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

glat — Galactic latitude. Same drill: NOTES has the format specifiers and default calling convention. 🌈

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

sglong — SuperGalactic longitude, yes super, very main character energy. Format specifiers and default calling convention = NOTES. 👑

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

sglat — SuperGalactic latitude. NOTES for format specifiers and default calling convention, iykyk.

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

ecllong — Ecliptic longitude. Format specifiers and default calling convention? Say it with me: NOTES. 💫

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

ecllat — ecliptic latitude. Same rules, NOTES for the format specifiers and default calling convention. 🎀

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

glonglat — calculates Galactic longitude and latitude in one go. The position comes from the current ra/dec position — literally whatever the radec method hands back. 🫶

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

Answer comes back as two Astro::Coords::Angle objects.

sglonglat — calculates Super Galactic longitude and latitude together. 🌀

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

Also two Astro::Coords::Angle objects, no cap.

ecllonglat — calculates 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 — note the original doc leaves the paren hanging here, we love an unfinished thought 💀).

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

Yep, two Astro::Coords::Angle objects.

radec2000 — convenience wrapper routine that returns the J2000 coordinates for epoch 2000.0. ⚠️ Heads up: this is not the same as calling the radec method with equinox J2000.0. Not even close, bestie.

($ra2000, $dec2000) = $c->radec2000;

It's equivalent to setting the epoch in the object to 2000.0 (that's midday on 2000 January 1, fact check ✅) and then calling radec.

The answer will be location dependent in most cases. 📍

Results come back as two Astro::Coords::Angle objects.

radec1950 — convenience wrapper that returns the FK4 B1950 coordinates for the currently defined epoch. Because the FK4 → FK5 conversion requires an epoch, the J2000 coordinates get calculated first for the current epoch, and then the frame conversion is done to epoch B1950. Two-step slay. 💅

Technically this is not the same as calling the radec() method with equinox B1950 — because that would use the current epoch associated with the coordinates when converting from FK4 to FK5. Subtle, but important, don't come for me.

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. It's giving pipeline. 🔥

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

Results: two Astro::Coords::Angle objects, as always. 🎁

pa — parallactic angle of the source, for the currently stored time, at the current telescope. NOTES has the supported format specifiers and default calling convention, obviously. 🌙

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

If no telescope is defined, the equator is used. Default behavior, iconic.

isObservable — determines whether the coordinates are actually accessible for the current time and telescope. The vibe check of the whole object tbh. 🔭

$isobs = $c->isObservable;

Returns false if a telescope hasn't been specified (see the telescope method) — or if the specified telescope doesn't know its own limits. No telescope, no answers. 😭

array — returns a summary of this object in the form of an array holding 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 — calculates 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 you get 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. Too far, bestie, it's not gonna work out. 💀

status — returns a status string describing the current coordinates. It consists of the current elevation, azimuth, hour angle and declination. If a telescope is defined, the observability of the target is included too. 🗒️

$status = $c->status;

calculate — calculates target positions for a range of times. Bulk mode, we love efficiency. ⚡

@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 won't necessarily be used explicitly when the increment doesn't divide into the total time gap exactly — read that again, it's a whole thing. 🫠 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. (Zero increment = you're not doing that. 😤)

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'll be Angle objects if no units are specified. ✨

Note that this method returns DateTime objects if it was given DateTime objects — otherwise it returns Time::Piece objects. It matches energies. 🪞

After running, the original time associated with the object will be retained. Nothing gets lost, periodt.

rise_time — the 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, you can control which rise time comes back: event=1 means the following rise (that's the default 💖), event=-1 means a previous rise, and event=0 means the nearest source rising to the current reference time.

If the nearest key is set in the argument hash, that's synonymous with event=0 and it supercedes the event key. Nearest wins, sorry event. 🏆

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

🚨 Yes — those examples really do say set_time inside the rise_time entry. That's exactly what the doc says, so that's exactly what you get. Don't @ me.

Returns a Time::Piece object or a DateTime object, depending on the type of object that's 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. Double the math, double the fun. 😮‍💨

It does not distinguish a source that never rises from a source that never sets. Both will return undef for the rise time. Equality in the void. 🕳️

Next and previous depend on the adjacent transits. The routine will not step forward multiple days looking for a rise time if the source isn't going to rise before the next or previous transit. It's not gonna go on a whole journey for you. 🙅‍♀️

set_time — the 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 controls which set time comes back: event=1 is the following set (default 💖), event=-1 is a previous set, and event=0 is the nearest source setting to the current reference time.

If the nearest key is set in the argument hash, that's synonymous with event=0 and it supercedes the event key. Same rules, sunset edition. 🌙

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 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. Yep, again. 🔁

Does not distinguish a source that never rises from a source that never sets. Both 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 isn't going to set following the next or previous transit.

ha_set — the hour angle at which the target will set. Negate this value to get the rise time (yes, just flip the sign, math is wild 🧮). By default it assumes the target sets at an elevation of 0 degrees — except for the Sun and Moon, which are special-cased, because of course they are, main characters. ☀️🌕 An optional hash can be given with key 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 also predefined elevations for events like Sun rise/set and Twilight — but this only matters if your object is actually the Sun, bestie. Peep "CONSTANTS" for the full tea. ☀️

It returns undef if the target never actually reaches the horizon you asked for (maybe it's circumpolar, i.e. it just vibes up there and never sets 😭).

⚠️ For the Sun and the Moon this calculation is not super accurate, because it depends on the time the calculation is for (and this routine doesn't use the time at all, bestie) — plus the rise Hour Angle and the set Hour Angle are different (especially for the Moon, she's extra 💅). Those effects get properly corrected by the rise_time and set_time methods, so don't come for this one.

In some cases for the Moon, an iterative technique is used to calculate the hour angle when the Moon is near transit (because the simple geometrical arguments do not correctly calculate the transit elevation — the geometry just isn't geometrying 🙈).

`meridian_time` 🌙

Calculates the meridian time for this target — i.e. the time at which the source transits. Iconic. ⭐

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

By default it computes the next transit following the current time and returns it as a Time::Piece or DateTime object (whichever one is stored in datetime — it matches the vibe of what you gave it 🫶).

If you want control over which transit gets calculated, you can say so with 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 means the next transit following the current reference time (this is the default behaviour, for backwards compatibility reasons 💀).
A value of -1 means the closest transit event before the reference time.
A value of 0 means the nearest transit event should be returned.

If the parameter value is not one of the above, it will default to 1. No cap.

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

`transit_el` 🔭

Elevation at transit — literally just the elevation at Hour Angle = 0.0 (i.e. at meridian_time). So simple, so clean, we love her.

Format is supported exactly as for the el method. See "NOTES" for the details on the supported format specifiers and the default calling convention. ✨

$el = $c->transit_el( format => 'deg' );

`apply_offset` 🎀

Applies the offsets of an Astro::Coords::Offset object. Slay.

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. Fresh object, who dis. 💅

🌀 Velocities

This section 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. Buckle up bestie, we're going fast (literally) 🚀

`rv`

Returns the radial velocity of the target (not the observer, ok?) in km/s. This gets 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, fair warning, it may not be a physical value 🙈).

If no radial velocity has been specified, it returns 0 km/s.

`redshift`

Redshift is defined as the optical velocity as a fraction of the speed of light:

v(opt) = c z

Returns the redshift if the velocity definition is optical. If the velocity definition is radio, redshift can only be calculated for small radio velocities. It makes an attempt to calculate redshift from radio velocity using:

v(opt) = v(radio) / ( 1 - v(radio) / c )

...but only if v(radio)/c is small. Else it returns undef. That's it, that's the deal. 🤷‍♀️

`vdefn`

The velocity definition used to specify the target radial velocity. This is a readonly parameter set at object creation (depending on the subclass) and can be one of RADIO, OPTICAL, RELATIVISTIC or REDSHIFT (which is really optical, just specified in a different way — sneaky but valid 👑).

$vdefn = $c->vdefn();

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

`vframe`

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 characters to distinguish LSRK from LSRD — the extra letter is doing so much work rn 💅):

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

`obsvel`

Calculates the observed velocity of the target as seen from the observer's location. Includes both the observer velocity and the target velocity. Both. Together. Bestie behaviour. 🫶

$rv = $c->obsvel;

⚠️ Note that the source velocity and observer velocity are simply added, without any regard for relativistic effects for high redshift sources. So don't be surprised if things get weird at extreme velocities, ok?

`doppler`

Calculates the doppler factor required to correct a rest frequency to an observed frequency. This correction is calculated for the observer location and the 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. No setup needed, she just works. ✨

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

So — in order to observe a line in the astronomical target, you multiply the rest frequency by the doppler correction to select the correct frequency at the telescope to tune the receiver. That's the whole point, that's the assignment, periodt. 📻

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 — i.e. the Doppler correction is calculated for a source at 0 km/s Heliocentric and combined with the redshift correction. Genuinely so clever of her. 🧚

💀 The Doppler correction is invalid for large radio velocities. Like, undefined-territory invalid. Don't do it.

`vdiff`

A simple wrapper around the individual velocity methods (vhelio, vlsrk, etc.) to report the difference in velocity between two arbitrary frames. So handy.

$vd = $c->vdiff( 'HELIOCENTRIC', 'TOPOCENTRIC' );
$vd = $c->vdiff( 'HEL', 'LSRK' );

Note that the velocity methods all report their velocity relative to the observer (i.e. the topocentric correction), which is equivalent to specifying 'TOP' as the second argument to vdiff. iykyk 💅

The two arguments are mandatory, but if either are 'undef' they are converted to the target velocity frame (see the vdefn method). No crashes, just vibes.

The second example above 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. Lowkey a life saver. 👑

$vd = $c->vdiff( 'HEL', '' );

`verot`

The velocity component of the Earth's rotation in the direction of the target (in km/s). Spin spin spin 🌍

$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. Defaults are still defaults, bestie.

`vorb`

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 it calculates the velocity component relative to the Sun. If an optional parameter is true, the calculation will be relative to the Solar System barycentre instead. Fancy. 🪐

$vorb = $c->vorb( $usebary );

`vhelio`

Velocity of the observer with respect to the Sun in the direction of the target (i.e. 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. Math girlies rise ☀️

$vhel = $c->vhelio;

`vbary`

Velocity of the observer with respect to the Solar System Barycentre in the direction of the target (i.e. 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;

`vlsrk`

Velocity of the observer with respect to the kinematical Local Standard of Rest in the direction of the target.

$vlsrk = $c->vlsrk();

`vlsrd`

Velocity of the observer with respect to the dynamical Local Standard of Rest in the direction of the target.

$vlsrd = $c->vlsrd();

`vgalc`

Velocity of the observer with respect to the centre of the Galaxy in the direction of the target. Galactic queen 🌌

$vlsrd = $c->vgalc();

`vlg`

Velocity of the observer with respect to the Local Group in the direction of the target.

$vlsrd = $c->vlg();

💫 NOTES 💫

okay so this is the part where we talk about return types, and honestly it's giving "why is this so nice" energy. A ton of the methods in these classes hand you back Astro::Coords::Angle and Astro::Coords::Angle::Hour objects instead of boring old numbers — and that's a slay, because it means you (the caller) get way more control over how the answer gets represented, especially when the default stringification just isn't it. 🙈

So like: methods such as radec and apparent always return objects, no negotiation. But the ones that hand back individual coordinate values — ra, dec, az, bestie, the whole crew — can return the result in a variety of formats. The default is literally just to give you the underlying Angle object, but you can specify an explicit format if you only care about the value in degrees, say, or if you're instantly stringifying it. 🌸

All the supported formats are documented in the in_format method docs over in the Astro::Coords::Angle man page, but the classics that have been around since the early versions of Astro::Coords include 'sexagesimal', 'radians', and 'degrees'. iconic behaviour:

  $radians = $c->ra( format => 'rad' );
  $string  = $c->ra( format => 'sex' );
  $deg     = $c->ra( format => 'deg' );
  $object  = $c->ra();

🌅 CONSTANTS 🌅

so when you're calculating events like sunrise, sunset, or twilight time, it's genuinely useful to have predefined constants holding the standard elevations. they live right there in the Astro::Coords namespace, no cap:

  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)

like, for example 🫶

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

these are usually only relevant for the Sun, fyi. and heads up — refraction effects may affect the actual answer, and these are simply average definitions, so don't come for them when they're off by a lil bit. 💅

for the Sun and Moon the expected defaults are used if no horizon is specified (ie SUN_RISE_SET is used for the Sun). default queen behaviour 👑

🛠️ REQUIREMENTS 🛠️

Astro::PAL is used for all internal astrometric calculations. that's the whole requirement. she does the math, we just vibe. ✨

👀 SEE ALSO 👀

Astro::Telescope and DateTime are used to specify observer location and reference epoch respectively — so if you're wondering where those come from, there ya go.

and the whole squad: Astro::Coords::Equatorial, Astro::Coords::Planet, Astro::Coords::Fixed, Astro::Coords::Interpolated, Astro::Coords::Calibration, Astro::Coords::Angle, Astro::Coords::Angle::Hour. go read them too, they're all main characters. 🌈

💖 AUTHOR 💖

Tim Jenness <tjenness@cpan.org>

📜 COPYRIGHT 📜

okay legal era, but read it because it matters — 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. (yes the no-warranty part is in all caps in the original too — it's that serious 😭)

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.

this page was served up by perl v5.42.2 and dated 2026-02-15 — so if you're reading this in the future, hi bestie, the docs still ate 💅✨🎀

📦 where this page comes from

alpine 3.24: perl-astro-coords-doc 0.23-r1 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

Astro::Coords(3pm)

💖 NAME 💖

🌈 SYNOPSIS 🌈

🦋 DESCRIPTION 🦋

👑 METHODS 👑

🧚 Constructor

new

🎀 Accessor Methods

name

telescope

datetime

has_datetime

usenow

datetime_is_unsafe

comment

native

⭐ General Methods

azel

ra_app

dec_app

ha

az

el

airmass

meridian_time 🌙

transit_el 🔭

apply_offset 🎀

🌀 Velocities

rv

redshift

vdefn

vframe

obsvel

doppler

vdiff

verot

vorb

vhelio

vbary

vlsrk

vlsrd

vgalc

vlg

💫 NOTES 💫

🌅 CONSTANTS 🌅

🛠️ REQUIREMENTS 🛠️

👀 SEE ALSO 👀

💖 AUTHOR 💖

📜 COPYRIGHT 📜

`new`

`name`

`telescope`

`datetime`

`has_datetime`

`usenow`

`datetime_is_unsafe`

`comment`

`native`

`azel`

`ra_app`

`dec_app`

`ha`

`az`

`el`

`airmass`

`meridian_time` 🌙

`transit_el` 🔭

`apply_offset` 🎀

`rv`

`redshift`

`vdefn`

`vframe`

`obsvel`

`doppler`

`vdiff`

`verot`

`vorb`

`vhelio`

`vbary`

`vlsrk`

`vlsrd`

`vgalc`

`vlg`