WeekCalendar 1.22b

2005-11-07 by John Land


PURPOSE: Clock and Universal Gregorian Calendar

FEATURES:

• A Clock with 4 different time formats

• A Perpetual Calendar, with holidays (including major Easter and Advent based dates) and personal reminders;

• Calendar information with day of year and week of year information, plus personal reminder dates

• Date Calculators for performing up to 9 of each of these calculations:

• The date forward or backward from a specified number of days
• The number of days between two dates
• The number of days to go to a specified date

• Sun times and coordinates based on geographic location and time zone

• Moon times and coordinates based on geographic location and time zone

• Local time for up to 24 world locations in any time zone

• Alarms for up to 9 alarm clocks and countdown timers

• User-definable Settings for appearance and functional characteristics of WeekCalendar

 

This Help file also includes other information regarding accuracy of the Sun and Moon calculations and general definitions for solar, lunar, and time concepts.


GENERAL

A dot · after a label means a section is hidden or displayed, or the display format is changed, when you click on the label; also look for the cursor changing to a pointer or text edit form for interactive fields.

Below the Calendar are icons that show or hide several functions, described below.

Icon Toolbar



CLOCK

Click on the Clock display to change between am/pm, 24-hour, Internet Beat Time (Swatch Time), and UTC time displays.

Changes to the Clock display also affect the Alarm time displays (shown in am/pm or 24-hour formats only)


PERPETUAL CALENDAR

Click on the Calendar heading to collapse the Calendar to only a full date indicator and icon bar. Click again to restore the Calendar. The date format is the same as the month-name date format selected in the second row of the Calendar Date information section described below.

Click on the arrows below the Calendar heading to increment or decrement the date by 1 month (6 months by CTRL-clicking), 1 year (5 years by CTRL-clicking), or 10 years (100 years by CTRL-clicking).

Click on the º symbol below the Calendar heading to return to today's date.

Click on the row of day names to toggle between a Sunday or Monday start of week.

Today's date is shown with a blue background and a bold, black date number. Clicking on a date shows the date with a yellow background and a bold, black date number.

Holidays are shown with a green background and red dates. Personal reminder dates (see below) are shown with a pinkish background and red dates. These background and foreground colors override the blue background and black text of today's date if today is a holiday or reminder date (but the date number is still bold in such a case). Hover over a marked holiday or personal reminder date to pop up a tooltip identifying the holiday or showing your reminder.

The colors can be manually changed by editing the CONFIG.JS file.

The Calendar date range is January 1, 1583 (first full Gregorian year) onward; however, Sun and Moon times are not computed beyond 3000, as the algorithms may not be accurate due to global precession.


CALENDAR DATE & REMINDER INFORMATION – Calendar Icon

This function displays the following information for the selected date (which is the current date if you do not select another date):

• Numeric date (click to change format between yyyy-mm-dd and dd-mm-yyyy).

• Named month date (click to change format between dd-FullMonthName-yyyy; dd-ShortMonthName-yyyy; FullMonthName-dd, yyyy; and ShortMonthName-dd, yyyy).

• Day of week with ISO day number (Monday = 1).

• Week of the year (with weeks remaining) (calculations are based on ISO8601: 1st Thursday of year defines the 1st week; some years have 53 weeks).

• Common holidays based on Christian Movable Feasts (Easter, Advent, etc.).

• A text entry field that identifies a selected holiday or personal reminder date.

You can select and copy the text of any of these displayed items.

Personal Reminders: To enter a personal reminder for a selected date, first type text into the pinkish text entry field and then check the checkbox next to it. To clear a personal reminder that has already been entered for a date, click on that date and clear the checkbox (if you enter a personal reminder on a holiday, the holiday is not affected).


DATE CALCULATORS – Calculator Icon

The Date Calculators include 3 types of computations:

• The date forward or backward from a specified number of days (e.g., the date 45 days from today);
• The number of days between two dates;
• The number of days to go to a specified date (e.g., the number of days from today until Halloween).

