﻿THE INTRO
---------
mephemeris
version 1.24
2009/04/09

Copyright (C) 2009 Darren Enns <dmenns1@gmail.com>

Mephemeris is a cross-platform astronomy application written in Python (PyGTK).

It was primarily designed for the Maemo operating system, which runs on the Nokia
N8xx Internet tablet devices -- but it should run on other hardware and operating
systems that meet the software requirements.

THE REQUIREMENTS
----------------
Mephemeris requires:

- Python (2.5 or higher)
- PyGTK 
- PyEphem (3.7.3.2 or higher!)

THE PROGRAM
-----------
Mephemeris contains the following windows/buttons (approximate!):

                         +-------+
                         |WELCOME|
                         +-------+
                             |
                        +----------+
                        |BASIC INFO|
                        +----------+
                             |                                 
                             +------------------------------------------+
                             |                                          |
                             +---------------------------------------+  |
                             |                                       |  |
     +-----------+-----------+---------------------+--------------+  |  |
     |           |           |                     |              |  |  |
+--------+  +--------+  +------------+  +---------------------+   |  |  |
|SET DATE|  |SET TIME|  |SET LOCATION|  |DATE/TIME CHANGERS...|   |  |  |
+--------+  +--------+  +------------+  +---------------------+   |  |  |
                                                                  |  |  |
                    +--------+-------+----------------------------+  |  |
                    |        |       |                               |  |
                 +------+  +----+  +----+                            |  |
                 |SEASON|  |TIME|  |MOON|                            |  |
                 +------+  +----+  +----+                            |  |
                    |                                                |  |
          +---------+------+                                         |  |
          |                |                                         |  |
    +-------------+  +------------+                                  |  |
    |SUN SKY ANGLE|  |SUN ANALEMMA|                                  |  |
    +-------------+  +------------+                                  |  |
                                                                     |  |
                         +------+---------+--------------------------+  |
                         |      |         |                             |
                       +---+  +---+   +-------+                         |
                       |WEB|  |SKY|   |COMPASS|                         |
                       +---+  +---+   +-------+                         |
                         |      |                                       |
               +---------+      +--+-----------+                        |
               |                   |           |                        |
      +------------------+      +-----+  +---------------+              |
      |WEB DOWNLOADERS...|      |POLAR|  |EQUIRECTANGULAR|              |
      +------------------+      +-----+  +---------------+              |
                                   |          |                         |
                                +------------------+                    |
                                |DISPLAY OPTIONS...|                    |
                                +------------------+                    |
                                                                        |
                             +------------------------------------------+
                             |            
                          +------+ 
                          |DETAIL| 
                          +------+ 
                             |
     +------------+-----------------+------------------+-------------+
     |            |                 |                  |             |
+---------+   +--------+   +-----------------+   +----------+   +----------+
|MORE INFO|   |RISE/SET|   |SOLAR SYSTEM PLOT|   |MOON PLOTS|   |MOON PHASE|
+---------+   +--------+   +-----------------+   +----------+   +----------+
                  |                 |
              +--------+   +-------------------+
              |ANALEMMA|   |SOLAR SYSTEM ORBITS|
              +--------+   +-------------------+

The font color is intended as a visual clue as to what can be done with that 
button/label:

- yellow      = title display (not click-able)
- green       = information display (not click-able) 
- red         = change date/time/location/mode/etc
- light blue  = detail information display
- dark blue   = major sub-window display
- orange      = toggle GMT/local date/time displays

All windows (?) support the 'full screen mode' toggle button (on tablet) or
the 'F6' key (on keyboard).  Other hardware keys are enabled to a greater
degree on some of the other windows (e.g. 'Sky Plot' window).

It is strongly recommended that Mephemeris be run in 'full screen' mode,
since it provides the extra window space for fitting in all the screen
elements properly!  However, one negative side-effect of using the 'full
screen' mode is that the window 'close' button is no longer visible.  To
compensate for this, most windows are also sensitive to the 'Escape' key,
which acts as a 'close' button.

Now to look at each main window in turn...

WELCOME WINDOW
--------------
This window merely contains an image of the moon (taken my myself) with the
'Mephemeris' title superimposed.  Just 'click' on this to continue.

MAIN WINDOW
-----------
This window provides the 'front end' to all other window options, and also
acts as a display of 'basic' local date/time/location info, as well as
basic ephemeris data for the Sun and non-Earth planets.  The current values
displayed are dependent on the settings of date/time/location -- the initial
values are set by the 'mephemeris.dat' file (for location data), or the 
internal clock itself (for date/time data).  If any of these parameters are
altered, current/subsequent calculated info will reflect that.

Many of the buttons at the top of this window do not open their own sub-windows,
but rather act immediately on the action chosen:

DATE/TIME	= toggle between GMT and local date/time displays

-1 Yr           = set date/time backward one calendar year
-1 Mo           = set date/time backward one calendar month
-1 Dy           = set date/time backward one day
-1 Hr           = set date/time backward one hour
-1 Mi           = set date/time backward one minute
Reset Date/Time = reset date/time back to internal date/time
+1 Mi           = set date/time backward one minute
+1 Hr           = set date/time forward one hour
+1 Dy           = set date/time forward one day
+1 Mo           = set date/time forward one calendar month
+1 Yr           = set date/time forward one calendar year

Reset Location  = reset date/time/location back to internal values

The tabular information presented for the objects shown on this window i.e. the
Sun and planets can be toggled between two separate display styles by clicking
on the 'Name' button:

- RA/Dec/Magnitude/Size/Distance/Phase
- Alt/Az/Rise Az/Rise Time/Set Az/Set Time

MENU OPTIONS
------------
A menu with a small number of options is now also available on the 'basic' window:

File
- Quit          = Exit the program

Edit
- Edit Ini File = Allow user changes to 'mephemeris.ini' file
- Save Ini File = Save current parameter state to 'mephemeris.ini' file
- Edit Messier Image URLs File = Allow user changes to 'data/messier_url.dat' file
- Save Messier Image URLs File = Save changes to 'data/messier_url.dat' file
- Edit Miscellanious Image URLs File = Allow user changes to 'data/misc_url.dat' file
- Save Miscellanious Image URLs File = Save changes to 'data/misc_url.dat' file

Help
- Readme        = Displays this README file
- Licence       = Displays COPYING file
- About         = Display version and contact info for Mephemeris

EDIT INI WINDOW
---------------
A two-column table is presented in this window.  Only the 2nd column is editable.
Some validation is performed to avoid gross errors in the 'values' column.  For
those values that were updateable in other windows (e.g latitude, longitude,
temperature, pressure, elevation), a click on the 'name' column will update the
'value' column with the most current value.

EDIT MESSIER/MISCELLANEOUS WINDOWS
----------------------------------
A two-column table is presented in this window.  Both columns are editable.
Insure that the first column has no embedded blanks.  The second column is
intended to contain a URL of your chosing.  Insure that it is valid.

RESET TIME BUTTON
-----------------
This deserves extra explanation: the current version of Mephemeris does NOT
implement a 'real time' clock i.e. calculated values are statically generated
from the current date/time/location settings.  In order to generate 'fresh'
information, the date/time must be MANUALLY advanced -- by using the date/time
set/reset buttons/windows.

RESET LOCATION BUTTON
---------------------
This is a special case, since no window is actually opened, but it deserves
extra explanation:  If a GPS is connected/available, and a GPS lock
can be established, the location is used as the new location.  As well,
the current date/time is also used from the GPS lock.  If no GPS (or GPS
lock) is detected, the lat/long/date/time/temp/pressure/elevation read
from the 'ini' file is used for the reset.  

The original version of Mephemeris only supported the Maemo 'gpsbt' blue-tooth
option for GPS data, but now it also supports a non-Maemo 'gpsd' option.
The choice of which option is desired/present is controlled by the 'ini' file
(see below).  The prime choices for GPS 'mode' are:

- gpsbt = bluetooth (Maemo only?)
- gpsd  = network (non-Maemo only)
- none  = no GPS available

If you wish to use the 'gpsd' option, it is up to you to set up a functional
'gpsd' data source at the desired host/port values, which are also needed in
the 'ini' file.  Finally, a 'timeout' option is intended to control the number
of seconds that a 'lock' should be waited for (there is no 'threading' option
to enable you to kill a GPS connection attempt).

