WMSUNMOON(1)

NAME
WMSUNMOON - dockable Window Maker Sun, Moon, time, and time zone application

SYNOPSIS
wmSunMoon [-lat <latitude>] [-lon <longitude>] [-tzone <local distant>] [-time] [-twil] [-gold] [-perc] [-clean] [-sun] [-moon] [-rev] [-mono] [-text] [-h]

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

OPTIONS

-lat <latitude>
    Set the latitude of the observer. Positive for the northern hemisphere, negative for the southern hemisphere.

-lon <longitude>
    Set the longitude of the observer. Positive west of Greenwich, negative east of Greenwich.

-tzone <local distant>
    Set the local and distant time zones. Use the names according to the format used by tz database.

-time
    Display the current time.

    This switch used with the time zone switch displays the time in the distant time zone.

-twil
    Display the civil twilight offset.

-gold
    Display the golden hour offset.

-perc
    Display the percentage of the lunar cycle.

-clean
    Supress displaying the arrow indicator on the Moon image.

-sun
    Force displaying the Sun.

-moon
    Force displaying the Moon.

-rev
    Reverse the display from Sun to Moon or vice versa.

-mono
    Use the monochrome images.

-text
    Display the complete data calculated by the program on the console.

-h  Display the list of the command-line options.

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

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

SEE ALSO
zoneinfo(7).