Planetarium for the Palm Computing Platform Version 1.9
=======================================================

You can find more detailed and illustrated 
information at
http://www.aho.ch/pilotplanets
There you can also download the latest release.

Introduction
------------
  This program calculates the position of the Sun, the 
Moon, all the planets and some of the brightest stars 
in the sky for any time and a any geographical position. 
Star gazers can use it to find or identify the planets 
in a clear nighttime sky. It can also be used as a 
compass when the Sun or Moon is visible. 

OS Version
----------
  Planetarium runs on PalmOS version 2 and higher.
It runs on all Palm Models except for the Palm 1000 
and 5000 models.

Installation
------------
There are three files which can be installed onto
the Palm:
 - planet19.prc - the executable application
 - PlanetariumDB.pdb - A list of major cities
 - UserObjsDB.pdb - Messier and Caldwell catalog

Please note: The files PlanetariumDB.pdb
and UserObjsDB.pdb are installable optionally.
If you don't need the locations or the objects
and would like to save some memory, just omit 
these files. They can also be installed later,
but will overwrite personal entries.
If you already have entered personal objects,
and wish to install one of the files, make sure 
you export your personal entries to the Memo 
beforehand so you can reimport them again afterwards. 
(Use the menu item "Export". This will create a 
Memo containing all the locations or objects. 
You can reimport this list with the menu item 
"Import".)

Accuracy
--------
  The accuracy is 0.1 resp. 5' for all angles shown
concering planets, 1' concerning stars, and 1 min 
for all times shown over the whole date range of the 
Palm (1904 to 2031) with the only exception 
that the azimuth value is less accurate if the altitude 
is higher than 60 (and eventially becomes meaningless 
if the altitude is exact 90).

Display
-------
  There are two main views: Compass view and Sky view.
They can be selected by the [C] and the [S] buttons
at the lower right.

  The Sky view display mode draws an image of the sky 
with the planets and some of the brightest stars as it 
can be seen by an observer at the specified location 
and time. It shows the position of about 1600 of the 
brightest stars and the planets in a camera-like view.

  In Compass view, the information for the planets is
given in azimuth and altitude which is less intuitive 
as in Sky view but more accurate. Also shown in Compass 
view are the celestial coordinates of the planets 
and the Moon phase.

  The two text lines at the bottom of the display show
the currently selected geographical location and the
time which are used for the calculation. Also shown are
the local mean sidereal time and the julian date.

  If several planets happen to be at the same position and
are obscuring each other, note that the selected one
is drawn last and therefore always visible (use the
pulldown menu at the top right).

Menus
-----
  Use the menu item 'Set Location' to set your current
geographical position and the zime zone or just tap on
the location text at the bottom of the display.

  Use the menu item 'Set Time' and 'Set Date' to set the
time of the calculation or just tap on the date and the
time texts at the bottom of the display.

  If the [Now] button is switched on, the time of the 
built-in clock of the Palm is used and the display 
is updated every minute.

  In the menu 'Time Increment' you can select a time 
step which is used when pressing one of the scroll buttons 
of the Palm (hardware, not on the display). The odd
numbers are multiples of 23h56m and are useful for studying
planetary motions because the stars stay at their 
positions after each step.

  Use the menu item 'Preferences' to select which planets 
are to be drawn, if your display gets overcrowded. You might
know that Uranus, Neptune and Pluto are too faint to be seen
by the naked eye. In this window you will also find a list 
of the symbols of the planets in case you are not yet familiar 
with them.

Sky view
--------
  In Sky view, a part of the Sky is shown in a camera-like
picture. It displays about 1600 stars and 110 Messier
objects. To see the name and constellation of any star, 
tap on it. 

  Tap the [L] button to switch constellation lines on 
or off. 

  Use the [Z] button to zoom in or out by a factor of 2. 
If you tap the [S] button while the cross hair is still 
shown after tapping a star, this star will be centered as 
much as possible.

  To change the view direction tap on one of the dials
in the top corners or tap one of the arrows near the 
borders of the display. There are visual clues for the 
horizon (----), Zenith (+) and Nadir (X) and a short 
dashed line at a height of 45. 

  To find a star, a constellation or a Messier object, 
tap on the (?) button and select an object.


Compass view
------------
  In Compass view, the information for the planets is
given in azimuth (the horizontal angle between north and
the direction of the planet, counted eastwards) and
altitude (the vertical angle between the horizon and the
height of the planet, negative if below horizon). In 
preferences you can set whether azimuth is counted 
from North or from South.

  The circle at the right of the display shows the azimuth
of the planets on a compass scale. Turn the Palm so 
that 'N' points to the north.

  The semicircle on the left shows the altitude. Objects
below the horizon line 'H' are not visible at the
specified time and location.

  Inside the circle are shown ecliptic coordinates,
right ascension and declination and the distance
(all topocentric) of the selected planet.
1 AU (Astronomical Unit) is 149.59787e6 km.

  The Moon phase is drawn as it can be seen at the