Generally, during testing, both the 'gpsbt' and 'gpsd' options worked extremely
well, once a solid GPS connection had been established.  However, it is not a
guaranteed source!

SET DATE WINDOW
---------------
This window uses the 'Hildon' (on Maemo), or a simple PyGTK calendar widget 
to allow the user to change the current date. 

SET TIME WINDOW
---------------
This window uses the 'Hildon' (on Maemo), or a simple PyGTK time widget to 
allow the user to change the current date. Since it can be very confusing
whether the time is being set in GMT or local time, an informational popup
will indicate which time display mode is currently in effect.

SET LOCATION WINDOW
-------------------
This window uses a simple PyGTK widget to allow the user to change the
current location (latitude/longitude), as well as some meteorological 
parameters that influence refraction distortions in the atmosphere
(temperature/pressure/elevation).

SEASON WINDOW
-------------
This window presents current/previous/next season (solstice/equinox) info
for the current date/time, using the current time display setting.

TIME WINDOW
-----------
This window presents current date/time info.

MOON WINDOW
-----------
This window presents current moon-specific ephemeris info.

WEB WINDOW
----------
This window allows download/display/usage of web-based images/data for those
situations where a web connection is present.  The reasons for providing this
feature are:

- some data is too complex for my coding skills (e.g. plots)
- some data is real-time and requires an external data source (e.g. weather)
- some data is dynamic and it saves on storage (e.g. APOD images)

Although attempts were made in the code to handle the occasional hassles of
web downloads (e.g. no connection, timeouts, etc.), you are mostly on your
own for how well this feature works! :)

The 'Astro Data' options, specifically the 'asteroid' (minor planets), 'comet',
and 'NEO' (near-earth-orbit and other unusual objects) will download data in
a format that PyEphem (and therefore Mephemeris) understands i.e. the Xephem
'edb' format.  Theoretically, any other source of such data could be used (and
referenced in the 'ini' file).  Note that the more objects that are downloaded,
the longer it will take to plot!  There is actually a LOT more data out there,
but it is unreasonable to expect Mephemeris to deal with larger datasets.  
There are currently three object types available:

- Asteroids = Bright minor planets reaching opposition during the current year
- Comets    = Current potentially observable comets (set for 2009)
- NEO       = Unusual objects, including the fast moving Near Earth Objects (NEOs)

Objects that are NOT currently included are:

- Critical List = Objects with incomplete/inaccurate orbital data
- Distant       = Centaurs and Transneptunian objects

The 'weather/elevation' options deserve further explanation: Using weather
station codes stored in the 'ini' file (see below), current weather conditions
can be downloaded from select web-based weather sites (XML!).  Not only does
this supply useful meteorological information to the user, but it also provides
the option to use this data in Mephemeris itself i.e. by clicking on the
temperature/pressure/elevation button labels (not the values themselves), the
selected values are then used to reset the current values in the internal
calculations.  These labels are marked in 'red' to differentiate them from
the information-only value displays.

The 'GeoNames Weather' option is unique in that it does not depend on a
preselected weather station code, but instead uses the current position
(latitude/longitude) to return the NEAREST weather station offering an
XML weather station download.

The 'GeoNames Elevation' option is also interesting in that it makes use
of an XML-based service to lookup elevations for the supplied location
(latitude/longitude) -- which can theoretically be more accurate than the
elevation values generated by current-technology GPS units -- at least
as far as the accuracy of the data source used is (currently SRTM).

The 'Google Map' option will download a single map tile centered on the 
location of the observer.  As well, clicking on the 'Distance' label of the 
'Weather Feed' option will download a Google Map tile showing *both* the
current observer location, *and* the weather station location.  As a bonus,
this mode also supports the zoom in/out buttons:

- Zoom in (F7)     = reduce FOV
- Zoom out (F8)    = increase FOV
- Select (RETURN)  = toggle roadmap/hybrid/terrain/satellite view

This feature uses a free API provided by Google for serving map tiles as images.
The documentation for this API mentions the need for an API 'key', but none was
needed/used in this context.  This makes this feature extremely tentative.  It is 
quite possible that the API key might be required in the future.  One possible
solution would be to use the free 'web redirect' feature of 'www.no-ip.org'.
If you feel uncomfortable about this use of the free Google static map service,
do not use it!  One small disadvantage of the current feature is the size of the 
image is limited to 600x400 pixels. :(

The 'Moon Map' option provides an alternate interface on the Clementine Lunar 
Image Browser (CLIB) found at 'http://www.cmf.nrl.navy.mil/clementine/clib/'.
The HTML interface there already support for the moon location to be 'zoomed',
as well as a 'zoom level', so with a bit of fancy code using a base image
from the site, a clickable/zoomable interface is possible. The initial 'base'
image is the one on which the point of interest is clicked.  Subsequent 'zoom'
images are the ones for which the zoom keys function.  Note that if the
'Grid Lines' option is activated on the 'Sky Plot' window, that a latitude/
longtitude grid is overlaid the base moon image.  The following buttons are 
supported:

- Zoom in (F7)     = reduce FOV
- Zoom out (F8)    = increase FOV
- Nav left         = move left 
- Nav right        = move right 
- Nav up           = move up 
- Nav down         = move down 

The maximum zoom level is '0', and the minimum zoom level is '5'.  The initial 
'zoom' level is '2', which roughly half-way between max/min zoom levels.
According to the CLIB web site, these zoom levels apparently correspond to these 
resolutions:

- zoom level 5 = 1 pixel = 32 kilometers 
- zoom level 4 = 1 pixel = 16 kilometers 
- zoom level 3 = 1 pixel = 8 kilometers 
- zoom level 2 = 1 pixel = 4 kilometers 
- zoom level 1 = 1 pixel = 2 kilometers 
- zoom level 0 = 1 pixel = 1 kilometer 

As well, if the 'feature' or 'feature name' options have been enabled on the
'Moon Phase' window, they will be applied to the base search image here as well.
Likewise, if the 'grid' option has been enabled on any of the other plot windows,
it will also be applied here.

The 'Satellite Position' option will download a 3D 'orthographic' (globe)
graphic showing the current position of the chosen satellite of interest,
as was provided in the 'ini' file for the 'number' option of the 'tle' section.

The 'Satellite Elements' option will download the text file containing
'TLE' element data as was provided in the 'ini' file for the 'group' 
option of the 'tle' section.  This refreshed file can then be used in the
'Satellites' option of the 'sky plot' window -- thereby displaying the location 
of the groups of satellites that the user had configured.  Alternatively, the
'tle.dat' file can be edited by hand with the parameters of interest.

The 'User Images' option will allow miscellaneous static imagery to be downloaded
and displayed, except that the list of links to the images is customizable by the
user by editing entries in the following files:

- messier_url.dat = file containing URLs of Messier images
- misc_url.dat    = file containing URLs of miscellaneous images

The following image groups are present:

- Messier       = images (of varying quality) of all 110 Messier objects
- NGC           = images of all (?) NGC objects
- Miscellaneous = images of whatever (astronomical?) images desired

The concept is that the user is able to modify the URL image source (for Messier 
objects), or add/remove/change URL image source (for Miscellaneous).  Some 
sample links are provided for both of those groups.  Due to the large number of NGC 
objects, there is no easy way to change the source of those images (in fact, there 
are very few places for sources of such images).

The downloaded images are automatically scaled upon presentation, and is also 
effected by the current full-screen mode setting i.e. the full-screen mode must
be chosen *before* the image is retrieved, in order for the scaling to take place.
It is the choice of the user whether to pick URLs for (large) images that need to 
be 'scaled down' to fit the N8xx screen size, rather than to seek out (small) 
images that are better suited to the N8xx screen size:

Con's - increased download time and temporary file space
Pro's - better resolution on larger screens (i.e. desktops) in full-screen mode

It is hoped that the file format is self-evident, but for the Messier file it is:

Messier Image
ID      URL
-----   ----
e.g.

1	http://...
2	http://..
...

For the miscellaneous image file:

Button Image
Label  URL
-----  -------
e.g.

label  http://... 

The 'button label' for miscellaneous image URLs can be anything acceptable
to the PyGTK label system, but the labels must be short enough so that the
generated button matrix is not overly large.

Take note that many of the 'web' options are date and/or location sensitive
e.g. many of the 'astro' images will differ from day-to-day and even
moment-to-moment, dependent on when the download is invoked.  For images
that are location-dependent, a change in location will have an effect on
the image downloaded.  Even the 'APOD' image changes from day-to-day, and
it is even possible to 'go back in time' to see what the APOD was on a different
date!

Credit for the image web links are provided where it was easy to do so.
By providing a link to an image -- rather the bundling actual images with Mephemeris 
-- it is hoped that the following has been accomplished:

- saving on storage space (i.e. URLs are much smaller than actual images)
- allowing for newer/better images in the future
- avoiding copyright infringement

DETAIL WINDOW
-------------
This window is activated by clicking on one of the solar system object
names on the 'Basic' window.  It presents detailed ephemeris info for the
selected object at the current date/time/location.  Various date/time
setting buttons are also present on this window.

RISE/SET WINDOW
---------------
This window is activated by clicking the button in the lower right corner
of the 'Detail' window.  It generates and displays a graph of the entire
current year, showing the trends for object rise and set, as well as
transit and anti-transit times.  It also displays the trends in total
day length (times when the object is above the horizon), even though the
y-axis units do not exactly mean the same thing :)

