Earth&Sun Application for Ewe

Earth&Sun Application for Ewe
Version 1.0^*

Description

Earth&Sun is an application for Ewe enabled computers to show the Sun Illuminated area of the Earth, and time and distance information.

To use this version of Earth&Sun you must install a Ewe¹ VM (Virtual Machine) on your computer. Ewe is a version of Java which runs on a variety of desktop and handheld computers. It is very compact and efficient. It uses only about 2 Mbytes of memory.
To learn more about Ewe please read the introduction on the Bray Mobile Applications page.

Earth&Sun is an application that shows a map of the Earth with Sun illumination and it will also display:

The latitude and longitude of an Earth location.
The time zone at that location, based on only longitude not civil boundaries.
The current time at that location based on the above time zone.
The sunrise, sunset times, and day length at that location.
The great circle distance between to locations on the earth.

Because of time zone irregularities some will consider Earth&Sun to fall into the category of "fun and games". If you are not familiar time zones see About Time Zones.

We hope you find Earth&Sun useful and enjoy it.

About This Documentation

Earth&Sun is intuitive and easy to use. This documentation probably seems large, but you really should read it to fully understand all of the features.
For a Quick Start read Installation. Then after trying it out please return to this documentation to learn all of the features. Sections:

Installation (Must Read)
Using the Program
Controls -- Top Buttons
Controls -- Bottom Buttons
Time Mode
Distance Mode
Menus Instructions
More Details
Alternate Maps
Contact Info
Foot Notes
Version Changes

Installation

Since you are reading this documentation, you have found that you have two .zip archives in earthsun10.zip. The earthsun10Install.zip archive contains the files to be installed on your computer. The earthsun10Doc.zip contains this documentation you are now reading.

The first thing to do is to install the Ewe VM on your computer(s), if not already installed. Follow the instruction found on the Ewe Download and Installation Page for your computer. The Ewe installer will create directories on your computer and put the Ewe VM files in them. After Ewe is installed find the Ewe directory. For example, in a Windows Desktop it will be where you told the installer to install it, and in the Pocket PC it will (probably) be in /Windows/StartMenu/Programs/Ewe.

There is no installer for Earth&Sun.ewe. The files in the earthsun10Install.zip archive can be put in any directory of your choice. However it is recommended that you put them in the directory with the Ewe VM. Specifically the directory in which you find 'ewe.ewe'. This will make it easier to find them if you want to change them, and when you add additional applications from Bray Mobile Applications common files can be shared.

Once you find the proper directory copy all of the files in earthsun10Install.zip into that directory, in what ever manner you do that on your computer.

Note: No matter what Regional settings are used on your computer(s), Earth&Sun always uses the '.' (period) as the decimal point, the ':' (colon) as the hour/minute/second separator, and the ',' (comma) as the data separator.

Earth&Sun should be ready to run now. Find Earth&Sun.ewe with your File Explorer, click on it to try it out!

Using the Program

The shaded area is that part of the world that is dark at the current time. The location where the Sun is directly overhead is shown by a little yellow Sun icon. It is located near the equator in Africa in the image at the top right.

Upon your first view of the Earth&Sun map you will note that the Sun's location and Night Shading is not correct. This is because Earth&Sun does not know the time zone to which your computer's clock is set. It thinks it is set to Greenwich Mean time. After learning about the display and its controls, instructions on setting the time zone correctly are given.

Hopefully program usage is pretty much self evident once you understand the instructions documented next.

This documentation starts by describing the control buttons

Controls -- Top Buttons

Refer to the top row of buttons from left to right:

Menus This will pop-up the Earth&Sun menus. Detailed menu instructions are discussed below in the section: Menus Instructions below.
Date Selector This allows selection of a new date. It is an interactive date selector. Use the CHECK to accept and X to cancel.

Controls -- Bottom Buttons

Refer to the bottom row of buttons from left to right:

1x This toggles the map between 1x, 2x and 4x magnification. Use your pen to drag the map to an area of interest.
Now This updates the map to the current time, but does not change the date.
Mode This toggles the Earth&Sun mode between Time and Distance.
STD/DLT Pressing this button switches any tapped location's time between Standard and Daylight time. This applies to all locations tapped.
NTZ/FTZ This changes the tapped location time zone between Normal and Frozen. This is somewhat complicated. Changing it to the Freeze mode can give unexpected results. See discussion on NTZ/FTZ -- Normal/Freeze Time Zone Button.

