
wmSunMoon README


Description
-------------------------------------------------------------------------
wmSunMoon displays Sun and Moon rise and set times as well as the Moon
phase.  By default it displays the Sun data during the day and the
Moon data during the night.  Around sunrise and sunset it emulates
the civil twilight and golden hour effects.  It can also display the
current time, the offsets for the civil twilight and golden hour, and the
percentage of the lunar cycle.  If both time and percentage switches are
used the program cycles them in the Moon view.  If both time zone and
time switches are used the program displays the time for the selected
time zone.  If both Sun and Moon switches are used the program cycles Sun
and Moon views forth and back.

Unlike the other dockable applications wmSunMoon offers also a text mode
displaying the complete data on the console.  It calculates a lot of data
but it is possible to display just a small fraction of them on the
dockable application window without cluttering it.  The text mode allows
to display all available data in a readable form.

Enter the valid latitude and longitude in order to display the valid
data.  For the distant locations enter local and distant time zones
names.

The correctness of the time calculated for the other time zone depends
on the time settings on your machine and the declared time zones.

After you click the dockapp window the program switches to the reverse
display for four seconds.

The program window displaying the Sun data looks like:

    +---------+    +---------+
    |sunrise  |    |sunrise  |
    |         |    |         |
    |(offset) | or |(time)   |
    |         |    |         |
    |sunset   |    |sunset   |
    +---------+    +---------+

The civil twilight -- called also civil dawn and dusk -- it is the time
when the Sun is from -6 to 0 degrees below the horizon.  During the
twilight it is enough light to distinguish the objects outside.  Golden
hour follows the morning twilight and precedes the evening twilight.  It
is the time when the Sun is from 0 to 6 degrees above the horizon.
During the golden hour the light of the Sun seems to be more or less
reddish.

wmSunMoon emulates the morning and evening twilights and golden hours in
the Sun view.  Using the offsets you might calculate the beginning and
the end of the civil twiligt as well as the end and the beginning of both
golden hours.  To do this it is enough to subtract or add the right offset
from or to the sunrise or sunset times.

Because the displayed offsets the averages of the morning and evening
offsets they may be a bit off backward or forward.

The program window displaying the Moon data looks like:

    +---------+    +---------+
    |moonrise |    |moonrise |
    |         |    |         |
    |(percent)| or |(time)   |
    |         |    |         |
    |moonset  |    |moonset  |
    +---------+    +---------+

wmSunMoon displays the Moon data related to the current day at the given
location rather than related to the lunar day.  The times of the moonrise
and moonset change during the entire Moon cycle so during some part of
the cycle the Moon rises and sets the same day and during the other part
of the cycle it rises one day and sets the other day.  As a result the
times of the moonset for a given day are sometimes later and sometimes
earlier than the times of the moonrise.

Because it is troublesome to determine the current state of the Moon the
program displays an appropriate indicator left to the Moon image.  The
arrow up means that the Moon is above the horizon (visible) while the
arrow down means that it is below the horizon (invisible).


Latitudes & Longitudes
-------------------------------------------------------------------------
The latitude and longitude values after dot have to be decimal.  So if
you take into consideration Paris coordinates: 48°51'N and 2°21'E you
should convert the minutes to the decimal values:

    51 / 60 = 0.85
    21 / 60 = 0.35

As a result the valid command for Paris, France is:

    wmSunMoon -lat 48.85 -lon -2.35

The above command works when you are in Paris or in the same time zone.
If you are in some other time zone follow the examples from the next
section.

Note that wmSunMoon uses POSIX standard so the longitudes used by it
have a reverse sign than in ISO 6709.


Examples
-------------------------------------------------------------------------
wmSunMoon -lat 40.72 -lon 74.00 -time

    Sun or Moon related data for New York, USA (40°43'N, 74°01'W) in
    local time -- that is when you are in New York or in the same time
    zone.  The additional switch forces displaying the current time in
    New York.

wmSunMoon -lat 40.72 -lon 74.00 -time -tzone Europe/Paris America/New_York

    The data for New York when you are in Paris or in CET/CEST time zone.