The values for these parameters is displayed for the current date, and the
position of the object (relative to rise/set) is also shown.  This takes
about 30 seconds to generate on the N8xx.

Colors are used to clarify the various parameter plots:

mauve  = anti-transit
red    = rise
yellow = transit
blue   = set
pink   = day length

SEASON INFO WINDOW
------------------
This window provides additional 'seasonal' data i.e. previous, current, and
future solstices and equinoxes, but it also provides buttons to invoke two
other graphic plots: for 'Sun Sky Angle' and 'Sun Analemma'.  See below.

SUN SKY ANGLE WINDOW
--------------------
This window generates and displays a graph of the Sun's path in the daytime
sky for 5 times of the year: spring, summer, fall, winter, and the current 
date.  It illustrates the dramatic change of the Sun's sunrise and sunset
azimuth during the year, as well as the Sun's altitude in the sky.  This
takes about 10 seconds to generate on the N8xx.

SUN ANALEMMA WINDOW
-------------------
This window is activated by pressing the 'select' button (on tablet)
or 'return' key (on keyboard) on the 'Rise/Set' window.  It will specifically
plot the 'analemma' diagram for the current year and location.  While this
feature is not all that useful, it presented an interesting coding challenge
and is something that one rarely gets to see for his/her location.  The
coordinates and plot are taken at 'noon' for each day.  This takes about
10 seconds to generate on the N8xx.

A spin-off of this work was the related 'equation of time'.  Also interesting,
some time was spent on implementing a separate window for this graph, but 
(for now) that feature is not implemented.  Instead, a simple calculation
for of the current equation-of-time is present on the 'Time' window.

SOLAR SYSTEM PLOT WINDOW(S)
---------------------------
This window is present only for the 'Sun' object, and is activated by clicking the
button in the lower right corner of the 'detail' screen for the 'Sun' object.  
There are two solar system plots available:

1) The first one, which is relatively quick, and shows the Sun, planets, and other
selected objects in their current locations.  This one provides the typical
datetime change buttons, label text-size control, as well as some optional 
object/name/search buttons, a 'Planet Trails' option, as well as the 'Legend Text' 
option.  The hardware keys available on this window are:

- Full screen (F6) = toggle full screen mode
- Zoom in (F7)     = reduce FOV
- Zoom out (F8)    = increase FOV
- Nav left         = set date/time backward one hour
- Nav right        = set date/time forward one hour
- Nav up           = set date/time forward one month
- Nav down         = set date/time backward one month

Using the 'Planet Trails' option will result in a white dot being drawn for the
planets for each time interval in the past/future selected using the datetime
change buttons (or matching hardware keys).  Note that heavy use of this feature
will slow down the display (especially on the N8xx device), since extra coordinates
are stored for each planet.  For an efficient calculation for an entire 'orbit' of
each of the planets, as well as display axis control, use the next plot display 
instead i.e. 'Orbit Plot'.

2) A second one, invoked using the 'Orbit Plot' button on the first, which is
quiet slow on the N8xx device (but fast on the desktop).  A fair amount of effort 
was taken into the code to make this as fast as possible, for the sake of the slow 
speed on the N8xx devices.  The main way this was done was by calculating the orbit 
positions for the current date/time only *once*, and then displaying it later when 
the plot window is actually drawn -- allowing zooming without re-doing the 
calculations.  Because of this, there is a short delay when this option is 
activated from the 'detail' window.  This takes about 15 seconds to generate on the 
N8xx.  The following hardware keys are enabled on this window:

- Full screen (F6) = toggle full screen mode
- Zoom in (F7)     = reduce FOV
- Zoom out (F8)    = increase FOV
- Nav left         = pan/rotate left
- Nav right        = pan/rotate right
- Nav up           = tilt/rotate up
- Nav down         = tilt/rotate down

In order for asteroid/comet/NEOs to be plotted as well, you need to have activated
the object type you are interested in using the supplied buttons.  As well, if you
want labels for the objects, you need to activate the object 'name' option for the
object type desired.  The default data files are large enough that the object
names tend to interfere with the display -- unless some amount of 'zoom in' has
been selected.  It is also possible to 'search' for an already-plotted object by
using the matching 'search' button -- the selected object will have a white circle
drawn around it, which will remain until the plot area is clicked.

Optional objects will be drawn on the 'Orbit Plot' window is they were selected
for display on the main 'Solar System Plot' display.

MOON PLOTS WINDOW
-----------------
This window is activated by clicking the button in the lower right corner of the
'detail' window, but only for the 'Mars/Jupiter/Saturn/Uranus' objects (because
that functionality is only available in PyEphem for those objects).  

The following hardware keys are enabled on the moon plots window:

- Full screen (F6) = toggle full screen mode
- Zoom in (F7)     = reduce FOV
- Zoom out (F8)    = increase FOV
- Nav left         = set date/time backward one hour
- Nav right        = set date/time forward one hour
- Nav up           = set date/time forward one month
- Nav down         = set date/time backward one month

Some reasonable efforts were taken to proportionally depict the angular size and
distance of the planet moons from their home planet i.e. zooming in will result
in both the planet *and* moons being enlarged in the display.  However, the minimum
size of the moons was established so that they would be visible even at extreme
zoom-out viewpoints.  No attempt was made to depict the actual surface features
of the planets involved; however, the correct angle for the rings of Saturn is
shown :)

It was somewhat tricky to verify the images plotted in these windows -- applets 
available on the web are few, awkward, and (in some cases) inaccurate.  One of the
more tricky efforts was to validate the angle of inclination of Saturn's rings.
Fortunately, even a website for that was located (see below).

MOON PHASE WINDOW
-----------------
This window graphically simulates the phase of the moon, by overlaying an image of
the moon with a crescent-shaped mask of the appropriate orientation and size.
Recent improvements include a dim -- rather than completely black -- terminator
shadow, accurate tilt of the terminator relative to the horizon, and textual moon
information.

Note that on the N8xx device, that this option is only permitted if the window is
in full-screen mode, due to the image warping that would otherwise occur.

The following hardware keys are enabled on the moon plots window:

- Full screen (F6) = toggle full screen mode
- Nav left         = set date/time backward one hour
- Nav right        = set date/time forward one hour
- Nav up           = set date/time forward one month
- Nav down         = set date/time backward one month

The window now also provides the typical datetime change buttons, as well as
some other options, including a moon feature option with optional names, and
search functionality.  When used, the 'search' function will temporarily hilight
the selected moon feature.

MORE INFO WINDOW
----------------
This window is currently only provided for the Earth's moon, since the PyEphem
libraries provide unique moon-related information that does not belong on the 
generic solar system object windows.