For the Add To/Subtract From function, enter the number of days to add or subtract from the currently selected date, and select the arithmetic operation (plus or minus) using the dropdown selection list. The answer is shown at the right side.

For the Days Between Dates function, use the Calendar to pick a date, then click on the checkbox next to a Days between Dates field to fill in the selected date. The difference between two selected dates is shown at the right side. Clear a date by unchecking the adjacent box.

For the Days to Date function, use the Calendar to pick a date, then click on the checkbox next to a Days to Date field to fill in the selected date. The days to go to that checked date, counted from the currently selected date, is shown at the right side. The answer can be negative if the currently selected date is after the checked date. Clear a date by unchecking the adjacent box.

In all cases, your selections will be saved between sessions.

For all calculators, the date format is the same as the numeric date selected in the first row of the Calendar Date information section described above (either yyyy-mm-dd or dd-mm-yyyy).

You can hide or show any of the 3 calculator sections by clicking on the section heading.

You can define how many rows or row pairs, from 1 to 9, are displayed in each calculator section (see Setup below to change the number of rows).


SUN TIMES & COORDINATES – Sun Icon

Simple or Complete Formats: Sun times and position information are shown in 2 formats: simple and complete. Click on "Sun Information" to toggle between the two formats.

For accurate information, you must set your geographic location (latitude & longitude) and time zone (with Daylight Saving Time or Summer Time status indicated). See Setting Location below.

The complete display shows 16 items; the simple display shows only the 4 marked with a red bullet:

• Morning twilight times (astronomical, nautical, civil; see definitions below)


• Sunrise time and azimuth (angular position from due North = 0°) at that time


