﻿THE INTRO
---------
mephemeris
version 1.00
2008/11/24

Copyright (C) 2008 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|                            |  |
                 +------+  +----+  +----+                            |  |
                                                                     |  |
                         +------+---------+--------------------------+  |
                         |      |         |                             |
                       +---+  +---+   +-------+                         |
                       |WEB|  |SKY|   |COMPASS|                         |
                       +---+  +---+   +-------+                         |
                         |      |                                       |
               +---------+      +--+-----------+                        |
               |                   |           |                        |
      +------------------+      +-----+  +---------------+              |
      |WEB DOWNLOADERS...|      |POLAR|  |EQUIRECTANGULAR|              |
      +------------------+      +-----+  +---------------+              |
                                   |          |                         |
                                +------------------+                    |
                                |DISPLAY OPTIONS...|                    |
                                +------------------+                    |
                                                                        |
                             +------------------------------------------+
                             |            
                          +------+ 
                          |DETAIL| 
                          +------+ 
                             |
     +------------+-----------------+------------------+-------------+
     |            |                 |                  |             |
+---------+   +--------+   +-----------------+   +----------+   +----------+
|MORE INFO|   |RISE/SET|   |SOLAR SYSTEM PLOT|   |MOON PLOTS|   |MOON PHASE|
+---------+   +--------+   +-----------------+   +----------+   +----------+
                  |
              +--------+
              |ANALEMMA|
              +--------+

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! 

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.

BASIC 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 Year         = set date/time backward one calendar year
-1 Month        = set date/time backward one calendar month
-1 Day          = set date/time backward one day
-1 Hour         = set date/time backward one hour
Reset Date/Time = reset date/time back to internal date/time
+1 Hour         = set date/time forward one hour
+1 Day          = set date/time forward one day
+1 Month        = set date/time forward one calendar month
+1 Year         = set date/time forward one calendar year

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

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

Colors are used to clarify the various parameter plots:

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

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.

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

The following hardware keys are enabled on the solar system plot 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

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

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 clipping an image of
the moon with a crescent-shaped mask of the appropriate orientation and size.
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

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.

This 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.  As well, in the 'polar' display, clicking on an area 
outside the plot 'circle' has the same effect (though, of course, if the
plot is zoomed to such a degree that the circle is no longer visible, this
option is not available). 

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
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
Legend          = toggle legend display
Horizon	    	= toggle display of horizon reference line
Ecliptic	= toggle display of ecliptic reference line
Galactic	= toggle display of galactic equator reference line

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 star/messier 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
[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/ (good model for Sun compass feature)
http://jackvalmadre.wordpress.com/tag/cairo/ (tips on resizing images well for Cairo)

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 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: 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!

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'