COMPASS WINDOW
--------------
This window was proposed by one of the users.  Mephemeris already had most of
this functionality in the polar-display/horizon-coordinate sky view plot i.e. 
it showed the compass direction of the sun, moon, etc. in reference to the
current horizon, along with cardinal compass points.  For this feature, 
the normal sky plot window was invoked, but with specific options (daytime
colors, only sun/moon objects, reversed horizon scale, etc.).  As with the 
normal 'sky plot' window (see below), some basic hardware keys are also enabled:

- Full screen (F6) = toggle full screen mode
- Zoom in (F7)     = reduce FOV
- Zoom out (F8)    = increase FOV

SKY PLOT WINDOW
---------------
This window was never anticipated for Mephemeris when it was first conceived.
It was thought that doing such complex graphics was beyond my coding skill
level (by a long shot!), but in the end it turned out to be easier than I
thought.  The default display is the 'polar' projection with 'horizon'
coordinates of the sky for the current date/time/location. Options are available
to toggle the 'projection' and 'coordinate' systems used (see below). 

By default, both the 'polar' and 'horizon' projections are generated in relation
to the user's azimuthal coordinates i.e. 'polar' shows the sky directly above
the user, and 'horizon' shows the view along the user's horizon -- this is known
as 'horizon' mode.  For new functionality, it is now possible to also 
switch to 'equatorial' mode.

The 'polar' projection is a 'stereographic' one.  This is the convention used
by most star charts, not because it is more accurate than others, but because
it produces the least-distorted view of constellations.  Some experimental code
was developed to use the more visually-accurate 'orthographic' (i.e. 'globe')
projection, but this was ultimately put aside.  The 'horizon' projection is an 
'equirectangular' one -- again a compromise in representing a the 3D sky onto
a 2D surface.

Selecting the option to display 'names' of objects will be ignored during re-draw
if the option to display the actual 'objects' is not also activated i.e. it doesn't
make sense to draw object labels without drawing them with their objects.

A relatively new feature is the ability to 'search' for particular objects.
To use this option properly, the object type of interest must already have been
selected *and* plotted (in order for the internal tables of objects to be
searched to be populated).  For some objects, like planets/comets/etc, a complete
searchable list is presented each time.  For others, like stars, the list populated
depends on the 'magnitude limit' threshhold currrently set/displayed. The actual
'search' function works this way: assuming the object type has already been
toggled active, and plotted, a single click on the matching 'search' button will
present a new window with a scrollable list of objects of that type.  This list
is sortable on any of the presented columns.  The user must 'click' on at least
one of the objects.  The window should then be closed.  The next click on the
'plot' window will center the view on the selected object.  The 'search' mode
is not a 'toggle' window, since it is only active for a single search and click
at a time.  If no object is selected, an arbitrary view will be selected (i.e. 
the zenith).

This window also supports a simple object 'tracking' feature: after using the 
'search' feature, as long as the main plot area is not selected -- and only the
date/time change keys are used -- the currently-selected object will remain in the
center of the plot window.

Th sky plot window is initially generated/drawn with a minimum feature set 
activated, and with a low (small) stellar magnitude filter set, leaving the choice 
for much more detail to be activated by the user.  By default, a minimal set of
stars, and the planets, are plotted.

The following hardware keys are enabled on the sky plot window:

- Full screen (F6) = toggle full screen mode
- Zoom in (F7)     = reduce FOV 
- Zoom out (F8)    = increase FOV 
- Nav left         = move left 
- Nav right        = move right 
- Nav up           = move up 
- Nav down         = move down 
- Select (RETURN)  = toggle equatorial/horizon coordinate modes
- Menu (F4)        = toggle on-screen controls verbose/spartan/off
- Escape           = kill window
- Swap             = no function
- Home (F5)        = no function

One very important behavior to recognize on this window is the 'queuing' action
i.e. in order to minimize screen refreshes (which can take a long time, 
depending on the degree of detail present), many of the option buttons do NOT
cause immediate visible changes to take place.  Instead, the choices are
'queued' (stacked) up, waiting till the user forces the plots to refresh -- 
by clicking on the plot surface.

On the other hand, the 'date/time' setting buttons cause immediate/visible
changes to occur i.e. the plots are re-drawn.

Clicking on the plot surface will re-center and re-draw the plot on that
coordinate (although this is not the 'center' of the display area itself, 
but shifted to the left side).  Sometimes it might be desired to re-draw
the display *without* inadvertently shifting the 'center' position -- the
best way to do this (currently) is to use one of the 'immediate' buttons
instead of clicking on the plot surface e.g. the 'date/time reset' button is
one such choice.  

A very large stellar database is currently packaged with Mephemeris, even 
though the device is not realistically/practically capable of processing all
the data.  For this reason -- on the Internet tablet -- it is recommended that
the visual magnitude limit be kept 'reasonable'.  On the other hand, running
Mephemeris on a fast desk/laptop computer can easily handle the entire database.

The planets plotted are *not* to scale, and are instead intentionally drawn
over-size to make them visible as 'objects of interest'.

In general, the plot display option buttons are self-explanatory:

(the following buttons are queued (stacked))

Stars           = toggle display of stellar objects
Planets         = toggle display of solar system objects
Constellations  = toggle displays of constellation outlines
NGC             = toggle display of NGC (deep sky) objects
Messier         = toggle display of Messier (deep sky) objects
Satellites      = toggle display of user-selected artificial satellites
Asteroids       = toggle display of bright near-opposition 'minor planets'
Comets          = toggle display of comets
NEOs            = toggle display of Near-Earth-Orbit and unusual objects
Milkyway	= toggle display of Milky Way translucent overlay
Inverse         = toggle plot colors between white/black
Grid            = toggle equatorial grid display
Names           = toggle labels for displayed objects
Horizon	    	= toggle display of horizon reference line
Ecliptic	= toggle display of ecliptic reference line
Galactic	= toggle display of galactic equator reference line
Legend          = toggle legend display

Hardware Keys   = toggle navigation/datetime change modes

Size            = decrease/increase object plot size
Bright          = decrease/increase object brightness
FOV             = decrease/increase field-of-view
Grid Space      = decrease/increase equatorial grid spacing
Magnitude       = decrease/increase object visual magnitude limit
Text Size       = decrease/increase plot text font size

Projection      = toggle equirectangular/polar projection modes
Coordinates     = toggle equatorial/horizon coordinate modes

(the following buttons take immediate effect)

Year            = decrease/increase current year
Month           = decrease/increase current month
Day             = decrease/increase current day
Hour            = decrease/increase current hour
Reset Date/Time = re-set date/time back to current internal clock

THE FILES
---------
The following files/directories are currently part of the mephemeris distribution,
and stored in the '/usr/lib/mephemeris' directory:

mephemeris.ini	= initialization file; currently only contains latitude/longitude
mephemeris.jpg	= banner splash screen for starting application; click to continue
mephemeris.py	= python program
/data		= directory containing object data files, and web images
/doc		= directory containing doc files; currently only contains README

For the actual internet tablet 'deb' distribution, a few other files are also 
present:

/usr/bin/mephemeris					= starter script
/usr/share/applications/hildon/mephemeris.desktop	= desktop config file
/usr/share/applications/pixmaps/mephemeris.png		= menu icon (too small!)

The control file 'mephemeris.ini' is read when the program begins.  It contains
the following sections and entries:

e.g.

[location]
longitude: -98.1
latitude: 49.2
temperature: 25.0
pressure: 1010.0
elevation: 328.0
yahoo: CAXX0547
wunderground: IMANITOB37
[tle]
number: 25544
group: http://celestrak.com/NORAD/elements/visual.txt
[gps]
#mode: gpsbt
mode: gpsd
timeout: 10
host: 192.168.1.104
port: 2947
[ngc]
source: http://darethehair.googlepages.com/ngc.dat
[asteroid]
source: http://www.cfa.harvard.edu/iau/Ephemerides/Bright/2009/Soft03Bright.txt
[comet]
source: http://www.cfa.harvard.edu/iau/Ephemerides/Comets/Soft03Cmt.txt
[neo]
source: http://www.cfa.harvard.edu/iau/Ephemerides/Unusual/Soft03Unusual.txt
[plot]
resolution: 180