Next the documentation discusses the Earth&Sun modes.

Earth&Sun has two modes of operation: Time Mode, and Distance Mode. Initially it is in the Time Mode. The mode is changed by tapping the Mode button in the bottom center of the display.

Time Mode

The Mode button changes Earth&Sun's mode between Time and Distance.

Refer to the first and second rows of the text display area from left to right.
For a tapped location:

Time is its current time. This is based solely on the time zone displayed next.
Zone is its time zone based solely on its longitude, not on civil boundaries.
Lat is its latitude.
Rise is its sunrise time. See discussion on sunrise/sunset time values.
Set is its sunset time. For latitudes near the poles, it is possible that the Sun does not rise or set.
In that case the rise/set time will be displayed as: 0:00.
Length is the length of the day.

Looking at the third row of the text display from left to right:

Clock: is the computer's clock time zone which is set with the /Menus/Home/TZ/. If you did not set it do it now before you forget. See Set Home Time Zone Instructions. Failure to do so makes the entire display of Earth&Sun invalid.
Long: is the tapped location's longitude.

Distance Mode

The Mode button changes Earth&Sun's mode between Time and Distance.

In the Distance mode the text display area changes as shown on the right.
Tap a location on the map. For the tapped location:

Loc is either F or T. From button in the bottom row puts the tapped location data in the second display row. From* indicates that it is activated.
To button puts the tapped location data in the third display row. (To the right it is seen to be active by the '*'.)
Lat is the latitude of the tapped location.
Long is its longitude.
Mi is the distance in miles between Loc F to Loc T.
Nmi is the distance in nautical miles.
Km is the distance in kilometers.
Bearing: is the great circle bearing from Loc F to Loc T.

Menus Instructions

Each time the map is tapped, data is put into the active row and change the distance and bearing to reflect the new location. When you tap Menus in the upper left of the display, the menu shown ton the right will pop-up.

Reference is a location for which you would frequently like to find the sunrise and sunset -- your home for example.
- Reference/Show tapping this displays the current time/rise/set information for the reference location set by Set This discussed next.
- Reference/Set This sets the Reference until changed. To set a Reference do:
  1. Change the map to 4x, and move it to show the map near your reference location.
  2. Tap on the desired location. Check to see if it is correct.
    If not continue tapping until is.
  3. Tap Menus/Reference/Set This.
There is additional ways to display the reference data.
--- Tap above or below the data line displaying: time/zone/lat...
This works in either the Time or Distance modes.

Home Set has two sub-menus:
- Home Set/Daylight Time This menu item will ask you to give the setting for the computer's clock: Is Home Time on Daylight Time?
  Be sure to change this whenever you change the computers time.
- Home Set/Time Zone This menu sets the currently displayed time zone to be that of the Home time. This must be set to put the night shadow in the correct position on the map.
When traveling with your handheld computer be sure to set both of these menu items when you change time zones.
About This is the usual About information. It tells you the version of Earth&Sun you have installed. Use this to see if your installed version of Earth&Sun is up-to-date.
Quit This is the obvious Quit selection. You can also Quit using the upper right hand X. In either case you will asked if you with to save the current settings of Earth&Sun for next usage start-up.

Back to the Top Button discussion.

More Details

Set Home Time Zone Instructions

You must do is to tell Earth&Sun where you are located. More accurately -- the time zone to which your computer clock is set. If you do not set this the Time, Sun's location, and Night Shading will be inaccurate.

To do this:

Tap the map at your approximate location. This will display the latitude, longitude and the time zone at the tap location. An example of this is seen in the map above. The latitude is 44.6n (44.6 degrees North), longitude is 75.00w and the time zone is 5w. if the time zone is not correct continue tapping until it is.
When you have the time zone correct, tap the Menus button int the upper left. Then tap the open menu Home Set/Time Zone.
Then complete this setting by tapping Menus again, then Home Set/Daylight Time and answering the question.

Back to the Time Mode discussion.

Sunrise/Sunset Time Values