specified location and time. The number besides it shows
the percentage in the cycle (I decided to use the space
of '%' for another digit instead). 0.00 is new moon,
50.00 is full moon, 25.00 and 75.00 are first and
last quarter respectively. Before 50.00 the Moon is
waxing, after 50.00 it is waning.

  Tap on a planet symbol to see its name.

  To get the azimuth and altitude of a star or a 
constellation, tap on the (?) button and select an object.

  To get information about rise, transit, set and twilight 
times, use the (R/S) button.


Known Bugs and Problems
-----------------------
- I have fixed all problems and bugs I knew about. 
  Please let me know if you find any other: planets@aho.ch

Disclaimer
----------
  Planetarium is provided "as-is" and without warranty of 
any kind, express or implied. I can accept no liability for 
data loss or any other problems caused directly or indirectly 
by the use of Planetarium.

Planetarium is copyright  1998,1999 by Andreas Hofer.

  Planetarium is shareware - this means that you can try it 
for a while and see if you like it. If you find that you 
are frequently using Planetarium then you need to register 
it to be able to legally continue using it (see the section 
at the end for details). If you decide not to register it 
after a reasonable evaluation period, you should stop using  
Planetarium and delete it from your Palm. 

  Please consider registering your copy of Planetarium. You 
will be supporting my development efforts and encouraging me
to produce more quality software like this.

  You may give unregistered copies to others under the same 
terms - they may try it and then either register or remove it.

  Planetarium (together with this document) may be included 
on any disk or CDROM of shareware sold by non-profit 
organizations. If you wish to include it in a commercial 
software collection, please contact me at aho@aho.ch

Registering Planetarium
-----------------------
You can find detailed information on how to
register at http://www.aho.ch/pilotplanets
There is also a link to PilotGear's online 
registration service.

  The trial version of Planetarium contains a reminder that 
will more and more often show up the longer you are using 
Planetarium. When you register you'll get a key which you 
need to enter into Planetarium. The key will make the 
reminder disappear and lets you fully enjoy Planetarium. 
Registered users will be put on my mailing list and alerted 
to Planetarium updates and bug fixes which I may release 
from time to time.

  You can register Planetarium in a variety of ways via the 
excellent PilotGear service. PilotGear accept all kinds of 
payment in all forms. They will send you promptly the 
registration key. Give them a ring or send a fax if you 
can't register via the web.

  http://www.pilotgear.com/
  PilotGear accept cards and cheques. Cost $19.
  Register securely online or with a phone call to +1-800-741-9070, 
  fax to +1-817-640-6614 or e-mail (sales@pilotgear.com).

  If registering by fax or e-mail please provide the following:
  Full Name, Address including city, state and zip, phone number,
  credit card (Visa, MasterCard or American Express), credit card
  number, expiration date and of course the fact that you want to
  register Planetarium.

If you live in Europe you can register via www.BTSoftware.com.
They will send you an invoice which you can pay in your local 
currency to a bank account in your country. (Not possible in 
all countries yet but they add new countries continuously.)

If you want to send cash because there are no fees that way,
you can ask me for my postal address: planets@aho.ch  

  Good luck and may all your clouds go away.

Cool things to try out with Planetarium
---------------------------------------
You can find this text with illustrations on
http://www.aho.ch/pilotplanets

  In this section I describe some things that you can do with
Planetarium. You are invited to do this step-by-step procedures
with me and see if you get the same results.

- Find the observation possibilities for today.
    Let's assume, today were Aug, 22. 1998 and the night 
    sky is going to be clear and we want to know if we should 
    stay up for watching the planets. Let's further assume 
    we are located at Chicago. 
    So enter the following as Location and Timezone: 
   88.0W, 42.0N, GMT-6, DST on 
    Set the date to Aug, 22. 1998.
    
    For a first survey, select Compass view and press the 
    (R/S) button for a table of the rise and set times of 
    the planets. We see that in the evening Jupiter and 
    Saturn will rise. The other planets set early in the 
    evening and will only be visible for a short time in 
    the morning.

    Set the time to 9:00 pm and make sure that in preferences 
    all planets are switched on. We see that at this moment 
    Jupiter is just above horizon. Set the time increment 
    to 1 hour. Increment several times. You can see that 
    the altitude of Jupiter is increasing with time and 
    Saturn is following. At midnight both could be seen well. 
    If you have a small telescope or binoculars, you could 
    try to observe Jupiter's moons and Saturn's ring. You 
    can also switch to Sky view and watch them crossing the 
    eastern horizon line when you are stepping the time.

- Determine sunrise and sunset
    Let's find the time of sunrise and sunset on Aug, 22. 1998
    in Boston. To do this, enter the following as Location and
    Timezone: 71.1W, 42.3N, GMT-5, DST on
    Set the date to Aug, 22. 1998.
    Choose Compass view and tap on the (R/S) button. In this
    window, select the [Twilight] button. After a few seconds 
    the display will show all the relevant times concerning 
    the Sun and twilight. Sunrise is at 5:59 am and sunset 
    is at 7:35 pm. 

    To verify this, enter 7:35 pm in Compass View. Please 
    note that sunrise and sunset are when the Sun has an 
    altitude of -0.83. One reason for this is that the Sun 
    is not a point of light but a disk about 0.5 wide. The 
    other reason is that the atmospheric refraction lets 
    objects at the horizon appear slightly higher than they 
    really are. Taking this into account, the top of the Sun's 
    disk visually crosses the horizon line when it's center 
    has an altitude of -0.83. 
    If you are interested in the times of Moon rise and set, 
    select the [Planets] button.