Values NEED to be present for each parameter, but they can be customized to any
values the user desires.  Take note that any upgrades/reinstalls of Mephemeris
will overwrite your custom settings, so write them down ahead of time! :)

When the program is running, most of these parameters can be dynamically altered
by the user using the appropriate buttons/windows, or set automatically

e.g.

latitude/longitude   = set by user or GPS device (if present)
temperature/pressure = set by user or web-based weather site download
elevation            = set by user or web-based geo service

The 'yahoo' and 'wunderground' parameters cannot (currently) be dynamically set.
The values are the 'codes' used to uniquely identify weather stations.  
Theoretically, the user would set them to the 'nearest' weather station, in order
to supply current weather conditions -- as well as temperature/pressure/elevation
values.  Visit the Yahoo or Weather Underground (Wunderground) websites
(see web links below) to look up relevant locations.

The 'number' parameter of the 'tle' section contains a single satellite number,
which can then be used on the 'Satellite Position' image download on the 'web'
window.  See the 'CelesTrak' website for the list of TLE files, each containing
satellite numbers that may be of interest.

The 'resolution' parameter of the 'plot' section indicates the number of solar
system plot points to be used to visually show the 'orbits' on the solar system
orbit plot window (fewer = faster, more = slower).

THE HISTORY AND MOTIVATION
--------------------------
Astronomy has been one of my hobbies since I was quite young.  In my University
years, when I purchased my first computer (Commodore 64), I wrote my first
astronomy application in the 'BASIC' programming language.  I was fascinated
by the fact that the mathematics involved were simple enough for anyone to
accurately simulate the position and appearance of the night sky.

In early 2007 I purchased my first 'pocket sized' computer -- a Nokia N800.
A major selling point for me was the realization that I could -- with the
proper tools and study -- write my own applications for the device.  It was
just a matter of time before I wrote something like 'mephemeris'.  Of course,
it was the existence of the Python programming language available for that
device, and Brandon Rhodes' excellent 'PyEphem' routines that made this even
the last bit realistic.

At the point which this application was developed, by skills to write a proper
OOP (object oriented programming)-style Python program were non-existent.
All I had to rely upon was my 'old school' structured programming methodology
I had been taught in my university days (way back in the early 1980s).

Initially, after some experiments were run, I concluded that Python (especially
on the Nokia Internet tablet) was probably not going to be 'fast enough' to 
drive a rich graphic 'planetarium-style' astronomy program.  I contented myself 
with simply striving to create a 'text-based' ephemeris-style program instead
-- not to mention the fact that my skill with PyGTK seemed woefully inadequate
for an attempt at any 'graphics'.  However, with a bit of help, and lots of
Google searches and reading, I determined that it was possible for me to 
create some simple polar (and later equirectangular) planetarium plots.  

My next challenge was to find an 'open' source of stellar data, and I ultimately
located the 'Hipparcos' catalog online, and I was on my way.  For the initial
version of the program, only stars down to magnitude 6.5 were used -- this also
happens to be the practical limit for CPU power of the Nokia N8x0 devices.
For the current version, a much larger catalog was generated -- down to magnitude
12.5 or so.  I also changed the catalog format to provide more fields of 
information -- even if not all are currently used:

HIPID	RIGHT ASC	DECLINATION	MAG	TYPE	COMMON STAR NAME
-----	-------------	-------------	-----	------	----------------
e.g.

32349   06:45:08.9173   -16:42:58.017   -1.47   SB*     NAME SIRIUS

The new catalog also provides common star names for many of the brightest
objects -- I had to do the 'translation' myself (using various sources), so
you can thank me for that :)  I also removed a few entries from the catalog
that did not make sense (for one reason or another).

The NGC (New Galactic Catalog) of non-stellar objects was also recently introduced.
This is based on NGC2000 by Sky Publishing (see below), which was made freely
available for non-commercial purposes.  I used the 'VizieR' web site to extract
only the columns I was interested in.  I then mushed the blank-separated object
names into a single string, and sorted the list by magnitude.  Finally, of the
13226 objects in the complete catalog, I removed 5460 that had no magnitude (!),
leaving the final 7766 objects.  The format is thus:

NAME    ASC     DEC     MAG
------- ------- ------ ----
e.g.

IC2602  10 43.2 -64 24  1.9

The modified NGC data file is not included with the Mephemeris package, since the
license is not compatible.  Instead, if the user has the option of downloading it
(via an option on the 'web' window) with the understanding that it is licensed
separately (yes, I know, this license stuff is a bit of a nuisance sometimes).

THE TOOLS
---------
The Nokia N800 (running OS2008) is easily capable of running Python.  In this
particular case, the 'PyGTK' running on my Fedora-based Linux desktop x86 PC
was extremely similar to the one which I installed on the N800.  No compilers
were required.

The 'PyEphem' routines are byte-compiled Python library code.  It was necessary
to cross-compile the source into 'ARMEL'-compatible form.  A Maemo 'scratchbox'
environment was installed on another x86 PC running Debian linux.  Compiling
the 'PyEphem' modules was very easy.  The end result was gathered into a
'debian' package, and made available to others in the OS2008 community.

All development was performed on the Fedora x86 linux desktop.  For the most
part, this provided a very good development environment, and periodically the
code was simply copied to the N800 to prove that everything worked, and the
elements were able to fit onto the screen properly.  The only limitations
encountered in this environment were that the specialized 'Hildon' code was
only recognized on the N800 itself e.g. date/time setters, GPS routines.

THE FUTURE
----------
The ability to run the application/ calculations on a 'real time' clock would be great 
(though the N8xx devices might not be powerful enough to do this every second).

THE EXTERNAL RESOURCES
----------------------

Much thanks go to the people behind the following websites and software for
providing the free tools/data/images for use in Mephemeris:

http://rhodesmill.org/pyephem/ (for Python ephemeris libraries)
http://khertan.net/pypackager.php (for creating Debian 'deb' files with PyPackager)
http://space.jpl.nasa.gov/ (for dynamic solar system orbit displays)
http://www.fourmilab.ch (for dynamic views of the earth and sky)
http://pymaemo.garage.maemo.org/ (for information of Python on Maemo)
http://www.pygtk.org/ (for information of PyGTK)
http://cadcwww.hia.nrc.ca/astrocat/hipparcos/hip_main.html (for free source of star data)
http://www.rssd.esa.int/index.php?project=HIPPARCOS&page=common (common star names)
http://simbad.u-strasbg.fr/simbad/sim-fid (better filter for hipparcos data)
http://webviz.u-strasbg.fr/viz-bin/VizieR-5?-out.add=.&-source=VII/118/ngc2000&Name=6805 (NGC data)
http://antwrp.gsfc.nasa.gov/apod/astropix.html (for astronomical picture of the day)
http://apod.nasa.gov/apod/lib/aptree.html (APOD categorized image links)
http://www.seds.org/messier/ (Messier image links)
http://www.fourmilab.ch/homeplanet (for constellation data)
http://xml.weather.yahoo.com (for Yahoo weather XML)
http://api.wunderground.com (for Weather Underground weather XML)
http://ws.geonames.org (for GeoNames elevation and weather XML)
http://mathworld.wolfram.com/StereographicProjection.html (for stereographic projection formula)
http://code.google.com/apis/maps/documentation/staticmaps/ (for google static map API)
http://celestrak.com/NORAD/elements/ (for TLE satellite elements)
http://www.heavens-above.com (for realtime satellite orbit images)
http://pds-rings.seti.org/tools/viewer2_sat.html (for accurate plots of Saturn's rings and moons)
http://edu.kde.org/kstars/ (for the Milkyway polygon data file, and thanks to James Bowlin)
http://solarsystem.nasa.gov/index.cfm (NASA planet image links)
http://hubblesite.org/ (Hubble image links)
http://www.ngcic.org/dss (full NGC and alternative Messier image link collection)
http://www.qcontinuum.org/compass/ (for good model for Sun compass feature)
http://jackvalmadre.wordpress.com/tag/cairo/ (for tips on resizing images well for Cairo)
http://www.cfa.harvard.edu/iau/Ephemerides/ (for orbital elements for asteroids, comets, and NEOs)
http://www.mmto.org/obscats/edb.html (for description of the 'edb' (Xephem) orbital elements format)
http://www.cairographics.org/manual/index.html (for API for Cairo drawing)
http://www.cmf.nrl.navy.mil/clementine/clib/ (for Clementine Lunar Image Browser images)
http://www.skyandtelescope.com/observing/objects/moon/3308811.html (for Lunar100 list)
http://www.biblegateway.com/ (for verse quote in dedication)

