/ 
Astro-MoonPhase-Simple-0.03
River stage zero No dependents
/ Astro::MoonPhase::Simple

NAME

Astro::MoonPhase::Simple - Calculate the phase of the Moon on a given time without too much blah blah

VERSION

Version 0.03

SYNOPSIS

This package provides a single subroutine to calculate the phase of the moon on a given time. The results are returned as a hash.

The heavy lifting is done by Astro::MoonPhase. All this package does is to wrap the functionality of Astro::MoonPhase adding some parameter checking.

use Astro::MoonPhase::Simple;

my $res = calculate_moon_phase({
  'date' => '1974-07-15',
  'timezone' => 'Asia/Nicosia',
});
print "moon is ".$res->{'MoonPhase%'}."% full\n";
print "moon is illuminated by ".$res->{'MoonIllum%'}."%\n";

print $res->{'asString'};

# alternatively provide location coordinates
# (instead of timezone) to deduce the timezone
my $res = calculate_moon_phase({
  'date' => '1974-07-15',
  'time' => '04:00',
  'location' => {lat=>49.180000, lon=>-0.370000}
});

# alternatively provide a nameplace instead of a timezone
# to deduce the timezone
my $res = calculate_moon_phase({
  'date' => '1974-07-15',
  'time' => '04:00',
  'location' => 'Nicosia',
});

...

EXPORT

  • calculate_moon_phase()

SUBROUTINES

calculate_moon_phase

This is the main and only subroutine which is exported by default. It expects a HASH reference as its input parameter containing date, in the form "YYYY-MM-DD", and optionally time, in the form "hh:mm:ss". The timezone the date is pertaining to can be specified using key "timezone", in the form of a TZ identifier, e.g. "Africa/Abidjan". Alternatively, specify the location, as a HASHref of {lon, lat}, the moon is observed from and this will deduce the timezone, albeit not always as accurately as with specifying a "timezone" explicitly.

Warning: if the caller does not specify a timezone or location then the specified time will be assumed to be UTC time and not at the local timezone of the host.

Astro::MoonPhase calculates the moon phase given an epoch. Which is the number of seconds since 1970-01-01 on a UTC timezone. This epoch is corrected to a "localepoch" by adding to it the specific timezone offset. For example, if you specified the timezone to be "China/Beijing" and the local time (at the specified timezone) to be 23:00. It means UTC time is 15:00. The epoch will be calculated on UTC time. However, we add 23:00-15:00=8:00 hours to that epoch to make it "localepoch" and this is what we pass on to Astro::MoonPhase to calculate the moon phase.

On failure it returns undef. On success it returns a HASHref with keys:

  • MoonPhase : the moon phase (terminator phase angle) as a number between 0 and 1. New Moon (dark) being 0 and Full Moon (bright) being 1.

  • MoonPhase% : the above as a percentage.

  • MoonIllum : the illuminated fraction of the moon's disc as a number between 0 and 1. New Moon (dark) being 0 and Full Moon (bright) being 1.

  • MoonIllum% : the above as a percentage.

  • MoonAge : the fractional number of days since the Moon's birth (new moon), at specified date.

  • MoonDist : the distance of the Moon from the centre of the Earth (kilometers).

  • MoonAng : the angular diameter subtended by the Moon as seen by an observer at the centre of the Earth

  • SunDist : Moon's distance from the Sun (kilometers).

  • SunAng : the angular size of Sun (degrees).

  • phases : a HASHref containing the date and time for the various Moon phases (at specified date). It contains keys New Moon, First quarter, Full moon, Last quarter, Next New Moon

  • asString : a string representation of the above.

SCRIPT

The script moon-phase-calculator.pl is provided for doing the calculations via the command line.

Example usage: moon-phase-calculator.pl --date 1974-07-14 --timezone 'Asia/Nicosia'

SEE ALSO

This package summarises the post and discussion this post over at PerlMonks.org

There are some more goodies in that post e.g. PerlMonk Aldebaran provides code for tracking the planets and at different altitudes.

I can't iterate enough that this module wraps the functionality of Astro::MoonPhase. Astro::MoonPhase does all the heavy lifting.

CAVEATS

In calculate_moon_phase, if the caller does not specify a timezone or location then the specified time will be assumed to be UTC time and not at the local timezone of the host.

AUTHOR

Andreas Hadjiprocopis, <bliako at cpan.org>

DEDICATIONS

Marathon Almaz

BUGS

Please report any bugs or feature requests to bug-astro-moonphase-simple at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Astro-MoonPhase-Simple. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Astro::MoonPhase::Simple

You can also look for information at:

ACKNOWLEDGEMENTS

The authors of Astro::MoonPhase take all the credit.

LICENSE AND COPYRIGHT

This software is Copyright (c) 2024 by Andreas Hadjiprocopis.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)