wmSunMoon -lat 48.85 -lon -2.35 -time -tzone America/New_York Europe/Paris

    The data for Paris when you are in New York or in EST/EDT time zone.

    When you use the time zone switch the program displays plus or minus
    sign next to the displayed hours when in the distant time zone there
    is the next or the previous day.  In such a case the times of the rise
    and set of the Sun and Moon are related to this future or past date.

wmSunMoon -lat 55.75 -lon -37.62 -rev -clean

    Reversed Sun or Moon related data for Moscow, Russia (55°45'N,
    37°37'E) when you are in the same time zone.  Reversing means that the
    program displays the Sun data during the night and the Moon data
    during the day.  The additional switch supresses displaying the arrow
    indicator on the Moon image.

wmSunMoon -lat -33.86 -lon -151.20 -twil -gold -perc

    Sun or Moon related data for Sydney, Australia (33°52'S, 151°12'E)
    when you are in the same time zone.  The additional switches force
    displaying the offsets for the civil twilight and golden hour and the
    percentage of the lunar cycle.

wmSunMoon -lat 48.85 -lon -2.35 -sun

    The Sun data for Paris.  This command emulates wmSun dockable
    application but you can still click the application window in order
    to display the Moon data.

wmSunMoon -lat 48.85 -lon -2.35 -moon

    The Moon data for Paris.  This command emulates wmMoonClock dockable
    application but you can still click the application window in order
    to display the Sun data.

wmSunMoon -lat 48.85 -lon -2.35 -twil -gold -perc -sun -moon

    If both Sun and Moon switches are used the program cycles the Sun and
    Moon data every two seconds.  In such a case clicking the dockapp
    window has no effect.

    The program without Sun and Moon switches displays the Sun data when
    there is a day in the given location or Moon data when there is a
    night.  If you use Sun and Moon switches the Sun view tells you which
    time of the day is in the given location:

        light blue sky with yellow Sun -- it is a day;

        orange sky with dark orange Sun -- it is a golden hour (morning
        or evening);

        gray blue sky without Sun -- it is a civil twilight (dawn or
        dusk);

        dark navy sky without Sun -- it is a night.

    The twilight emulation is seen only in the Sun/Moon mode.

wmSunMoon -lat -33.86 -lon -151.20 -tzone Europe/Warsaw Australia/Sydney -text

    The text mode switch forces displaying the complete data calculated by
    the program on the console.  It requires just the latitude and
    longitude parameters and the time zone data if necessary.

    The sample command displays the data as follows:

                           latitude: -33.860000
                          longitude: -151.200000

                    local time zone: CET    Europe/Warsaw
                  distant time zone: AEDT   Australia/Sydney

                         local time: 23:30
                         local date: 2015/03/19
                       distant time: 09:30      +
                       distant date: 2015/03/20 +
                     universal time: 22:30
                     universal date: 2015/03/19
                   time zone offset: -11.000000

              civil twilight begins: 06:32
                            sunrise: 06:57
           morning golden hour ends: 07:31
         evening golden hour begins: 18:34
                             sunset: 19:07
                civil twilight ends: 19:32

                 is it day or night: day
                  is it golden hour: it is not
                        is it today: tomorrow
              civil twilight offset: ±00:25
                 golden hour offset: ±00:33

               day and night length: 12:10 / 11:50

                   moon age in days: 29.39 days
                moon cycle fraction: 98.17% (98%)
                         moon phase: new moon
     illuminated moon disc fraction: 0.33%  (0%)
                    is moon visible: visible

               yesterday's moonrise: 05:14
                yesterday's moonset: 18:13
                   today's moonrise: 06:24
                    today's moonset: 18:56
                tomorrow's moonrise: 07:34
                 tomorrow's moonset: 19:39

            moon azimuth in degrees: -116.41°
           moon altitude in degrees: 35.84°
        moon distance in kilometers: 357187.05 km
             moon distance in miles: 221959.43 mi

           moon ascention in hhmmss: 23:29:41
        moon declination in degrees: -1°32'05"
     moon distance in earth's radii: 56.064520 Re


Notes
-------------------------------------------------------------------------
You can check the correctness of the calculated data using the following
website:

    http://www.timeanddate.com/worldclock/sunrise.html

    http://www.timeanddate.com/worldclock/moonrise.html

The slight differences between the data calculated by wmSunMoon and
www.timeanddate.com are caused by different alghoritms used in their
cases.

                                * * *

Instead of declaring the time zone names you can use the GMT offsets such
as GMT+12 or GMT-14.  They are useful if you would like to display the
time according to the military and nautical convention.  These zones are
named from Alpha to Zulu (A to Z).  The tz database supports only Zulu
time zone.

This setting may be also useful for the time zones which you are in trouble
to find in tz database.  For example Station Nord, Greenland (81°36'N,
16°14'W) uses GMT time without daylight savings.

Assuming that you are in Poland the right command for Station Nord might be
the following:

    wmSunMoon -lat 81.60 -lon 16.67 -tzone Europe/Warsaw GMT -text

In fact Station Nord uses the same time zone settings as
America/Danmarkshavn so the right command in its case is also:

    wmSunMoon -lat 81.60 -lon 16.67 -tzone Europe/Warsaw America/Danmarkshavn -text

You may find the right time zone for a given location using the zoneinfo
command or zoneinfo(7) manual page.

                                * * *

In the case of the latitudes near or behind the polar circles -- this
means over 65.725 or below -65.725 (over 65°43'30" N or S) -- the program
recognizes just the day and night ignoring the civil twilight and golden
hour effects though it still tries to calculate their times.  It
interprets also properly the polar day and night.

                                * * *

In order to display the information about the daylight savings use the
command such as:

    /usr/sbin/zdump -v -c 2015,2016 /usr/share/zoneinfo/Australia/Sydney

    Sat Apr  4 15:59:59 2015 UTC = Sun Apr  5 02:59:59 2015 AEDT isdst=1 gmtoff=39600
    Sat Apr  4 16:00:00 2015 UTC = Sun Apr  5 02:00:00 2015 AEST isdst=0 gmtoff=36000
    Sat Oct  3 15:59:59 2015 UTC = Sun Oct  4 01:59:59 2015 AEST isdst=0 gmtoff=36000
    Sat Oct  3 16:00:00 2015 UTC = Sun Oct  4 03:00:00 2015 AEDT isdst=1 gmtoff=39600

In the above example the parameter 2015,2016 is for the year 2015 and the
parameter Australia/Sydney selects the time zone.

Sunday, April 5, 2015 when the time in UTC changed from 15:59:59 to
16:00:00 the time in Sydney changes from 02:59:59 to 02:00:00 switching
from AEDT daylight savings time to AEST standard time.  Sunday, October
4, 2015 the time in Sydney switches back from AEST to AEDT.

The isdst parameter indicates whether the daylight savings time is in use.
Value 0 means that it is not used -- value 1 means that it is used.

The gmtoff parameter indicates the time offset related to GMT.  In order
to calculate the time zone offset in hours used by wmSunMoon using this
offset it is enough to divide it by -3600.

So the time zone offset for AEDT time is equal:

    39600 / -3600 = -11

while the time zone offset for AEST time is equal:

    36000 / -3600 = -10

If zdump displays just the data for 1901 and 2038 this means that in the
given time zone there is no daylight savings time at all.  In such a case
use the gmtoff parameter for 2038 to calculate the time offset.

                                * * *

In order to display the information about the current time, date, time
zone abbreviation and time zone offset in hours and minutes in the given
time zone use the following command:

    TZ="Australia/Sydney" date +"%H:%M %m-%d %Z %:z"

It displays the data such as:

    09:30 03-20 AEDT +11:00

The +11:00 offset above translates to the wmSunMoon time zone offset
equal -11.

As you see wmSunMoon uses POSIX standard so the time zone offsets used by
it have a reverse sign than in ISO 6709 used by tz database.


Files
-------------------------------------------------------------------------
COPYING    GNU General Public License Version 3.
ChangeLog  description of the changes.
INSTALL    installation instructions.
README     this file.
THANKS     my thanks to the other people.


License
-------------------------------------------------------------------------
wmSunMoon is provided on the terms of the GNU General Public License
v. 3.  Read the COPYING file for the complete text of the license.


Author
-------------------------------------------------------------------------
(C) 2014-2015 by Cezary M. Kruk <c.kruk@bigfoot.com>

wmSunMoon is based on the code of wmSun and wmMoonClock dockable
applications -- both written by Michael G. Henderson in 1999.