Credit also needs to be given to Sky Publishing for their 'NGC 2000' catalog, a subset which was 
downloaded from the 'VizieR' site and manipulated into a form usable by Mephemeris.  The copyright 
on the downloaded data said this:

	NGC 2000.0 (Sky Publishing, ed. Sinnott 1988)

The actual license terms mentioned are as follows:

Copyright Notice:
    This catalog is copyrighted by Sky Publishing Corporation, which has
    kindly deposited the machine version in the data centers for permanent
    archiving and dissemination to astronomers for scientific research
    purposes only. The data should not be used for commercial purposes
    without the explicit permission of Sky Publishing Corporation.

I also wish to thank those that have provided positive feedback, as well as constructive 
criticism of Mephemeris.  My programming skills do not allow me to implement every feature than 
has been suggested (or even that I myself have conceived of). As more code is added, I am pleased 
with the increase in functionality, but disappointed with the complexity and 'ugliness' of the code.

FAQ (Frequently Asked Questions)
--------------------------------

Q: Have users really asked all the questions posed in this FAQ?
A: No, at least not yet -- but I think that it is an appropriate way to describe some of the 
   behavior, challenges, and compromises that were made during development :)

Q: Why was Mephemeris developed?  Aren't there much better astronomy applications out there?
A: This project originated from a desire to learn Python, and to write an application for use 
   on the Nokia Internet tablet series.  I had previously written a 'PyGame' entertainment 
   application, and now wanted to write a more serious 'PyGTK' scientific application.  As of   
   the writing of this entry, there was only one astronomy application for Maemo, named 'Stars',
   but no apparent progress has been made since it was first released.  Certainly, on the desktop,
   and other PDA operating systems, there are *much* better astronomy applications available!

Q: Why wasn't Mephemeris written in a much faster/superior programming language?
A: Python is a modern, popular, and (fairly) easy programming language.  It is cross-platform,
   doesn't require a compiler (since it is a 'scripting' language), and allows me to develop
   Mephemeris 100% on my desktop (big screen!).  I also originally perceived that Python would
   not be fast enough on the Nokia N8xx Internet tablets, but I was pleasantly surprised how
   fast it really ran.  Of course, the compiled 'PyEphem' libraries that it uses do an
   excellent job of making the astronomical calculations as fast as possible!

Q: Can Mephemeris be run on other operating systems than Maemo (and N8xx Internet tablets)?
A: Although written specifically for the Maemo operating system, I have intentionally coded 
   so that the application should run successfully in any 'PyGTK' environment also containing the 
   'PyEphem' library.

Q: Where did the silly name 'Mephemeris' come from?
A: The name 'mephemeris' is a combination of 'Maemo' + 'ephemeris'.  Not very clever, but I 
   couldn't think of a better name at the time :)

Q: Why does the UI (user interface) of Mephemeris look so shabby?
A: Well, part of that is my lack of a serious programming background, but it may also be due
   (in part) to the limitations of PyGTK from a 'visual' perspective.  Certainly, there are
   a lot of other astronomical applications that look 'nicer' than Mephemeris -- but it is
   still 'good enough' for me! :)

Q: Why doesn't Mephemeris have a RT (real-time) clock mode?  Doing manual refreshes is tedious!
A: With proper 'threading' in the Python code, such a thing might be possible.  However, my
   skills in that area are lacking (see other reference to this issue).  As well, the calculations
   in Mephemeris are 'intense' enough that I seriously doubt that second-by-second real-time
   calculations are even possible.

Q: Can Mephemeris be depended upon for serious and accurate astronomy?
A: This software is "as is", and has no warranty of any kind.  The author assumes no 
   responsibility for the consequences of any use of this software.  I have tried my best to 
   make it accurate and truthful, but all programs have bugs, right?

Q: Why does the Python code for Mephemeris look so terrible?
A: I am not a programmer by profession, though I have tried to keep some skills intact after
   graduating with a Computer Science degree back in 1984.  Modern and proper Python relies
   heavily on OOP (object oriented programming) style, and it is very difficult for me (at my
   age) to "get my head" around that.  Mephemeris is written well enough for me to maintain,
   but not nearly good enough for serious peer review.  At this point, 'functionality' is more
   important than 'beauty' :)

Q: Why don't you use 'generic' data files for stellar, Messier, NGC position data?
A: In order to save space, I created custom data files for Mephemeris.  The 'fully-populated'
   data files available on the Internet are amazing, but I wanted to make Mephemeris as 
   'lean and mean' as possible.  As well, I wanted my data files to be sorted in ascending
    'magnitude' order, which allowed me to avoid reading the *entire* file -- by filtering
   on the magnitude that the user had currently selected.

Q: Why is Mephemeris not packaged with a bunch of cool astronomical pictures to look at?
A: Pictures take lots of space, and the Internet provides a fresh supply of images much better
   than I could gather on my own.  As well, the legal hassle of dealing with copyright issues
   on images is not something that I wanted to deal with.  It was felt that providing image
   download links (with appropriate on-screen credits) was the optimal solution for getting
   nice 'eye candy' :)

Q: Why did you add 'equatorial' projections to the 'sky plot' window?
A: At first, I decided not to take the time to do 'equatorial' projections, and stick with the
   local 'horizon' projection instead -- since I wanted to provide the benefit of custom/local
   visual information, rather than the 'static' ones that any paper/digital equatorial maps
   could provide (and at much better detail/speed than Mephemeris is capable of).  Later on,
   I changed my mind -- I thought that perhaps there are those that would want 'equatorial'
   viewing anyways, since there weren't a lot of other convenient choices on Maemo for that
   (other than viewing pre-generated PDFs or web pages).

Q: Why isn't there a nice and easy way to cancel long-running calculations in Mephemeris?
A: In order to do this, 'threading' would be required.  I spent time trying to figure out how
   to do this, but eventually gave up.  Where reasonable, I provide on-screen warnings about
   long-running calculations.  For GPS fixes, I provide a user-selectable 'timeout' value.
   For sky plots, be aware that setting a high magnitude limit is asking for trouble -- it
   is recommended that you restrict the magnitude setting on the N8xx devices to no higher
   than around '6' or so (visual magnitude limit), and reserve reading higher values for
   operation on faster devices i.e. desktop.

Q: Why is everything so small on the Nokia N8xx Internet tablet when running Mephemeris?
A: The 800x480 pixel resolution of the N8xx series is amazing, but the high DPI that this
   resolution causes on the 4 inch screen means that everything will be very small.  The UI
   (user interface) of Mephemeris has been changed numerous times in order to balance readability
   with usability.  For example, on the 'sky plot' screens, the user can select the font size
   (for text), turn off text completely (to make more room for the actual 'plotting'), change
   the relative object sizes/brightness/etc to make up for the small screen size, etc..

Q: What were the challenging programming challenges encountered while developing Mephemeris?
A: More than I care to talk about :)  Since I started with minimal Python programming knowledge,
   also every step along the way had at least some degree of difficulty for me.  Mephemeris
   started as a completely 'text-based' application, and even for that I had to figure out how
   the 'PyGTK' button/label/event system worked.  Adding graphics required learning about the
   'Cairo' vector drawing library, and well as a lot more OOP required to do so, was pretty
   difficult.  For actual 'algorithm' challenges, figuring out how to do the various map 
   projections, plot zooms, and spherical trigonometry took a *lot* of time.  Even something
   as 'simple' as the plotting of the phase of the moon was very tricky and required numerous
   trial-and-error to get it working (mostly) correctly. 