You may find that the sunrise and sunset times may be different in the 1X, 2X and 4X modes. The reason for two different calculation is a matter of accuracy of pen positioning. On the 1X display it is difficult to locate a particular latitude/longitude.

The sunrise/subset times are accurate for the displayed latitude/longitude. See for discussion on the NTZ/FTZ Button which follows. This gives an example of different times at different longitudes.

Back to the Time Mode discussion.

NTZ/FTZ -- Normal/Freeze Time Zone Button

Since the time zone is based solely on longitude the NTZ/FTZ (Normal/Freeze Time Zone) button allows you to freeze a time zone so that in the you can find sunrise/sunset times for locations which do not follow normal time zone rules. For example: Alaska extends over 4 time zones, Russia and China extend over 3 times zones. Also there are locations like western Texas where the time zone boundary is very much west of where it should be.

To use this feature put the pen down on a location which is in the desired time zone. For example: Alaska time is 9w, so tap the map on eastern Alaska and verify that the time zone is 9w. Then observe the sunrise/sunset times. Next tap the NTZ button. It will change to FTZ (Freeze Time Zone)^*. Then tap the western part of Alaska and the sunrise/sunset time should be about 2 hours later. Now tap the far western Aleutians Islands and see the sunrise/sunset advance another hour. Note that the time zone still reads 9w.

With a frozen time zone it is possible that the sunset could occur in the next morning. In this case the time might be, e.g. 24:10. The same is true for sunrise except it might occur the previous night, with a sunrise e.g. of 23:45. Note: In these cases the date does not change.

^*Because this button can cause large inaccuracies, a warning is popped up to be sure you really want to change to the Freeze Time Zone mode.

Back to the Bottom Button discussion.

About Time Zones

If you are not familiar with world time zones this should help.
Time zones are defined to indicate number of hours local clocks differ from that of Greenwich Observatory in England.
Examples of world wide time zones are in the table below. Local clocks (time zones) to the East are later in time than a clock in Greenwich England, thus of course, those to the West are earlier.

United States		Around the World
Time Zones	Offset	Time Zones	Offset
Eastern	5 West	British Isles	0 East
Central	6 West	Western Europe	1 East
Mountain	7 West	Eastern Europe	2 East
Pacific	8 West	MidEast	2 East
Alaska	9 West	So. Africa	2 East
Hawaii	10 West	Russia	3 East
		Japan	9 East
		South Australia	9.5 East
		Eastern Australia	10 East

Alternate Maps

The maps distrubuted with Earth&Sun have low altitude land shown in green varing to high altitude land shown in red, as seen above. Alternate maps with low altitude land shown in green varing to high altitude land shown in brown and with lighter ocean blue, as shown to the right, can be downloaded at: Alternate Earth&Sun Maps.

Install the alternate maps by simply replacing the current ones in the directory containing Earth&Sun.ewe.

Contact Info

The Bray Palm OS Page can be found at: http://www.40-below.com/palm/

Registering

Earth&Sun is freeware -- no registration is required. We hope you enjoy using it.
I would appreciate receiving e-mail about what computer(s) you are using Earth&Sun on, and any other feedback and suggestions you would like to share with me.

This archive may be freely redistributed, provided it is made available only in its complete, unmodified form with no additional files and for noncommercial purposes only. Any other use must have prior written authorization from David W. Bray at bray@davidbray.org.

Unauthorized commercial use includes, but is not limited to:

Earth&Sun itself as a product for sale.
Accompanying a product for sale.
Accompanying a magazine, book or other publication for sale.
Distribution with 'Media', 'Copying' or other incidental costs.
Available for download with access or download fees.

Disclaimer

This program is provided without warranty and the user accepts full responsibility for any damages, consequential or otherwise, resulting from its use.

Foot Notes

¹ Ewe is developed by Michael L Brereton. We are indebted to him for his outstanding software product and making it freely available. Thank you Michael!

^*Changes in Version 1.0

Earth&Sun Version 1.0 Bld: 439 differs from Version 1.0 Bld:418 in:

Original release -- Version 1.0 Bld:418
Improved menus. (V1.0 Bld:422)
Changed the decimal point to always be '.' (period). (V1.0 Bld:439)

Bld: 439 is the current release.

To be sure that your version is up-to-date check the Bld: number in the current description of Earth&Sun at: http://davidbray.org/mobile/