• Solar noon (the time when the sun crosses the meridian of the observer's location)


• Sunset time and azimuth (angular position from due North = 0°) at that time


• Duration of the day (sunrise to sunset)


• Equation of time (an astronomical term accounting for changes in the time of solar noon for a given location over the course of a year)


• Right ascension (the angular offset from the meridian of the vernal equinox)


• Declination (the angular displacement north or south from the projection of Earth's equator on the celestial sphere to the location of the Sun)


• Elevation (measured vertically from the horizon up to the Sun at the azimuth location of the Sun; also called Altitude)


• Azimuth (measured clockwise from true north to the point on the horizon directly below the Sun)


• Distance to the Sun (given in Astronomical Units, AU, which is the mean (average) distance from Earth to the Sun, approximately 92,957,210 miles)

 
• Evening twilight times (astronomical, nautical, civil; see definitions below)

 

The Sun moves a measurable amount every few seconds; click on the "Values as of [time]" label at the bottom of the Complete Sun information format to update the position information. All Sun calculations auto-update once per minute. If you want to know position information for a specific time, use the Clock Override function of the Set Location table described below.

Three twilight times are given for both morning and evening; see below for definitions.


MOON TIMES & COORDINATES – Moon Icon

Simple or Complete Formats: Moon times and position information are shown in 2 formats: simple and complete. Click on "Moon Information" to toggle between the two formats.

For accurate information, you must set your geographic location (latitude & longitude) and time zone (with Daylight Saving Time or Summer Time status indicated). See Setting Location below.

The complete display shows 9 items; the simple display shows only the 4 marked with a red bullet:


• Moonrise time and azimuth (angular position from due North = 0°) at that time


• Moonset time and azimuth (angular position from due North = 0°) at that time


• Phase, in degrees


• Percent of Moon illuminated


• Right ascension (the angular offset from the meridian of the vernal equinox)


• Declination (the angular displacement north or south from the projection of Earth's equator on the celestial sphere to the location of the Moon)


• Elevation (measured vertically from the horizon up to the Moon at the azimuth location of the Moon; also called Altitude)


• Azimuth (measured clockwise from true north to the point on the horizon directly below the Moon)


• Distance to the Moon in kilometers
 

The Phase of the Moon is shown with actual photographs next to the "Moon Information" title (see Accuracy note below):
• 0°/360° = full moon
• 90°       = waxing quarter moon
• 180°     = new moon
• 270°     = waning quarter moon

The Moon moves a measurable amount every few seconds; click on the "Values as of [time]" label at the bottom of the Complete Moon information format to update the position information. All Moon calculations auto-update once per minute. If you want to know position information for a specific time, use the Clock Override function of the Set Location table described below.

Note that the day ends at midnight, and hence it is normal for Moonset to be BEFORE Moonrise for a particular day (for example, if the Moon sets at 11:30 am, it will have risen some time the day before; similarly, if the Moon rises at 9:00 pm, it will set after midnight, and thus in the next day).


GLOBAL TIME ZONES – Clock Icon

You can set Time Zone information for up to 24 locations (see Setup below to change the number of rows). Click on the Time Zone Information label to display dropdown lists for over 4200 locations, by Country and City. Click on the Time Zone Information label again to hide the dropdown lists.

Select a Country, then a City, and put a checkmark in the Set checkbox in the lower table to see the local time and date for the selected location. Click on the Time label to change the time format between am/pm and 24-hour. Times are updated once per minute.

If a location is on Daylight Saving Time (Summer Time), put a checkmark in the corresponding DST checkbox to adjust the local time.

Each location includes latitude and longitude coordinates. If you click on the Time field for a defined location, the corresponding coordinates are loaded into the Set Locations fields, thus allowing you to see Sun and Moon rise, set, and position information for that location. The selected Location time will be yellow-highlighted to remind you of your selection. Click on the Load button of the Set Locations table to restore your default location and clear the highlighting in the Time Zone Information section.

You can define a custom location by selecting "Custom Coordinates" in the Country dropdown list. Then do 3 things:
• define the coordinates and time zone in the Set Locations table;
• enter the name of the location in a blank Location field in the Time Zone Information table; and
• click the Set checkbox next to the new Location.

If you forget to enter a location name before clicking on Set, clear the Set checkbox, enter the location name, and click on Set again.

Your last selected Country and City are saved and reloaded for each browser session. Because of the number of cities (606) under the United States, leaving Country on "United States" may cause slow initial loading of WeekCalendar.

The city coordinate information was derived from several sources on the Internet, so I can't vouch for their accuracy.
 


SETTING LOCATION

In the Set Location table, latitude (Lat) and longitude (Long) are set using conventional Degrees, Minutes of arc, and Seconds of arc. "Dir" stands for direction, North or South for latitude, and West or East for longitude. You can click on the Globe icon for a link to a site that may help you find your local coordinates.

The Time Zone is the number of hours away from UTC (formerly GMT). Countries West of UTC are minus numbers (e.g., France is +1 offset from UTC; California is -8 hours). Most people can leave the Adjustment to the Time Zone at zero. This only applies to a few countries that use added 1/2 hour or (I think only 3 cases) 3/4 hour offsets to adjust local time to local sunrises. A 1/4 hour adjustment is available, but I know of no country that uses that amount. Click on the Time Zone label to link to a map that shows world time zones.

DST means "Daylight Savings Time" (sometimes called "Summer Time"), which changes the local time 1 hour in Summer. Many countries do not observe this practice. The exact day and time that DST starts and ends is a matter of national (and sometimes local) law.

You can click on "Use local time offset" to quickly set the offset to the value maintained in YOUR computer. Since this takes Daylight Savings Time into account automatically, the DST field is set to "No".

Remember to click on Save Settings when you have your desired location set. However, once you save your settings, you can enter the coordinates and time zone of other places to see what their Sun and Moon times are; just don't click on Save Settings again.

Saved settings can be reloaded by clicking on Load Settings.

You can also load coordinates and time zone settings for locations selected under the Time Zone Information function described below by clicking on Time field for a particular location; the field will be yellow highlighted, and the corresponding coordinates and time zone settings will be displayed in the Set Location fields. This gives you an easy way to check out Sun and Moon rise and set times for different locations around the world.

Below the coordinate and time zone fields is a Locale Time that shows the local time for a specific locale, defined by geographic coordinates and time zone.

Clock Override: If you click on the Local Time label, and click on the "Clock Override" checkbox, you can set a specific time (in 24 hour format) at which to calculate Sun and Moon positions. For example, if you want to know the Phase of the Moon at a specific time, use the Clock Override function to set that time.

Clicking on the Locale Time label again, or on the Clock Override label, will hide the Clock Override section hide IF the checkbox is clear.


ALARM CLOCKS & COUNTERS – Alarm Bell Icon

You can set up to 9 alarms, either as a specific time or a relative time (elapsed time countdown) (see Setup below to change the number of rows).

Click on the Alarm Timers label to display the Alarm Setup table; click on the Alarm Timers label again, or on the Alarm Setup label to hide the Alarm Setup table.

Once an alarm is set but isn't ringing, clicking on the Alarm Time field will display the settings for that alarm in the Alarm Setup section, making it easy to change part of a previously defined alarm.

Setting an Alarm: To set an alarm based on a specific time, in the Alarm Setup section, enter the hour (24-hour format) and minute that the alarm is to ring into the Alarm Time fields.

You can pick an Alarm Sound (click the green arrow to play the alarm sound, and the red square to stop the alarm sound); you can select "None" if you do not want an alarm sound.

You can include an Alarm Message which will pop up as an alert when the alarm rings (you will not get a pop up if no message is entered).

You can set a Snooze Delay for the alarm by setting the number of hours and minutes to delay if an alarm rings and you hit "snooze" (discussed below).

Once you set the time, alarm sound, and any message, click on the Set checkbox in the Alarm Timers table to set that alarm. An alarm clock icon will appear under Type; if you set a Snooze Delay time, a recycle icon will also appear under Type. Click on either icon to see a pop up alert that shows the snooze delay time, the selected alarm sound, and any message for that alarm.

Setting an alarm automatically turns that alarm on, as indicated by a check in the On/Off checkbox. The alarm time is displayed in the Alarm Time field; the format is controlled by the Clock format (am/pm or 24-hour are the only two options).

The state of each alarm is checked against the Clock once per minute. Once an alarm rings, any specified message will pop up, the selected alarm sound (if any) will be played, and the Alarm Time field will be yellow highlighted. If you click on the yellow-highlighted alarm time, the alarm will snooze for the corresponding Snooze Delay time (computed from when you hit "snooze"), then ring again (the yellow highlighting is turned off while snoozing). You can turn the alarm off by clearing the corresponding On/Off checkbox.

To delete an alarm entry, clear the Set checkbox.

Alarm times and on/off state are saved between browser sessions, and restored when the browser next starts.

Remember, alarms can only work while the browser and this plugin are running!

Setting a Counter: To set a counter to ring an alarm after a specific time has elapsed (like a 3 minute egg timer), in the Alarm Setup section, enter the hour (24-hour format) and minute that the countdown alarm is to ring in the Alarm Time fields and set the "Check for Counter" checkbox.

You can pick an Alarm Sound or select "None".

You can include an Alarm Message which will pop up as an alert when the countdown alarm rings (you will not get a pop up if no message is entered).

You can set a Snooze Delay by setting the number of hours and minutes to delay if a countdown alarm rings and you hit "snooze" (discussed below). If no Snooze Delay is set, the Snooze Delay defaults to the countdown time.

Once you set the time, alarm sound, and any message, click on the Set checkbox in the Alarm Timers table to set that countdown alarm. An hourglass icon will appear under Type, and a recycle icon (since all countdown alarms reset themselves to their initial countdown time if you hit "snooze" and no other Snooze Delay time is set). Click on either icon to see a pop up alert that shows the snooze delay time, the selected alarm sound, and any message for that alarm.

Setting an alarm automatically turns that alarm on, as indicated by a check in the On/Off checkbox. The countdown alarm time is displayed in the Alarm Time field in hours and minutes; the format is not changed by changes to the Clock format.

The state of each countdown alarm is checked against the Clock once per minute. Each countdown alarm also delays from ringing for a residual time offset of 0-59 seconds (the exact value depends on when the alarm was actually set) in order to increase accuracy to about 1 second (this is an improvement over other known Maxthon countdown timers, which can be off by as much as 59 seconds). The display changes from "0:0" to "0:0:ss" where "ss" is the number of residual seconds that are counted down before the alarm rings; this value counts down to the nearest 5 second time, then by 5 seconds until it reaches zero, at which time the alarm rings..

Once a countdown alarm rings, any specified message will pop up, the selected alarm sound (if any) will be played, and the Alarm Time field will be yellow highlighted. If you click on the yellow-highlighted alarm time, the countdown alarm will snooze for the corresponding Snooze Delay time (which is the default countdown time if no Snooze Delay is specifically set; the snooze time is computed from when you hit "snooze"), then ring again (the yellow highlighting is turned off while snoozing). The new countdown time is displayed in the Alarm Time field.

You can turn the countdown alarm off by clearing the corresponding On/Off checkbox.

To delete a countdown alarm entry, clear the Set checkbox.

Countdown alarm times and on/off state are saved between browser sessions, BUT all countdown alarms are reset to their initially specified time at browser startup. Using the Setup function also resets all countdown alarms to their specified start time.

Remember, countdown alarms can only work while the browser and this plugin are running!


SETUP – Tool Icon

The user can set the following items:

• Date Calculator: The number of date arithmetic rows (1-9)

• Date Calculator: The number of date difference row pairs (1-9)

• Date Calculator: The number of date countdown rows (1-9)

• Alarm: The number of alarm rows (1-9)

• Time Zones: The number of time zone rows (1-24)

• Help Style: choose from a tabbed window or a popup window

• Background color: Click to select the background color for WeekCalendar, using the standard Windows color picker


HELP – Question Mark Icon

Pops up this Help page.



OTHER INFORMATION

Accuracy of Sun and Moon calculations:

The algorithms for Sun calculations are from the National Oceanic and Atmospheric Administration (NOAA). According to NOAA, for latitudes between ±72°, accuracy is approximately one minute. For latitudes greater than 72° N or S, calculations are accurate to within 10 minutes. For locations above the Arctic Circle and below the Antarctic Circle, when a sunrise or sunset does not occur on the given day, the program locates the local time and date of the most recent sunrise or sunset, and the next sunset or sunrise. When this occurs, the UTC output fields will display "prior" or "next" information instead of the UTC times.

The algorithms for Moon calculations were derived from work done by Peter Hayes; see his embodiment here. When compared to the U.S. Naval Observatory, accuracy is within about one minute.

Note that these are theoretical accuracies based on ideal conditions (e.g., a clear sky at sea). The times of rise and set phenomena cannot be precisely computed, because, in practice, the actual times depend on unpredictable atmospheric conditions that affect the amount of refraction at the horizon. Local topography (e.g., mountains on the horizon) and the height of the observer also affect the times of rise or set even more. It is not practical to attempt to include such effects in routine rise/set computations.

The accuracy of rise and set computations decreases at high latitudes. There, small variations in atmospheric refraction can change the time of rise or set by many minutes, since the Sun and Moon intersect the horizon at a very shallow angle. For the same reason, at high latitudes, the effects of observer height and local topography are magnified and can substantially change the times of the phenomena actually observed, or even whether the phenomena are observed to occur at all.

Also note that the Moon has a 29.53 day cycle. There are 29 images that depict the phase of the Moon, so the image may be off within one month by as much as half a day. However, the numeric Phase information should be accurate to within less than one degree.


Definitions of some Sky Time & Position Terms:

Derived from the NOAA website.

Apparent sunrise/sunset - due to atmospheric refraction, sunrise occurs shortly before the sun crosses above the horizon. Light from the sun is bent, or refracted, as it enters earth's atmosphere. This effect causes the apparent sunrise to be earlier than the actual sunrise. Similarly, apparent sunset occurs slightly later than actual sunset. The sunrise and sunset times reported in this calculator have been corrected for the approximate effects of atmospheric refraction. However, it should be noted that due to changes in air pressure, relative humidity, and other quantities, the exact effects of atmospheric refraction on sunrise and sunset time are not predictable. Also note that this possible error increases with higher (closer to the poles) latitudes. See also this NOAA explanation.

Civil twilight - defined to begin in the morning, and to end in the evening when the center of the Sun is geometrically 6° below the horizon. This is the limit at which twilight illumination is sufficient, under good weather conditions, for terrestrial objects to be clearly distinguished; at the beginning of morning civil twilight, or end of evening civil twilight, the horizon is clearly defined and the brightest stars are visible under good atmospheric conditions in the absence of moonlight or other illumination.

Nautical twilight - defined to begin in the morning, and to end in the evening, when the center of the sun is geometrically 12° below the horizon. At the beginning or end of nautical twilight, under good atmospheric conditions and in the absence of other illumination, general outlines of ground objects may be distinguishable, but detailed outdoor operations are not possible, the horizon is indistinct, and artificial illumination is normally required to carry on ordinary outdoor activities.

Astronomical twilight - defined to begin in the morning, and to end in the evening when the center of the Sun is geometrically 18° below the horizon. Before the beginning of astronomical twilight in the morning and after the end of astronomical twilight in the evening the Sun does not contribute to sky illumination; for a considerable interval after the beginning of morning twilight and before the end of evening twilight, sky illumination is so faint that it is practically imperceptible.

Latitude - an angular measurement of north-south location on Earth's surface. Latitude ranges from 90° south (at the south pole), through 0° (all along the equator), to 90° north (at the north pole).

Longitude - an angular measurement of east-west location on Earth's surface. Longitude is defined from the prime meridian, which passes through Greenwich, England. The international date line is defined around ± 180° longitude (180° east longitude is the same as 180° west longitude, because there are 360° in a circle.)

Universal Time Coordinated - replaced GMT as the world reference for time. UTC is based on atomic clock time, with leap seconds added when necessary to match earth-motion time. Many data sets collected around the world are recorded with a UTC time stamp to avoid the confusion associated with time zones and daylight saving time.

Daylight Saving Time - also known as "Summer Time". Many countries have instituted a clock change over the summer months to save energy. By moving sunset closer to the time when most people go to bed, an hour's worth of electricity for lighting can be conserved.

Equation of time - an astronomical term accounting for changes in the time of solar noon for a given location over the course of a year. Earth's elliptical orbit and Kepler's law of equal areas in equal times are the culprits behind this phenomenon. See this plot of the equation of time vs. day of the year. For more information on this "analemma" phenomenon, see here.

Solar noon - defined for a given day for a specific longitude, it is the time when the sun crosses the meridian of the observer's location. At solar noon, a shadow cast by a vertical pole will point either directly north or directly south, depending on the observer's latitude and the time of year.

Solar declination - the declination of the sun. The solar declination varies from -23.44° at the (northern hemisphere) winter solstice, through 0° at the vernal equinox, to +23.44° at the summer solstice. The variation in solar declination is the astronomical description of the sun going south (in the northern hemisphere) for the winter. This Solar Declination Graph shows how the solar declination varies over the year. See this Solar Paths Figure showing the seasonal solar paths projected on the celestial sphere.

Solar right ascension - along with declination, a means of defining the position of objects in space, referred to a known point. Similar to the angular system used to define latitude and longitude on Earth's surface, right ascension is roughly analogous to longitude, and defines an angular offset from the meridian of the vernal equinox.

Azimuth and Elevation - an angular coordinate system for locating positions in the sky. Azimuth is measured clockwise from true north to the point on the horizon directly below the object. Elevation is measured vertically from that point on the horizon up to the object. If you know the azimuth of a constellation is 135° from north, and the elevation is 30°, you can look toward the southeast, about a third of the way up from the horizon to locate that constellation. Because our planet rotates, azimuth and elevation numbers for stars and planets are constantly changing with time and with the observer's location on earth.

For definitions of other terms, see the NOAA Glossary.

–o0o–