Q: Why isn't the current date/time visible on the 'moon phase' plot window like on other windows?
A: As mentioned, the 'moon phase' window was a lot more tricky than it looks :)
   What I wanted to accomplish was to 'overlay' a transparent 'crescent' shape on top of a moon
   image, but I couldn't figure out how to do that.  So, I ended up taking a different approach:
   creating a crescent-shaped 'window' through which the moon image would 'shine'.  I could not
   figure out a way to draw text on top of the 'clip' window.  The actually 'scaling' that is
   done in 'full-screen' mode uses a totally different technique than is used to scale the images
   downloaded in the 'web' window.  Oh, and by the way, creating the 'crescent' shape required was a 
   'hair-pulling' experience :)

Q: Why isn't the 'NGC' catalog packaged with Mephemeris?  Why does it need to be downloaded separately?
A: The GPL license of Mephemeris is incompatible with the 'license' provided for by the original NGC
   data.  I couldn't think of a way around this except what I had seen other developers do i.e. 
   provide NGC as a separate/optional download.

Q: Why isn't 'TLE' satellite data packaged with Mephemeris?  Why does it need to be downloaded separately?
A: TLE elements change over time, so the 'fresher' the data is, the better the accuracy.  Downloading
   from the Internet is easy, so why not? :)

Q: Why isn't asteroid, comet, and NEO data packaged with Mephemeris?  Why does it need to be downloaded 
   separately?
A: For reasons similar to 'TLE' satellite data mentioned above. 

Q: Why does the 'Milky Way' graphic overlay not extend completely to the far left/right edges of the
   'equirectangular/horizon' sky plot display?
A: The data file making up the Milky Way file is based on RA/Dec, and not (of course) local azimuth/
   elevation values for the current user.  It is composed of 'polygons', which are then 'filled'
   by PyGTK for the transparent effect.  The polygons are not nicely 'terminated' at the edges of
   the azimuthal coordinates, but would otherwise want to 'wrap around' to the other side -- creating
   a graphics mess.  The only practical way for me to deal with this was to avoid drawing any polygons
   that overlap on those edges -- and even that was a difficult task!

Q: Does a GPS (Global Positioning Satellite) receiver actually work with Mephemeris?
A: Yes, at least for me it works quite well.  The feature started off with the Maemo-only 'bluetooth'
   GPS ability, and recently I added 'gpsd' (linux demon) ability as well (basis a user suggestion).
   As far as I know, this 'covers' all the GPS functionality that (I think) needs to be covered
   - excluding development of *custom* code for individual GPS devices.  Take note that this feature
   is not always 100% reliable i.e. you need a good, clean, consistent 'lock' in order for this to
   work properly.

Q: What's with that weird 'analemma' feature anyways?
A: When I completed all the work required for the 'rise/set' plot window, I found out that it would
   not take a lot more effort to add the 'analemma' option.  Yes, it is a strange thing, but something
   that is unique to your location, and not something that you will ever 'observe' on your own -- unless
   you are willing to take a year's worth of time-lapse pictures of the sun and mogrify them together :) 
 
Q: Are all those 'weather' features in Mephemeris really necessary?  Is elevation/pressure/etc relevant?
A: Yes, apparently atmospheric parameters like observer elevation, temperature, and air pressure *are*
   relevant to accurate position calculations done by Mephemeris (via PyEphem), due to 'refraction'
   effects.  What is not totally clear (yet) is how accurately the internal calculations taken by
   PyEphem take these parameters into effect -- but 'something is better than nothing' :) 

Q: Why is Mephemeris packaged only as a Debian 'deb' file?  What about 'tar' and 'RPM'?
A: I myself have been a Redhat/Fedora desktop Linux user since the early days, and so I also love
   RPM packages.  However, since Mephemeris was developed for the Maemo operating system, I decided
   to use Debian 'deb' packaging instead.  Fortunately for me, 'PyPackager' was released and allowed
   me to easily create such packages.  Note that 'deb' files are just a special variation (?) of
   the classic 'tar.gz' packaging scheme, so anybody that knows their way around the 'ar' and 'tar' 
   commans dcan open the Mephemeris 'deb' package for their own platform.

Q: Why did you only start using proper 'toggle' and 'radio' buttons on the 'sky plot' window so late in
   the development of Mephemeris?
A: This was again due to my lack of experience, and fear of OOP programming -- especially considering
   that what I already had was working (if poorly).  After I got a bit of confidence, I found that it
   was not as difficult as I thought it would be.  Even so, getting PyGTK to do exactly what I wanted
   did not work 100% successfully e.g. as of this writing, I cannot control both the background and
   foreground colors in the 'radio' button widgets. 

Q: Where did that idea for a 'sun compass' come from?  Do you actually use it?
A: This feature was recommended by one of the users, as something that he had seen for another PDA
   astronomy program.  I found a much better representation of what this feature was all about
   (see HTML credits), and decided that it would be relatively easy to add -- since it was merely
   a left-right reversed daytime sky plot image with an exaggerated depiction of the sun and moon.
   No, I had never conceived of such an idea myself, but some people (apparently) find it quite
   useful -- especially on 'pocket' computers.

Q: Why didn't you include sources for *all* comets, asteroids, and NEOs?
A: A full list of all known solar system objects would number in the hundreds of thousands.  This is
   much too many for Mephemeris to handle, and provides an overwhelming amount of detail.  If there
   are particular objects that you are interested in, it is recommended that you hand-edit one of the
   data files to include the orbital elements of the objects you are interested in -- and at the same
   time (perhaps) removing ones that you are not interested in.  Of course, the next down you download
   and refresh the data files, your customizations will be lost.

Q: Why are the positions of the comets, asteroids, and NEOs way off the true location?
A: If the orbital elements are old (months? years?) then that will definitely have a degrading impact
   on the accuracy of the position calculations, and you are advised to get fresher data.  If the data
   is fresh, but still generates an inaccurate position, then (perhaps) there is a bug in the python
   library that is being used, or in Mephemeris itself.

Q: Why did it take so long for a 'search' function to be implemented in Mephemeris?
A: Believe it or not, it was easier to develop code to project with a view of the sky, and then alter
   the 'relative' point-of-view from that point *without* knowing what the new 'absolute' direction
   being viewed.  It was even more difficult to move the view of the sky to point to a *particular*
   object.  So, the, the answer is that it was difficult to know the behavior of my code to the
   degree required for absolute positioning.

Q: Why doesn't the moon image in the 'Moon Phase' window doesn't look 100% like it does in the sky?
A: The actual terminator shadow is artificially drawn, as is the dimming represented.  The 'tilt'
   (zenith angle) is something that I had a lot of difficulty figuring out, and I know that the angle
   shown is close to the true angle, but is not fully accurate i.e. it assumes that the moon is 
   following the same 'great circle' path in the sky as does the Sun, but in fact the Sun follows the
   'ecliptic', and the moon is off that by a few degrees.  I ended up using a nice, clear moon image
   from the Clementine mission instead of my own, since it showed a 'neutral' image of the moon
   (without libration) and was accurately oriented vertically for a latitude/longtitude overlay to be
   properly drawn.

Q: The 'moon features' option on the 'Moon Phase' window is terribly cramped, and doesn't allow zooming,
   so isn't it fairly useless?
A: On small displays, I agree that the 'moon features' option isn't terribly useful, but on larger
   displays it makes a bit more sense.  The main focus of this window was to provide a somewhat realistic
   display of the phase/orientation of the Moon -- not to provide a fancy zoomable map of the Moon.  For
   that, I would suggest the 'Moon Map' option on the 'web' window, which takes images from the 
   Clementine mission.

Q: Why doesn't the 'moon feature' option work with the zoomed downloaded moon images from the Clementine
   web site?
A: For now, simply providing an easier way to download/view/zoom moon images of interest was my goal.
   It would take a lot more work for me to understand the image calibration sufficiently to overlap my
   own highlighting on top of these images.  

Q: Why are there two 'solar system' plot windows available?  Why not combine them into just one feature?
A: Mostly, it was a compromize for the sake of slower hardware i.e. the N8xx devices.  It become easier
   to separate the old 'orbit' plot from the new 'position' plot.  The 'position' plot would allow changes
   to the date/time, and would not spend time generating the additional data points necessary to show
   each planet's full orbital path.  This then provided an option for a 'trail' option.  The older 'orbit'
   plot would be 'lean and mean', intended for quicker rotation on the x/y/z axis.