- See the Moon's crescent lying horizontally near the equator.
    When you live near the equator you can sometimes
    see the Moon lying horizontally like a smilie. This is
    an unfamiliar view for people living in higher latitudes.
    Enter the following as Location and Timezone:
    36.0E, 1.0S, GMT+3, DST off  (Nairobi)
    Set the date to Apr 20. 1999 and the time to 10.00 pm
    Choose Compass view and have a look at the Moon phase
    diagram. You can also select Sky view and see the Moon
    setting perfectly vertically when stepping hours.

- Verify the Sun eclipse at Aug 11. 1999 in southern Germany
    Let's go to southern Germany.
    Enter the following as Location and Timezone:
    10.0E, 48.5N, GMT+1, DST on
    Set the date to Aug 11. 1999 and the time to 12.35 pm
    Both the Sun and the Moon are small disks on the sky
    of about 0.5 wide and they have to get really close
    for an eclipse to occur. Most of the new moons are not
    eclipses because the Moon's orbit is tiltet by about 5
    to the pane of Earth's orbit and it passes either above
    or below the Sun. But on this specific day look at the
    azimuth and the altitude of the Sun (choose Compass
    view and set the selected planet to Sun) and compare it
    with the azimuth and the altitude of the Moon (set the
    selected planet to Moon). The are both 158.4 and 55.3
    respectively, so they are very close. Because the accuracy
    of Planetarium is only 0.1, we can not tell if this is a
    total or a partial eclipse not the exact contact times. 
    But in fact it was a total one. 
    And a totally clouded one, too...

- The Sun never sets in polar summer
    Let's go to Inuvik (Canada): 134W, 68N, GMT-7, DST on
    Set the date to June, 21. 1999. Now select Compass
    view and observe the altitude of the Sun as you step
    hour by hour through the day. It will not go below 1.4.

- Find the Big Dipper and Polaris
    If you live in northern hemispheres, enter your location 
    and try to find the Big Dipper and Polaris in Sky view. 
    You can use the search function for that, accessible by 
    tapping the (?) button. Please note that the official 
    name for Big Dipper is "Ursa Major".
 
- Observe a retrograde loop of a planet
    Do you know that the early medieval astronomers had
    great difficulty in explaining the planetary motions?
    Let's see why.
    Select 8E, 47N, GMT+1, DST off
    Select Nov 28. 1998, 7:00 am
    Select Sky view and make sure that in preferences
    Mars is switched on. Look horizontally in direction SE.
    You should see the Sun a few degrees below the horizon
    and Mars about 45 above. Set the time increment to
    6.981 days or to 29.918 days if you have little time.
    Using one of these odd numbers has the advantage that
    the stars seem to stay at their place and we can
    watch the motion of the planet against them.
    Step now the time up and observe Mars wandering through
    the constellations. In March 1999 it will slow down and
    go back in April! This retrograde loop will last until
    June and then Mars will continue in the usual direction.
    Unfortunately it becomes harder then to observe Mars on the
    real sky because it is also getting closer to the Sun and
    therefore the sky will be too bright to see it.

- Determine the next full moon
    Select 8E, 47N, GMT+1, DST on
    Select Aug 22. 1998, 1:00 pm
    When is the next full moon?
    New moon has just passed. The percentage next to
    the Moon phase diagram shows 1.19%. Full moon will
    be at 50.00%. Set the time increment to 7 days.
    Step up until you get close to 50 (I got 46.16).
    Reduce now the time increment to 24 hours. Step up
    or down until you get as close to 50.00 as possible.
    Reduce the time increment further and refine the time.
    Proceed until you arrive at the desired accuracy. It
    is not possible to be more precise than 5 min with the
    accuracy offered by Planetarium, so I found the next
    full moon will be at Sept. 6, 1998  1:25 pm.

- Use Planetarium as a compass
    Enter your location and switch the Now-Button on. If the
    Sun is visible on a clear sky, turn the Palm so that 
    the Sun symbol in the azimuth diagram points to the Sun.
    The aizmuth scale shows now the directions.
    To get it more precisely, the Sun should cast a shadow.
    Put the Palm on a flat even sunlit surface. This 
    surface should be as horizontal as possible. Find a 
    rectangular object like a cigarette box for example. Select 
    Compass view and set the selected planet to Sun, so that 
    you get a line drawn from the center in the azimuth diagram 
    to the Sun symbol. Now move and turn the Palm so that 
    this line is exactly aligned with the shadow of one of the
    vertical edges of the rectangular object.