Q: Why does that app sometimes warn of options that will take a long time, and sometimes does not?
A: Although it is easy to generate a warning popup, I had to decide how 'long' a pending operation was
   going to take before it was worth the nuisance of the popup.  Arbitrarily, I decided that 15 seconds
   was 'long' enough to warn the user.  

Q: What crazy version numbering scheme is being used for Mephemeris?
A: Every time I make a large enough change that I want to 'snapshot' the functional status, a
   new version number is created, starting from 0.01.  Hypothetically, by the time it reaches
   1.0, Mephemeris should be fairly complete and functional -- but *not* perfect :)

Q: What should I do if I discover a bug in Mephemeris?
A: Keep it to yourself :)  Actually, I would appreciate knowing about it.  I don't relish the thought
   of releasing a new version *just* to fix bugs, but if the fixes are easy enough, and the benefit
   strong enough, then it is best for all if this is done.  Some bugs are simple typing or thinking
   mistakes, while others may be due to the underlying infrastructure itself e.g. I discovered subtle
   behavior changes between 'Maemo' and 'Desktop' execution of Mephemeris -- some which I have been
   able to compensate for.  
 
Q: Why are you giving so many excuses for Mephemeris?
A: Because I want people to realize that Mephemeris is 'a labor of love', and not commercial software
   that they paid for using their hard-earned cash, and that it is 'just me' and not a team of 
   crack-shot programmers churning out perfect code :) 

Q: Shouldn't you be spending more time doing actual 'astronomy' rather than developing Mephemeris?
A: Yes, of course!  I have always been more of an 'armchair astronomer', but I do also enjoy
   the experience of watching the sky (even during the day!) and capturing it digitally.  You
   might want to check out my personal 'astronomy' web page sometime to see the (humble) things
   I have done in the past.  Of course, lots of people have done a *lot* more amazing things than
   me as observers! 

Q: Do you intend to continue to develop Mephemeris?
A: As of this writing, the vast majority of features that I wanted (and believe that I have the
   necessary skills to develop) are present.  On user request, I will consider further development,
   but I would also like to move on to some other projects for a change of pace! I do have other
   interests than just astronomy -- check my personal web pages if you are curious!

DEDICATION
----------
This software is dedicated to the honor of the 'Master Designer', the Creator of our incredible
universe!

Amos 5:8 (New Living Translation)

   It is the Lord who created the stars,
      the Pleiades and Orion.
   He turns darkness into morning
      and day into night.
   He draws up water from the oceans
      and pours it down as rain on the land.
      The Lord is his name!

BUGS
----
- The 'Reset Location' for 'gpsd' occasionally returns the wrong current 'time'.  If a good GPS lock
is present, subsequent clicks will return the correct value.  I am not sure what I can do about this
bug, since 'gpsd' reports that a 'lock' has been established, but the 'time' is not guaranteed to
be immediately correct.

CHANGES
-------
2008/04/24 = version 0.36 
- original version released to public

2008/08/11 = version 0.39 
- fix calculation of Messier object positions
- much larger 'stars.dat' file (118121 entries compared to original 8924 entries)
- option added to toggle star names
- check to verify that PyEphem version is 3.7.3.2 or higher
- much faster method to get APOD (astronomy picture of the day)
- show plot legend on equatorial star map

2008/08/14 = version 0.40
- add legend toggle
- remove magnitude limiter for maemo
- fix and improve grid options
- add grid option to polar plot
- add zoom option to polar plot
- add legend to polar plot
- allow zoom out past 90 degree field of view

2008/08/21 = version 0.46
- add sky plot hardware button controls/Fn keys
- add constellation data
- add temperature/pressure/elevation to 'mephemeris.ini' file and internal calculations
- add ability to toggle sky plot window controls on/off
- rearrange sky plot window controls
- set default graphics richness down to minimal levels to improve startup time
- fix bug in date/time resets
- fix full-screen mode toggles in sky plot windows

2008/09/02 = version 0.61
- add solar sunspot image download to 'web' window
- add yearly sunrise/sunset/transit/antitransit/daylength/analemma graph options to 'object detail' window
- add widgets to set temperature/pressure/elevation to 'set location' window
- add multiple weather info downloads to 'web' window
- add local elevation download to 'web' window
- add ability to reset temperature/pressure/elevation from weather downloads
- add distance calculation to selected weather station from local location
- add weather site names to 'mephemeris.ini'
- add equation-of-time calculation to 'time' window
- add option to turn on/off object names separately
- add option to turn off star display
- change OOP structure of 'show_object_info_basic' module (gulp! risky!)
- change 'reset_location' to also reset temp/pressure/elevation
- change 'web' window to classify links
- fix (?) calculation of daylight saving time
- fix some smaller bugs re: time-setting 
- fix bug of planets not being displayed below horizon on equatorial plot
- change layout/detail of this README file to be a lot better

2008/10/08 = version 0.97
- add plot text font size setting option
- add Google static map download to Web section (two places)(highly tentative!)
- add viewpoint alter option to polar map mode (lots of work!)
- add ecliptic reference line option to plots
- add galactic reference line option to plots
- add moon plot window for 'mars/jupiter/saturn/uranus ' objects
- add controls visibility/brevity options to sky plot window
- add artificial satellites display option to sky plot window
- add partial NGC catalog plot option to sky plot window
- add Milky Way semi-transparent overlay option to sky plot window
- add 'sun compass' option (basis suggestion from a user)
- add A and B rings to saturn moon and sky plot windows
- add non-Maemo 'gpsd'-based GPS option to supplement existing Maemo 'gpsbt' option
- add image URL source information to most web window download options
- add multiple static user-selectable image download options to web window
- add image scaler for downloaded images
- add solar system plot window for 'sun' object
- add moon phase plot window for 'moon' object
- add FAQ section to the README document
- change layout of 'web' window (again) to support new options
- change to larger sizes on some web image downloads if web window is in full screen mode
- change sky map 'select/enter' option to toggle equatorial/polar instead of equirectangular/polar
- change all unnecessary window destroys to table/vbox destroys instead (less flicker)
- combine splash and main windows into one (very ugly, but it seems to work)
- remove 'rise/set' plot option from 'moon' object window (to make room for 'phase' window)

2008/10/10 = version 0.99
- implement PyGTK 'toggle' buttons on 'sky plot' window
- implement PyGTK 'radio' buttons on 'sky plot' window
- fix bug of constellation lines getting dim when grid was activated

2008/11/24 = version 1.00
- add new 'ini' file option to control the resolution of the solar system orbit plot window
- add horizontal/vertical pan/tilt option to solar system plot window
- fix bug in user-controlled timeout option for 'gpsbt'

2009/03/20 = version 1.12
- add new 'ini' file options for sources of asteroid, comet, and NEO data
- add options to plot asteroids, comets, and NEOs on both sky and solar system plots
- add menu and initial options, such as 'quit' and 'help'
- add options to edit/save 'ini' file settings
- add options to edit/save 'messier' image URL file settings
- add options to edit/save 'misc' image URL file settings
- add search options for all appropriate object types
- add better proportional planet sizes during extreme zooming
- add realistic shading, tilt, gridding, and info to the 'Moon Phase' window
- fix bug in object size not affecting some object types
- fix bug (!) of program ending when date/time direct setting is done

2009/04/10 = version 1.25
- add zoomable moon map to 'Web' window in 'Astro Images' section
- add object tracking feature to 'Sky Plot' window
- add planet trail feature to 'Solar System' plot window
- add new 'Sun Sky Angle' graph plot to 'Season Info' window
- add direct 'Sun Analemma' graph plot to 'Season Info' window
- add ability to toggle tabular object display info on 'Main' window
- add 'minute' button increment to datetime change windows
- add 'Lunar 100' feature list to 'Moon Map' and 'Moon Phase' windows
- add datetime change hardware key features to 'Moon Phase' window
- add datetime change hardware key features to 'Mars/Jupiter/Saturn/Uranus' moons windows
- add variation of 'Solar System' plot window with datetime change hardware keys
- add 'grid' function to 'Moon Phase' window
- move original 'Solar System' orbit plot window as option to new 'Solar System' plot window
- reduce time required to produce 'Rise/Set' plot by reducing data points generated
