Please note: Some websites have links directly to the .ipk files for this program. While it is very gratifying that other people like the program enough to include a link to the .ipk file, those links will not automatically update when a newer .ipk file is uploaded. So using one of those links might cause you to install an obsolete version of the program. If your version of the code doesn't match the description below, please download the most recent version from here: [http://projects.openmoko.org/projects/orrery/]. The current version is 2.5, and the version is shown

+

Please note: Some websites have links directly to the .ipk files for this program. While it is very gratifying that other people like the program enough to include a link to the .ipk file, those links will not automatically update when a newer .ipk file is uploaded. So using one of those links might cause you to install an obsolete version of the program. If your version of the code doesn't match the description below, please download the most recent version from [http://projects.openmoko.org/projects/orrery/ here]. The current version is 2.7, and the version is shown

under the "opts" menu, at the top of the "About Orrery / Symbol Key" page.

under the "opts" menu, at the top of the "About Orrery / Symbol Key" page.

----

----

Line 13:

Line 13:

the games bundled with the openmoko rootfs. It requires no network connection,

the games bundled with the openmoko rootfs. It requires no network connection,

but does use the GPS information, by querying gpsd.

but does use the GPS information, by querying gpsd.

−

It will be converted to work with Gypsy once the dbus based software stack

−

becomes available.

The star database was extracted from the Hipparcos catalog. To ease the

The star database was extracted from the Hipparcos catalog. To ease the

Line 29:

Line 27:

Note, the screen grabs shown below were taken with the orrery running

Note, the screen grabs shown below were taken with the orrery running

atop the 2007.2 stack, because I find it easier to do a screen grab with

atop the 2007.2 stack, because I find it easier to do a screen grab with

−

that stack. The program works with 2008.x too.

+

that stack. The program works with SHR, OM2009, OM2008.x, etc. too.

== The Display ==

== The Display ==

Line 44:

Line 42:

plotted with a size about 3.5 times larger than their true angular size on

plotted with a size about 3.5 times larger than their true angular size on

the sky.

the sky.

+

+

The user may chose to have the program display the stars visible at

+

the user's location and at the current time, or at any other position on

+

the earth, or any other time between 3000 BC and 3000 AD.

The blue line near the bottom of the display is the horizon. Nothing below that line is visible, but the

The blue line near the bottom of the display is the horizon. Nothing below that line is visible, but the

Line 59:

Line 61:

not exactly evenly spaced. This is caused by the distortion

not exactly evenly spaced. This is caused by the distortion

introduced by the Transverse Mercator projection.

introduced by the Transverse Mercator projection.

+

+

If either the sun or moon is visible, you can use the planet

+

compass (under the opts menu) to quickly orient yourself with

+

an accuracy of about 1 degree,

=== Constellations Display ===

=== Constellations Display ===

−

There are two display screens defined. By default, one of them shows

+

There are two sky display screens defined. By default, one of them shows

the display shown above, and the other shows the constellations, and

the display shown above, and the other shows the constellations, and

symbolic representations of the solar system objects.

symbolic representations of the solar system objects.

Line 68:

Line 74:

The constellations are plotted in three colors. The twelve zodiac

The constellations are plotted in three colors. The twelve zodiac

−

colors are plotted in hot pink. The constellations plotted in

+

constellations are plotted in hot pink. The constellations plotted in

gold are the classical Greek constellations, as listed in Ptolomy's Almagest (apart from the zodiac constellations, which are

gold are the classical Greek constellations, as listed in Ptolomy's Almagest (apart from the zodiac constellations, which are

also in the Almagest). The only constellation from the Almagest which is not

also in the Almagest). The only constellation from the Almagest which is not

Line 82:

Line 88:

==== Displaying Asterisms ====

==== Displaying Asterisms ====

−

There are many informal constellations which are widely know, such

+

There are many informal constellations which are widely known, such

as the Big Dipper, The Summer Triangle, etc. The user can choose

as the Big Dipper, The Summer Triangle, etc. The user can choose

to display some of these unofficial constellations by selecting "Use Asterisms" from the "items" menu. If you know of some nice asterisms

to display some of these unofficial constellations by selecting "Use Asterisms" from the "items" menu. If you know of some nice asterisms

Line 90:

Line 96:

[[Image:OrreryAsterisms.png|200px|Orrery Northern Asterisms]]

[[Image:OrreryAsterisms.png|200px|Orrery Northern Asterisms]]

−

== Control Modes ==

+

== Panning / Exiting Fullscreen==

−

The orrery has two control modes, "finger mode" and "stylus mode".

+

The image

−

By default the program is in finger mode. In finger mode, the image

+

can be panned by tapping your finger in

can be panned by tapping your finger in

the bottom 1/5 of the display (excluding menus). The size of

the bottom 1/5 of the display (excluding menus). The size of

Line 104:

Line 109:

Tapping anywhere else toggles between the two screens.

Tapping anywhere else toggles between the two screens.

−

If you are in stylus mode, the view can be panned around the sky by

+

=== Selecting a New Center Azimuth ===

−

tapping the green arrows at the bottom, or the green azimuth values.

+

Panning to a new central azimuth by panning 45 degrees at a time

−

In stylus mode, to exit from fullscreen you must tap in the area

+

can be tedious. To make a large change in the display's center

−

above the upper blue line, in the region where the time and location

+

azimuth you may use the azimuth compass. To call up the azimuth

−

are displayed. Tapping anywhere else toggles between the two screens.

+

compass, tap the center of the finger-pan area (bottom 1/5 of

+

the display) or press (long tap) anywhere within the finger pan

+

area. The compass shown below will appear:

+

+

[[Image:OrreryAzCompass.png|200px|Orrery Azimuth Compass]]

+

+

You may use your finger or stylus to select another center

+

azimuth. Keep you finger pressed to the display as you select

+

your new center azimuth - the selected azimuth will be shown by

+

a white pointer on the inside of the compass circle. Once you release pressure on the screen,

+

the compass will disappear, and the display will be redrawn.

−

There is a check box in the opts menu which allows you to turn finger mode on and off.

+

The azimuth compass cannot be accessed if the display is zoomed.

One may enter fullscreen mode by tapping the FS button at the

One may enter fullscreen mode by tapping the FS button at the

Line 124:

Line 139:

=== opts ===

=== opts ===

−

==== Toggles ====

+

−

The opts menu allows you to toggle between finger and stylus mode.

+

−

It also has a checkbox labeled "Save All Changes". If that box is

+

−

checked, all changes you make within the menus are saved to flash

+

−

memory when you click the "OK" button. If "Save All Changed" is not

+

−

selected, you must click the "Save to Configuration File" to save

+

−

changed configurations to flash - clicking "OK" makes the changes

+

−

active for the current session, but does not save to flash.

+

==== Flashlight Modes ====

==== Flashlight Modes ====

Line 193:

Line 201:

The This Moon's Moons page shows the phase of the moon for each day

The This Moon's Moons page shows the phase of the moon for each day

of a particular month. By default, the current month is shown, but

of a particular month. By default, the current month is shown, but

−

one may use the arraw buttons to pan through the months.

+

one may use the arrow buttons to pan through the months.

[[Image:OrreryMonthlyMoons.png|200px|Monthly Moon Calendar]]

[[Image:OrreryMonthlyMoons.png|200px|Monthly Moon Calendar]]

+

+

Both moon calendars show "Blue Moons", which are (according to the most

+

commonly used definition) the second full moon in a calendar month which

+

has two full moons. Both images above show the Blue Moon which falls

+

on New Year's Eve, 2009.

To exit the Moon Calendar displays, just tap the screen anywhere.

To exit the Moon Calendar displays, just tap the screen anywhere.

+

+

==== Meteor Showers ====

+

This display shows information for all the meteors showers which

+

will occur during the current year. Remember that to see a meteor

+

shower, you must travel to a site that has a very dark sky. In

+

a city, few meteors will be seen even during a shower.

+

+

[[Image:OrreryShowerTable.png|200px|Meteor Showers]]

+

+

The items

+

shown on the Meteor Showers page are 1) The name of the meteor

+

shower 2) the abbreviation used for this shower when its radiant

+

is plotted on the sky display 3) the expected number of meteors

+

per hour - this is the maximum you will see under the best circumstances

+

with a very dark sky and the shower radiant directly overhead

+

on the date of the shower maximum. If the rate entry says "Var", that

+

means the rate is variable; such shower are not apt to show

+

a large number of meteors per hour. 4) the range of dates during

+

which the shower will occur 5) the date at which the shower shows

+

the maximum number of meteors 6) the typical velocity of the

+

showers meteors in km/sec - larger numbers lead to brighter, bluer

+

meteors 7) the percentage of the moon's disk which is illuminated

+

on the date of shower maximum - full moon = 100%. A minus sign

+

following the percentage means the moon is waning, a plus sign

+

means it is waxing. Moonlight greatly interferes with seeing

+

meteors 8) the number of dark hours on the date of the shower

+

maximum - defined as the time during which the sun is more than

+

12 degrees below the horizon, and the moon is far enough below

+

the horizon to not appreciably brighten the sky.

+

+

The Meteor Showers page shows information for all showers, the

+

large majority of which are really minor events. Even when a

+

meteor shower is not occurring, you can expect to see 4 to 10 meteors

+

per hour. Many of the showers listed do not even double that

+

background rate, and are of interest only to serious meteor

+

enthusiasts. If you just want to go out and see some meteors

+

for fun, it's best to select a shower with a rate of at least 50

+

meteors per hour, and to watch it on or very near the date of the

+

shower's maximum.

+

+

Each line of the display describes a separate shower. If the

+

shower currently in progress, the line is shown in green - bright

+

green if there will be 2 or more hours of dark sky tonight, and

+

dark green otherwise. If the shower is not currently underway,

+

it will be shown in a cream color if on the night of the shower's maximum, the sky will be dark for at least 2 hours. Otherwise

+

the shower information will be shown in grey, indicating that this

+

year is not a good one to observe that particular shower.

+

+

At the bottom of the Meteor Showers page is shown the number of

+

dark sky hours to expect tonight. In this context, "tonight"

+

means the upcoming night if the sun is currently above the horizon,

+

or the current night, if the sun is below the horizon.

+

+

If you wish to get meteor shower information for a different year,

+

simply change in year using the time menu.

+

+

Many thanks to the International Meteor Organization

+

(http://www.imo.net/imo/intro)

+

for permission to use their data to produce the meteor shower

+

related displays.

==== Planet Compass ====

==== Planet Compass ====

Line 229:

Line 302:

==== Solar System ====

==== Solar System ====

+

The program can display the relative planet positions in two

+

different ways. In both cases, the view is from the north looking down,

+

with the direction of the Vernal Equinox to the left of the screen

+

(marked with the vernal equinox symbol, and an arrow). At the

+

time of the vernal equinox, the earth will be at the 3 o'clock position

+

in its orbit, so that the Sun will appear at the vernal equinox

+

position.

===== Schematic Solar System View =====

===== Schematic Solar System View =====

This button presents a schematic view of the Solar System, showing

This button presents a schematic view of the Solar System, showing

Line 251:

Line 331:

if any of the planet orbits were completely shown. Because Neptune's

if any of the planet orbits were completely shown. Because Neptune's

orbit is nearly 100 times larger than Mercury's, it is not possible to

orbit is nearly 100 times larger than Mercury's, it is not possible to

−

display all of the planet orbits simultaneously. There are "Zoom in"

+

display all of the planet orbits simultaneously. There are "Zoom In"

−

and "Zoom out" buttons which allow you to select which proper subset of

+

and "Zoom Out" buttons which allow you to select which proper subset of

planet orbits is shown. The current position of each planet in its

planet orbits is shown. The current position of each planet in its

orbit is shown. Also plotted are grey lines connecting the Sun to

orbit is shown. Also plotted are grey lines connecting the Sun to

Line 302:

Line 382:

you may push that button to save it in the menu labeled "Private".

you may push that button to save it in the menu labeled "Private".

That menu is initially empty.

That menu is initially empty.

+

+

If you use the GPS position feature, the number of satellites tracked,

+

and the number of satellites used for the most recent position fix will

+

be shown on the top text line (after the longitude and latitude). Note that the orrery only checks for a new position once every one minute by default, so you might have a fix with, for example, tangogps before the new position is displayed on the orrery. You can force the orrery to

+

look for a new position by forcing a screen redraw. If the gps unit stops producing new position fixes, the most recent fix position will be used, and the word "stale" will be displayed next to the longitude and latitude.

==== How to change the default location from Cambridge MA ====

==== How to change the default location from Cambridge MA ====

Line 342:

Line 427:

5 = Galaxy. The "mag" is the visual magnitude. The

5 = Galaxy. The "mag" is the visual magnitude. The

orrery program currently does nothing with the visual magnitude, but future versions may use it.

orrery program currently does nothing with the visual magnitude, but future versions may use it.

+

+

==== Meteor Radiants ====

+

If you select Meteor Radiants, then the radiant position for any

+

meteor showers which are now occurring will be plotted.

+

The radiant is the position in the sky from which meteors seem

+

to emerge during a shower - it's the best place in the sky to

+

look for meteors. The radiant is plotted in

+

white if more than 50 meteors per hour are expected under optimal

+

viewing conditions, cream-color if 20 or more meteors per hour

+

are expected, and grey if fewer then 20 meteors per hour are

+

expected. Note that these are meteor rates for the date of the

+

shower maximum - see the Meteor Showers page for more information.

+

The radiant position usually changes as the shower progresses.

+

The orrery takes that into account when plotting the radiant.

+

For example, the image below shows how the radiant for the

+

Orionids (abbreviated ORI in the sky plots) shower moves from northern Orion early in the shower

contains 83392 stars, and is complete to 9th magnitude. The orrery will

−

that the orrery will be more sluggish if you use this larger catalog.

+

be more sluggish if you choose to display stars fainter than 6.6.

−

Most people definately won't want to use it. The plot below shows

+

If you choose to display all the stars in the hipparcos_9.0.dat, by

−

Lyra with limiting magnitudes of 6.6 (left) and 9.0 (right).

+

setting the magnitude limit to 9.0, it will take about 10 seconds to

+

draw the star map.

+

+

The plot below shows Lyra with limiting magnitudes of 6.6 (left) and

+

9.0 (right).

[[Image:orreryLyraComparison.png|400px|Orrery Catalogs]]

[[Image:orreryLyraComparison.png|400px|Orrery Catalogs]]

+

+

Remember, there's no reason at all to install the hipparcos_9.0.dat

+

file unless you plan to do star gazing with binoculars or a small

+

telescope.

== System Requirements ==

== System Requirements ==

Line 498:

Line 632:

=== Supported Software Stacks ===

=== Supported Software Stacks ===

This program has been tested running atop the

This program has been tested running atop the

−

2007.2 and 2008.8 distributions. It probably will

+

2007.2, 2008.x and SHR distributions.

−

work with FSO too. It is gtk based.

+

The only stacks it will definitely not work on

+

are Android, Qtopia, and their descendants.

+

The orrery is gtk based.

−

==== A note about FSO ====

−

At least some versions of FSO do not include the

−

file /usr/lib/libpopt.so.0 . orrery uses that

−

file, and will not run without it. If you cannot

−

get orrery to run on FSO, try issuing the command

−

<pre>

−

opkg install libpopt0

−

</pre>

−

−

and then launch orrery again.

=== Memory Requirements ===

=== Memory Requirements ===

Line 526:

Line 652:

.ipk files for this program are now available for both the 2007.2

.ipk files for this program are now available for both the 2007.2

and 2008.8 stacks, at the gForge site. It is much easier to install

and 2008.8 stacks, at the gForge site. It is much easier to install

−

than it used to be. The latest .ipk files can be found here:

+

than it used to be. The latest .ipk files can be found

−

[http://projects.openmoko.org/projects/orrery/].

+

[http://projects.openmoko.org/projects/orrery/ here].

== Known Bugs ==

== Known Bugs ==

Line 535:

Line 661:

you pan a zoomed region so that the zenith falls within it,

you pan a zoomed region so that the zenith falls within it,

the orrery goes nuts.

the orrery goes nuts.

+

+

=== Landscape display mode doesn't work well ===

+

The Orrery program works poorly when the phone's display is in

+

landscape mode. The reason this

+

has not been fixed is that the sky projection used, Transverse

+

Mercator, does not work well with the landscape aspect ratio; there

+

is too much distortion at the edges. The fix for landscape mode

+

will require using a different projection in that orientation. It's

+

on the todo list.

'''Send more bug reports!'''

'''Send more bug reports!'''

Line 540:

Line 675:

== Revision(ist) History ==

== Revision(ist) History ==

−

Version 2.5:

+

Version 2.7:

<pre>

<pre>

New user features:

New user features:

−

Added a to-scale Solar System view, which

+

Monthly moon calendar now uses moon images.

−

shows the positions of the planets to

+

Also, both moon calendars now show "Blue

−

proper scale, with elliptical orbits.

+

Moons", using the common definition that

+

a Blue Moon is the second full moon in a

+

calendar month.

−

Added the ability to display common

+

Enlarged and re-arranged buttons on the

−

asterisms, rather than official IAU

+

"opts" page, for enhanced finger

−

defined constellations. Official

+

friendliness.

−

constellations are still shown by default.

+

−

Improved handling of the faint star catalog,

+

Got rid of "stylus mode". The program is

−

so that the normal catalog is used if you

+

always in finger mode now. There was

−

chose to display only stars visible to the

+

never a significant difference between the

−

unaided eye, but if you have installed the

+

two modes anyway.

−

faint star catalog, it will be used if you

+

−

choose to display stars that require

+

−

binoculars or a small telescope to see.

+

−

Added a display of the number of satellites

+

The program now always saves configuration

−

being tracked and being used for the last

+

changes in nonvolatile memory. This is

−

fix, which is displayed when GPS position

+

the standard behavior for handheld

−

mode is active. This was requested by a

+

applications.

−

user.

+

Bug Fixes:

Bug Fixes:

−

In version 2.4, the Solar System View time

+

Build-related files completely redone so

−

increments were always 1 day too small, which

+

as to use GNU autotools properly.

−

made the +-1 day buttons do nothing at all.

+

−

That has been fixed.

+

Program no longer crashes if run on a

+

phone who's locale is set to a language

+

which uses a comma for the decimal point.

−

Fixed a bug which lead to a nonterminating

+

Improved handling of zoom gestures which

−

loop if the moon phases were calculated at

+

originate in the panning area. Before

−

a time within a few hours of the new moon.

+

this fix, it was difficult or impossible

+

to zoom an area near the horizon, because

+

such a gesture would be interpreted as a

+

"press" in the panning area, which would

+

call up the azimuth compass.

−

Added a trap for the SIGPIP signal, so that

+

Removed the call to the popt library that

−

a shutdown of the socket to gpsd will no

+

parsed the command line arguments. This

−

longer crash the program. Now the

+

caused problems, because not all Freerunner

−

gpsd connection will be re-established, if

+

software stacks shipped with the popt

−

possible.

+

library. The program now parses its

+

command line arguments with no call to any

+

library.

−

Cleaned up planet-related code.

+

Fixed a bug which made it difficult to

+

use the arrows at the bottom of the monthly

+

moon calendar to change months.

</pre>

</pre>

Line 597:

Line 739:

Screenshot=OrreryWithMenuTabs.png|

Screenshot=OrreryWithMenuTabs.png|

Homepage=http://projects.openmoko.org/projects/orrery/|

Homepage=http://projects.openmoko.org/projects/orrery/|

−

TestedOn=Om 2008.8|

+

TestedOn=Om 2007.2, 2008.12 and SHR|

PackageName=orrery

PackageName=orrery

}}

}}

Latest revision as of 19:58, 10 January 2010

Orrery is one of the applications that runs on the Openmoko Phones. For a list of all applications, visit Applications

Please note: Some websites have links directly to the .ipk files for this program. While it is very gratifying that other people like the program enough to include a link to the .ipk file, those links will not automatically update when a newer .ipk file is uploaded. So using one of those links might cause you to install an obsolete version of the program. If your version of the code doesn't match the description below, please download the most recent version from here. The current version is 2.7, and the version is shown
under the "opts" menu, at the top of the "About Orrery / Symbol Key" page.

The orrery is a simple open-source application for the Openmoko platform
which displays the night (and day!) sky. It is nowhere near as elaborate as, for
example Google Sky or xephem. It is intended to be a small application
that will have a storage footprint comparable to a ringtone, or one of
the games bundled with the openmoko rootfs. It requires no network connection,
but does use the GPS information, by querying gpsd.

The star database was extracted from the Hipparcos catalog. To ease the
computational load, the coordinates are not precessed or nutated before
being displayed. Orbital elements are used,
rather than ephemerides, to calculate planet positions. Although
this is less accurate, it dramatically reduces the memory
footprint. The planet positions are accurate to a few arc
minutes, from 3000 BC to 3000 AD. Since the scale
on the default display is approximately 8 arc minutes
per pixel, these small errors are imperceptible, unless a very
large zoom factor is used.

Note, the screen grabs shown below were taken with the orrery running
atop the 2007.2 stack, because I find it easier to do a screen grab with
that stack. The program works with SHR, OM2009, OM2008.x, etc. too.

The image above shows the default display - all stars visible to the unaided
eye, with colors for the brightest ones. It's displayed with a
Transverse Mercator projection (similar to Norton's Star Atlas) which works
well with the VGA aspect ratio in portrait mode.
It's a conformal transformation, so the
constellations have about the right shapes. The Sun, Moon and planets are
plotted, and the Moon is shown with the proper phase. The Sun and Moon are
plotted with a size about 3.5 times larger than their true angular size on
the sky.

The user may chose to have the program display the stars visible at
the user's location and at the current time, or at any other position on
the earth, or any other time between 3000 BC and 3000 AD.

The blue line near the bottom of the display is the horizon. Nothing below that line is visible, but the
program plots objects there anyway, because it is often
useful to know which objects are just about to rise, and
which ones have recently set.

The green numbers at the bottom are the azimuth values. The
azimuth is measured along the horizon, from north through east.
So the azimuth of due north is 0, east is 90, south is 180
and west is 270 degrees. By using these azimuth values, the
orrery can be used as a celestial compass, if the sky above you
is at least partially clear. Notice that the azimuth values are
not exactly evenly spaced. This is caused by the distortion
introduced by the Transverse Mercator projection.

If either the sun or moon is visible, you can use the planet
compass (under the opts menu) to quickly orient yourself with
an accuracy of about 1 degree,

There are two sky display screens defined. By default, one of them shows
the display shown above, and the other shows the constellations, and
symbolic representations of the solar system objects.

The constellations are plotted in three colors. The twelve zodiac
constellations are plotted in hot pink. The constellations plotted in
gold are the classical Greek constellations, as listed in Ptolomy's Almagest (apart from the zodiac constellations, which are
also in the Almagest). The only constellation from the Almagest which is not
plotted is Argo Navis, which is not one of the official modern
constellations (Argo Navis was broken up into the modern constellations
Carina, Puppis and Vela). The remaining constellations, plotted in blue, where
added during the last few hundred years.

In addition to constellation names and figures, three great circles, the Celestial Equator
(light yellow), Ecliptic (red) and Galactic Plane (blue-green), are shown.
Solar system objects are shown symbolically (see Mercury, Venus,
the Moon and the Sun in the above image).

There are many informal constellations which are widely known, such
as the Big Dipper, The Summer Triangle, etc. The user can choose
to display some of these unofficial constellations by selecting "Use Asterisms" from the "items" menu. If you know of some nice asterisms
that the orrery does not yet display, please send them to orrery.moko@gmail.com, and I'll include them in a future release if I can. The image below shows the Big Dipper and Little Dipper
asterisms.

The image
can be panned by tapping your finger in
the bottom 1/5 of the display (excluding menus). The size of
the panning step is controlled by how close your finger is
to the edge of the display. If you tap in the center, it pans
by 0 degrees, and nothing happens. If you tap near the
left or right edges, it
pans by the maximum allowed amount, +-45 degrees. Pan steps are
quantized in increments of 5 degrees. You may exit fullscreen mode
by tapping anywhere in the upper 1/5 of the display area.
Tapping anywhere else toggles between the two screens.

Panning to a new central azimuth by panning 45 degrees at a time
can be tedious. To make a large change in the display's center
azimuth you may use the azimuth compass. To call up the azimuth
compass, tap the center of the finger-pan area (bottom 1/5 of
the display) or press (long tap) anywhere within the finger pan
area. The compass shown below will appear:

You may use your finger or stylus to select another center
azimuth. Keep you finger pressed to the display as you select
your new center azimuth - the selected azimuth will be shown by
a white pointer on the inside of the compass circle. Once you release pressure on the screen,
the compass will disappear, and the display will be redrawn.

The azimuth compass cannot be accessed if the display is zoomed.

One may enter fullscreen mode by tapping the FS button at the
bottom left of the display.

The "White Flashlight" button paints the entire screen white, and the
"Red Flashlight" button paints the entire screen red. Both may
be used as a flashlight, but the red one is best if you are trying
to preserve your night vision.

The "Sun and Moon Information" button displays a page giving the
sun and moon positions, rise and set times, phase etc for five
days, centered on today:

The highlighted date is the current UT date (unless the time menu
has been used to select a different time). The highlighted
rise and set times are the next ones which will occur at your
location. Of course, that may be on a different UT date (for
example, during daylight hours, the next sunrise will be tomorrow).
The times are shown as Universal Times (UT), which may annoy people,
UT is used because the orrery allows you to select any location on the
earth, and any time from 3000 BC until 3000 AD. It would be very
difficult to keep track of all the timezone, daylight savings change
dates, etc for that time range! So I have wimped out, and displayed
UT, which is always reasonably well defined.

The current sun and moon positions shown are geocentric - no
topocentric correction has been applied. However topocentric
corrections are applied when rise and set times are calculated,
so they should be reasonably accurate for a specific location on earth.

The moon illumination percentage shown on the line with the
rising and setting times is the value at transit. The
illumination shown on the line that has the drawing of the
moon phase is the illumination percentage at this moment.

This page also shows the UT date and time of the four major moon
phases (New, First Quarter, Full and Last Quarter) for a time span
of 17 lunar months, centered on the current time (which of course
can be changed with the time menu). The next time and date when
each phase will occur is highlighed.

The Big Moon Calendar is a graphic display of the phase of the moon for
each day from 10 months before the current month, until 10 months after
the current month (roughly 640 days), as shown below:

Each column shows one month, and the day number is shown for each row.
At the top and bottom of each column is shown the first letter of the
name of the month
shown in the column. Two vertical green lines separate years.
The current Universal Time date is outlined in a red box.

The This Moon's Moons page shows the phase of the moon for each day
of a particular month. By default, the current month is shown, but
one may use the arrow buttons to pan through the months.

Both moon calendars show "Blue Moons", which are (according to the most
commonly used definition) the second full moon in a calendar month which
has two full moons. Both images above show the Blue Moon which falls
on New Year's Eve, 2009.

This display shows information for all the meteors showers which
will occur during the current year. Remember that to see a meteor
shower, you must travel to a site that has a very dark sky. In
a city, few meteors will be seen even during a shower.

The items
shown on the Meteor Showers page are 1) The name of the meteor
shower 2) the abbreviation used for this shower when its radiant
is plotted on the sky display 3) the expected number of meteors
per hour - this is the maximum you will see under the best circumstances
with a very dark sky and the shower radiant directly overhead
on the date of the shower maximum. If the rate entry says "Var", that
means the rate is variable; such shower are not apt to show
a large number of meteors per hour. 4) the range of dates during
which the shower will occur 5) the date at which the shower shows
the maximum number of meteors 6) the typical velocity of the
showers meteors in km/sec - larger numbers lead to brighter, bluer
meteors 7) the percentage of the moon's disk which is illuminated
on the date of shower maximum - full moon = 100%. A minus sign
following the percentage means the moon is waning, a plus sign
means it is waxing. Moonlight greatly interferes with seeing
meteors 8) the number of dark hours on the date of the shower
maximum - defined as the time during which the sun is more than
12 degrees below the horizon, and the moon is far enough below
the horizon to not appreciably brighten the sky.

The Meteor Showers page shows information for all showers, the
large majority of which are really minor events. Even when a
meteor shower is not occurring, you can expect to see 4 to 10 meteors
per hour. Many of the showers listed do not even double that
background rate, and are of interest only to serious meteor
enthusiasts. If you just want to go out and see some meteors
for fun, it's best to select a shower with a rate of at least 50
meteors per hour, and to watch it on or very near the date of the
shower's maximum.

Each line of the display describes a separate shower. If the
shower currently in progress, the line is shown in green - bright
green if there will be 2 or more hours of dark sky tonight, and
dark green otherwise. If the shower is not currently underway,
it will be shown in a cream color if on the night of the shower's maximum, the sky will be dark for at least 2 hours. Otherwise
the shower information will be shown in grey, indicating that this
year is not a good one to observe that particular shower.

At the bottom of the Meteor Showers page is shown the number of
dark sky hours to expect tonight. In this context, "tonight"
means the upcoming night if the sun is currently above the horizon,
or the current night, if the sun is below the horizon.

If you wish to get meteor shower information for a different year,
simply change in year using the time menu.

Many thanks to the International Meteor Organization
(http://www.imo.net/imo/intro)
for permission to use their data to produce the meteor shower
related displays.

The Planet Compass page graphically shows where each of the planets
is at the current time.

The image has one complete circle, which shows the planet azimuth,
and one semicircle, which shows the elevation.

The azimuth circle has blue
triangles marking the four cardinal points: North, South, East and West.
There are small tick lines at the NE, SE, SW and NW directions, as
well as a small dot every 10 degrees. The planet symbols are shown
with lines projecting to their current azimuth. The line is white if
the planet is above the horizon, and red if it is below the horizon.

The elevation semicircle has blue triangles marking the directions
of the Zenith, Horizon and Nadir. Small dots are shown every 10
degrees, and there are short lines at +-45 degrees.
As with the azimuth circle, lines connect the planet
symbols to their current elevations.

Below the compass graphic, the name, Hour Angle (HA) rising time
and azimuth, transit time and elevation, and setting time and
azimuth is shown for each planet. The name and HA of the planet is
highlighted if the planet is above the horizon. The time of
the next event - rising, transiting or setting, is also highlighted
for each planet.

The program can display the relative planet positions in two
different ways. In both cases, the view is from the north looking down,
with the direction of the Vernal Equinox to the left of the screen
(marked with the vernal equinox symbol, and an arrow). At the
time of the vernal equinox, the earth will be at the 3 o'clock position
in its orbit, so that the Sun will appear at the vernal equinox
position.

This button presents a schematic view of the Solar System, showing
the locations of the earth, the earth's moon and the other planets
in their orbits around the sun. The view is schematic in the sense
that the orbit radii and planet sizes are not shown to scale. However
the positions of the objects within their orbits are correct
(the heliocentric ecliptic longitudes are correct).

Several buttons are drawn at the bottom of the display, which allow you to
show an animation of the motion of the Solar System objects for several
time increments. Showing the motion of planets in this way is what
mechanical orreries do.

This button displays the Solar System with the planet orbits shown with
the proper relative sizes. The orbits are also plotted as ellipses in
this display, with the correct eccentricity and orientation. The
moon is not plotted, because it would be too close to the earth to display
if any of the planet orbits were completely shown. Because Neptune's
orbit is nearly 100 times larger than Mercury's, it is not possible to
display all of the planet orbits simultaneously. There are "Zoom In"
and "Zoom Out" buttons which allow you to select which proper subset of
planet orbits is shown. The current position of each planet in its
orbit is shown. Also plotted are grey lines connecting the Sun to
each orbit, terminating with a white dot at the position of the
planet's perihelion (where it is closest to the sun in its orbit).
The image below shows the display when the outermost plotted planet is
Mars. Note that the orbits of Mercury and Mars are quite noncircular:

The time menu allows you to specify an
explicit time between 3000 BC and 3000 AD, or the current
time. If "Now" is selected, the current time is used and the display updates
automatically once per minute. If a specific time is selected,
it is shown in red, to remind you that the display is not
going to update automatically as time passes. The time may be
specified as a calendar date, or as a Julian Date.

The Julian Date is a less ambiguous way of entering times
in the distant past than using a calendar date, because of the
differing calendar systems in use worldwide before the late 16th
century. For example, the date October 10, 1582 never occurred in
some European countries. Many countries have gaps in their calendars
with missing dates when they adopted the Gregorian Calendar.

The place menu allows you to select the GPS-derived location,
a user specified latitude and longitude, or a city or
astronomical observatory selected from a menu. The lists of
locations are stored in ASCII text files under the menus subdirectory
of the program installation area on your phone. You may
save your selected location, by hitting the "Save
to Configuration File" button, so it will be used the
next time you start the orrery. If you would like
to add additional cities etc to one of the menus, you may simply
edit one of the menu files, and add the name, latitude and longitude
of the location. You will need to restart the orrery program for
your new locations to become available.

To use the menu option, first select the "place" menu. Then, select the "Menu" checkbox at the top right of the screen. You will notice that the "Region" menu will then become highlighted. Push "Region", and then select the continent or category of the area you want the sky to be shown for. Once you have selected a region, a pull-down menu with the name of that region will appear next to the "Region" button. Use that new menu to select your city. After the city is selected, its name will appear next to the regional menu.

If you select a "Custom" or "Menu" location, a button labeled
"Save in Private Menu" will appear. After you select your new position,
you may push that button to save it in the menu labeled "Private".
That menu is initially empty.

If you use the GPS position feature, the number of satellites tracked,
and the number of satellites used for the most recent position fix will
be shown on the top text line (after the longitude and latitude). Note that the orrery only checks for a new position once every one minute by default, so you might have a fix with, for example, tangogps before the new position is displayed on the orrery. You can force the orrery to
look for a new position by forcing a screen redraw. If the gps unit stops producing new position fixes, the most recent fix position will be used, and the word "stale" will be displayed next to the longitude and latitude.

To change the default location, just use the place menu to select a new
location as described above, and be sure to push the "Save to Configuration File" button. That will make the currently selected position your new default location, which will be used whenever the program is started, unless GPS is selected.

The display menu allows you to configure the display, selecting
such things as the faintest magnitude object displayed, whether constellation
lines are plotted, whether or not star names are displayed, etc.

If you select "Deep Sky Obs" from the items menu, you will
be shown some of the brightest Deep Sky Objects. Deep Sky
Objects are objects such as galaxies, expelled envelopes of
dying stars, clusters of young stars and lumious gas. A few,
such as the Andromeda Galaxy, are visible to the unaided eye.
Many more are visible with binoculars or a small telescope.
The orrery shows all messier objects, and many other
well known bright nebulae and star clusters.
The image bellow shows the Messier objects in Sagittarius.

You may add your own list of deep sky objects to be
plotted. Simply create a file within the directory
/usr/share/orrery/deepSky/ with any name. The
file should contain lines of text with the format

name HH MM SS.SS DD MM SS.S type mag

where name is the object name, which may not include
white space, HH MM SS.SS is the Right Ascension,
DD MM SS.S is the declination (do not include a + sign
for positive declinations) "type" is an integer
specifying the type of object. 0 = Supernova Remnant,
1 = Globular Cluster, 2 = Open CLuster, 3 = Diffuse
Nebula (HII region, etc), 4 = Planetary Nebula, and
5 = Galaxy. The "mag" is the visual magnitude. The
orrery program currently does nothing with the visual magnitude, but future versions may use it.

If you select Meteor Radiants, then the radiant position for any
meteor showers which are now occurring will be plotted.
The radiant is the position in the sky from which meteors seem
to emerge during a shower - it's the best place in the sky to
look for meteors. The radiant is plotted in
white if more than 50 meteors per hour are expected under optimal
viewing conditions, cream-color if 20 or more meteors per hour
are expected, and grey if fewer then 20 meteors per hour are
expected. Note that these are meteor rates for the date of the
shower maximum - see the Meteor Showers page for more information.
The radiant position usually changes as the shower progresses.
The orrery takes that into account when plotting the radiant.
For example, the image below shows how the radiant for the
Orionids (abbreviated ORI in the sky plots) shower moves from northern Orion early in the shower
(Oct 2) to Gemini late in the shower (Nov 5):

The magnitude scale for expressing the brightness of
stars and planets is explained here. It is one of the oldest
measurement systems still in use today.

By default, the orrery displays every star a person with excellent
eyesight located in a very dark area on a moonless night can see.
If your observing conditions are less ideal than that, it can be
helpful to use the "Mag. Limit" field in the item menu to lower
the limit of the faintest object plotted. The plot below shows
the "Summer Triangle" region plotted with the default 6.6 limiting
magnitude on the left, and a 5.0 limiting magnitude on the right.

If you tap "Save to Configuration File" your new magnitude limit
will be the default the next time orrery is run.

If you press the display area, and withdraw your finger or stylus
within 0.25 seconds, that gesture is considered a tap.

Tapping in the lower 1/5 of the display area will pan the display in
azimuth. If you are in fullscreen mode, then tapping in the upper 1/5
of the display will take you out of fullscreen mode. Tapping anywhere
else toggles between the default screen and the constellation screen.

If you press the screen and trace out a roundish figure, and remain
in contact with the screen for more than 0.25 seconds, and if
the figure encloses a nontrivial (> 300 pixels) area, the gesture
is considered to be a zoom. As you move your finger or
stylus, the region you are outlining will be shown
as a green dotted line. After you release your finger
from the display, a red box will be shown.
The red box is a rectangle with the aspect ratio of the
display area, and the same area and centroid as the region you
traced out with your finger. The display will then be zoomed so
that the region in the red box fills the display area:

The image above shows the display immediately after the zoom gesture
has been made (left) and after the zoom has become active (right).
One may zoom an image which has already been zoomed.

Zooming can do some non-intuitive things, especially if you zoom near
the upper left or upper right of the display. This is because
the orrery's transverse mercator projection always has a line of
constant azimuth in the center. This means that something zoomed
at the edge of the display area will be rotated as it is zoomed, and
some of the stars you wish to display may be rotated out of the
display area. It is best, especially if you are zooming in on
an area near the zenith, to first pan the display so that the region
is near the center of the display, before zooming. The nice
thing about the transverse mercator projection is that a zoomed
area is displayed with the orientation it would have if you were
directly facing it at the time indicated by the display.

If your zoom area includes the zenith, the display may do weird
things. This is a bug.

A pan is like a zoom, but with a more linear, rather than roundish
gesture. A pan can be used to move the center of a zoomed region.
It has no effect if the display area is not zoomed. After you
release your finger or stylus following a zoom gesture, orrery
will show the region you traced out in green, and will draw a red
arrow showing the direction and size of the pan. After that,
the display is re-drawn with the new center position.

The image above shows the display immediately after a pan gesture
has been made (left) and following the re-drawing of the display
area (right).

If you push down on the touchscreen for more than 0.25 seconds, and
do not move your finger or stylus significantly while making contact,
you will have made a press gesture. Since one almost always moves
one's finger a little by while pressing the screen, some small motion
is allowed during a press gesture. This means that a zoom or pan
gesture cannot be arbitrarily small, because it will be interpreted
as a press.

If the screen is zoomed, then the press gesture unzooms it. If the
screen is already unzoomed, then the press gesture has the same
effect as a tap gesture.

The dotted yellow line is the Celestial Equator, the intersection of
the Earth's equatorial plane with the celestial sphere. The red
dotted line is the Ecliptic. The Ecliptic is the intersection
of the Earth's orbital plane with the celestial sphere. The
Ecliptic is also the path of the Sun across the sky, and the intersection
points between the Celestial Equator and the Ecliptic are where the
Sun is at the time of an equinox. Constellations lying along the
Ecliptic plane are zodiac constellations. The planets and the Moon
are always near, but usually not exactly on, the Ecliptic.
The blue-green dotted line is
the Galactic Plane, the intersection of the plane of the Milky Way's
disk and the celestial sphere.

The default sky catalog used by the orrery contains every star
you can see with your unaided eye, even if you have
exceptionally good eyesight, and are located in a
very dark area on a moonless night. If you wish to display stars
which require binoculars or a small telescope to be seen, you can
download the file hipparcos_9.0.dat from the
orrery area of the gForge site.

You must load this file onto your phone, of course, but you
probably will want to store it on the microSD card, because the file
is so large (3 megabytes). You must make a softlink in the top
of the orrery files area called "faintStars", which will point to
where the hipparcos_9.0.dat is actually stored. For example,
if you do the default opkg installation of the orrery (or use
a script like Kustomizer), and if you store the hipparcos_9.0.dat
at the top directory of your microSD card, you must issue the following
command to make the faint star catalog usable:

> ln -s /media/card/hipparcos_9.0.dat /usr/share/orrery/faintStars

You must restart the orrery after making this softlink.

Once the new catalog and softlink are in place, the orrery will
allow you to change the maximum magnitude (using the item menu)
all the way up to magnitude 9.0. Note that the default, smaller catalog
is still used if the maximum magnitude is no larger than 6.6, so you
may used the orrery with the faint star catalog, and not incur and
performance penalty as long as you restrict yourself to stars no
fainter than 6.6. The faint (mag > 6.6) stars cannot be displayed
in constellation mode.

The default orrery star catalog contains 9931 stars. hipparcos_9.0.dat
contains 83392 stars, and is complete to 9th magnitude. The orrery will
be more sluggish if you choose to display stars fainter than 6.6.
If you choose to display all the stars in the hipparcos_9.0.dat, by
setting the magnitude limit to 9.0, it will take about 10 seconds to
draw the star map.

This program will run on either the neo1973 (gta01)
or the FreeRunner (gta02). Users of the neo1973
may wish to move the files to the microSD card, to
save space in the limited builtin flash memory
(see below).

This program requires 630 kbytes of storage space in the phone's
builtin flash storage or microSD card. By default, most of
the files (everything except the .desktop file, the launch
icon and the executable) are stored under /usr/share/orrery.
This directory tree may be moved elsewhere, if the new
location is specified with the -d switch on the orrery
invocation line in the .desktop file. The .desktop
file resides in /usr/share/applications .

The Orrery program works poorly when the phone's display is in
landscape mode. The reason this
has not been fixed is that the sky projection used, Transverse
Mercator, does not work well with the landscape aspect ratio; there
is too much distortion at the edges. The fix for landscape mode
will require using a different projection in that orientation. It's
on the todo list.

New user features:
Monthly moon calendar now uses moon images.
Also, both moon calendars now show "Blue
Moons", using the common definition that
a Blue Moon is the second full moon in a
calendar month.
Enlarged and re-arranged buttons on the
"opts" page, for enhanced finger
friendliness.
Got rid of "stylus mode". The program is
always in finger mode now. There was
never a significant difference between the
two modes anyway.
The program now always saves configuration
changes in nonvolatile memory. This is
the standard behavior for handheld
applications.
Bug Fixes:
Build-related files completely redone so
as to use GNU autotools properly.
Program no longer crashes if run on a
phone who's locale is set to a language
which uses a comma for the decimal point.
Improved handling of zoom gestures which
originate in the panning area. Before
this fix, it was difficult or impossible
to zoom an area near the horizon, because
such a gesture would be interpreted as a
"press" in the panning area, which would
call up the azimuth compass.
Removed the call to the popt library that
parsed the command line arguments. This
caused problems, because not all Freerunner
software stacks shipped with the popt
library. The program now parses its
command line arguments with no call to any
library.
Fixed a bug which made it difficult to
use the arrows at the bottom of the monthly
moon calendar to change months.

Views

Personal tools

Orrery is one of the applications that runs on the Openmoko Phones. For a list of all applications, visit Applications

Please note: Some websites have links directly to the .ipk files for this program. While it is very gratifying that other people like the program enough to include a link to the .ipk file, those links will not automatically update when a newer .ipk file is uploaded. So using one of those links might cause you to install an obsolete version of the program. If your version of the code doesn't match the description below, please download the most recent version from here: [1]. The current version is 2.5, and the version is shown
under the "opts" menu, at the top of the "About Orrery / Symbol Key" page.

Overview

The orrery is a simple open-source application for the Openmoko platform
which displays the night (and day!) sky. It is nowhere near as elaborate as, for
example Google Sky or xephem. It is intended to be a small application
that will have a storage footprint comparable to a ringtone, or one of
the games bundled with the openmoko rootfs. It requires no network connection,
but does use the GPS information, by querying gpsd.
It will be converted to work with Gypsy once the dbus based software stack
becomes available.

The star database was extracted from the Hipparcos catalog. To ease the
computational load, the coordinates are not precessed or nutated before
being displayed. Orbital elements are used,
rather than ephemerides, to calculate planet positions. Although
this is less accurate, it dramatically reduces the memory
footprint. The planet positions are accurate to a few arc
minutes, from 3000 BC to 3000 AD. Since the scale
on the default display is approximately 8 arc minutes
per pixel, these small errors are imperceptible, unless a very
large zoom factor is used.

Note, the screen grabs shown below were taken with the orrery running
atop the 2007.2 stack, because I find it easier to do a screen grab with
that stack. The program works with 2008.x too.

The Display

The image above shows the default display - all stars visible to the unaided
eye, with colors for the brightest ones. It's displayed with a
Transverse Mercator projection (similar to Norton's Star Atlas) which works
well with the VGA aspect ratio in portrait mode.
It's a conformal transformation, so the
constellations have about the right shapes. The Sun, Moon and planets are
plotted, and the Moon is shown with the proper phase. The Sun and Moon are
plotted with a size about 3.5 times larger than their true angular size on
the sky.

The blue line near the bottom of the display is the horizon. Nothing below that line is visible, but the
program plots objects there anyway, because it is often
useful to know which objects are just about to rise, and
which ones have recently set.

The orrery as a compass

The green numbers at the bottom are the azimuth values. The
azimuth is measured along the horizon, from north through east.
So the azimuth of due north is 0, east is 90, south is 180
and west is 270 degrees. By using these azimuth values, the
orrery can be used as a celestial compass, if the sky above you
is at least partially clear. Notice that the azimuth values are
not exactly evenly spaced. This is caused by the distortion
introduced by the Transverse Mercator projection.

Constellations Display

There are two display screens defined. By default, one of them shows
the display shown above, and the other shows the constellations, and
symbolic representations of the solar system objects.

The constellations are plotted in three colors. The twelve zodiac
colors are plotted in hot pink. The constellations plotted in
gold are the classical Greek constellations, as listed in Ptolomy's Almagest (apart from the zodiac constellations, which are
also in the Almagest). The only constellation from the Almagest which is not
plotted is Argo Navis, which is not one of the official modern
constellations (Argo Navis was broken up into the modern constellations
Carina, Puppis and Vela). The remaining constellations, plotted in blue, where
added during the last few hundred years.

In addition to constellation names and figures, three great circles, the Celestial Equator
(light yellow), Ecliptic (red) and Galactic Plane (blue-green), are shown.
Solar system objects are shown symbolically (see Mercury, Venus,
the Moon and the Sun in the above image).

Displaying Asterisms

There are many informal constellations which are widely know, such
as the Big Dipper, The Summer Triangle, etc. The user can choose
to display some of these unofficial constellations by selecting "Use Asterisms" from the "items" menu. If you know of some nice asterisms
that the orrery does not yet display, please send them to orrery.moko@gmail.com, and I'll include them in a future release if I can. The image below shows the Big Dipper and Little Dipper
asterisms.

Control Modes

The orrery has two control modes, "finger mode" and "stylus mode".
By default the program is in finger mode. In finger mode, the image
can be panned by tapping your finger in
the bottom 1/5 of the display (excluding menus). The size of
the panning step is controlled by how close your finger is
to the edge of the display. If you tap in the center, it pans
by 0 degrees, and nothing happens. If you tap near the
left or right edges, it
pans by the maximum allowed amount, +-45 degrees. Pan steps are
quantized in increments of 5 degrees. You may exit fullscreen mode
by tapping anywhere in the upper 1/5 of the display area.
Tapping anywhere else toggles between the two screens.

If you are in stylus mode, the view can be panned around the sky by
tapping the green arrows at the bottom, or the green azimuth values.
In stylus mode, to exit from fullscreen you must tap in the area
above the upper blue line, in the region where the time and location
are displayed. Tapping anywhere else toggles between the two screens.

There is a check box in the opts menu which allows you to turn finger mode on and off.

One may enter fullscreen mode by tapping the FS button at the
bottom left of the display.

Menus

When not in fullscreen mode, one button and four menus are displayed at the bottom of the screen.

FS

Pushing the "FS" button pops you into fullscreen mode. To exit,
tap the top 1/5th of the display (if you are in finger mode) or
the region where the location and time is displayed (in stylus mode).

opts

Toggles

The opts menu allows you to toggle between finger and stylus mode.
It also has a checkbox labeled "Save All Changes". If that box is
checked, all changes you make within the menus are saved to flash
memory when you click the "OK" button. If "Save All Changed" is not
selected, you must click the "Save to Configuration File" to save
changed configurations to flash - clicking "OK" makes the changes
active for the current session, but does not save to flash.

Flashlight Modes

The "White Flashlight" button paints the entire screen white, and the
"Red Flashlight" button paints the entire screen red. Both may
be used as a flashlight, but the red one is best if you are trying
to preserve your night vision.

Sunrise, Moonrise and Moon Phases

The "Sun and Moon Information" button displays a page giving the
sun and moon positions, rise and set times, phase etc for five
days, centered on today:

The highlighted date is the current UT date (unless the time menu
has been used to select a different time). The highlighted
rise and set times are the next ones which will occur at your
location. Of course, that may be on a different UT date (for
example, during daylight hours, the next sunrise will be tomorrow).
The times are shown as Universal Times (UT), which may annoy people,
UT is used because the orrery allows you to select any location on the
earth, and any time from 3000 BC until 3000 AD. It would be very
difficult to keep track of all the timezone, daylight savings change
dates, etc for that time range! So I have wimped out, and displayed
UT, which is always reasonably well defined.

The current sun and moon positions shown are geocentric - no
topocentric correction has been applied. However topocentric
corrections are applied when rise and set times are calculated,
so they should be reasonably accurate for a specific location on earth.

The moon illumination percentage shown on the line with the
rising and setting times is the value at transit. The
illumination shown on the line that has the drawing of the
moon phase is the illumination percentage at this moment.

This page also shows the UT date and time of the four major moon
phases (New, First Quarter, Full and Last Quarter) for a time span
of 17 lunar months, centered on the current time (which of course
can be changed with the time menu). The next time and date when
each phase will occur is highlighed.

Moon Calendars

Big Moon Calendar

The Big Moon Calendar is a graphic display of the phase of the moon for
each day from 10 months before the current month, until 10 months after
the current month (roughly 640 days), as shown below:

Each column shows one month, and the day number is shown for each row.
At the top and bottom of each column is shown the first letter of the
name of the month
shown in the column. Two vertical green lines separate years.
The current Universal Time date is outlined in a red box.

This Month's Moons

The This Moon's Moons page shows the phase of the moon for each day
of a particular month. By default, the current month is shown, but
one may use the arraw buttons to pan through the months.

To exit the Moon Calendar displays, just tap the screen anywhere.

Planet Compass

The Planet Compass page graphically shows where each of the planets
is at the current time.

The image has one complete circle, which shows the planet azimuth,
and one semicircle, which shows the elevation.

The azimuth circle has blue
triangles marking the four cardinal points: North, South, East and West.
There are small tick lines at the NE, SE, SW and NW directions, as
well as a small dot every 10 degrees. The planet symbols are shown
with lines projecting to their current azimuth. The line is white if
the planet is above the horizon, and red if it is below the horizon.

The elevation semicircle has blue triangles marking the directions
of the Zenith, Horizon and Nadir. Small dots are shown every 10
degrees, and there are short lines at +-45 degrees.
As with the azimuth circle, lines connect the planet
symbols to their current elevations.

Below the compass graphic, the name, Hour Angle (HA) rising time
and azimuth, transit time and elevation, and setting time and
azimuth is shown for each planet. The name and HA of the planet is
highlighted if the planet is above the horizon. The time of
the next event - rising, transiting or setting, is also highlighted
for each planet.

Solar System

Schematic Solar System View

This button presents a schematic view of the Solar System, showing
the locations of the earth, the earth's moon and the other planets
in their orbits around the sun. The view is schematic in the sense
that the orbit radii and planet sizes are not shown to scale. However
the positions of the objects within their orbits are correct
(the heliocentric ecliptic longitudes are correct).

Several buttons are drawn at the bottom of the display, which allow you to
show an animation of the motion of the Solar System objects for several
time increments. Showing the motion of planets in this way is what
mechanical orreries do.

To-Scale Solar System View

This button displays the Solar System with the planet orbits shown with
the proper relative sizes. The orbits are also plotted as ellipses in
this display, with the correct eccentricity and orientation. The
moon is not plotted, because it would be too close to the earth to display
if any of the planet orbits were completely shown. Because Neptune's
orbit is nearly 100 times larger than Mercury's, it is not possible to
display all of the planet orbits simultaneously. There are "Zoom in"
and "Zoom out" buttons which allow you to select which proper subset of
planet orbits is shown. The current position of each planet in its
orbit is shown. Also plotted are grey lines connecting the Sun to
each orbit, terminating with a white dot at the position of the
planet's perihelion (where it is closest to the sun in its orbit).
The image below shows the display when the outermost plotted planet is
Mars. Note that the orbits of Mercury and Mars are quite noncircular:

About Orrery / Symbol Key

This button displays an annotated list of
all the symbols used on the orrery display.

time

The time menu allows you to specify an
explicit time between 3000 BC and 3000 AD, or the current
time. If "Now" is selected, the current time is used and the display updates
automatically once per minute. If a specific time is selected,
it is shown in red, to remind you that the display is not
going to update automatically as time passes. The time may be
specified as a calendar date, or as a Julian Date.

The Julian Date is a less ambiguous way of entering times
in the distant past than using a calendar date, because of the
differing calendar systems in use worldwide before the late 16th
century. For example, the date October 10, 1582 never occurred in
some European countries. Many countries have gaps in their calendars
with missing dates when they adopted the Gregorian Calendar.

place

The place menu allows you to select the GPS-derived location,
a user specified latitude and longitude, or a city or
astronomical observatory selected from a menu. The lists of
locations are stored in ASCII text files under the menus subdirectory
of the program installation area on your phone. You may
save your selected location, by hitting the "Save
to Configuration File" button, so it will be used the
next time you start the orrery. If you would like
to add additional cities etc to one of the menus, you may simply
edit one of the menu files, and add the name, latitude and longitude
of the location. You will need to restart the orrery program for
your new locations to become available.

To use the menu option, first select the "place" menu. Then, select the "Menu" checkbox at the top right of the screen. You will notice that the "Region" menu will then become highlighted. Push "Region", and then select the continent or category of the area you want the sky to be shown for. Once you have selected a region, a pull-down menu with the name of that region will appear next to the "Region" button. Use that new menu to select your city. After the city is selected, its name will appear next to the regional menu.

If you select a "Custom" or "Menu" location, a button labeled
"Save in Private Menu" will appear. After you select your new position,
you may push that button to save it in the menu labeled "Private".
That menu is initially empty.

How to change the default location from Cambridge MA

To change the default location, just use the place menu to select a new
location as described above, and be sure to push the "Save to Configuration File" button. That will make the currently selected position your new default location, which will be used whenever the program is started, unless GPS is selected.

items

The display menu allows you to configure the display, selecting
such things as the faintest magnitude object displayed, whether constellation
lines are plotted, whether or not star names are displayed, etc.

Deep Sky Objects

If you select "Deep Sky Obs" from the items menu, you will
be shown some of the brightest Deep Sky Objects. Deep Sky
Objects are objects such as galaxies, expelled envelopes of
dying stars, clusters of young stars and lumious gas. A few,
such as the Andromeda Galaxy, are visible to the unaided eye.
Many more are visible with binoculars or a small telescope.
The orrery shows all messier objects, and many other
well known bright nebulae and star clusters.
The image bellow shows the Messier objects in Sagittarius.

Adding Your Own Deep Sky Object List

You may add your own list of deep sky objects to be
plotted. Simply create a file within the directory
/usr/share/orrery/deepSky/ with any name. The
file should contain lines of text with the format

name HH MM SS.SS DD MM SS.S type mag

where name is the object name, which may not include
white space, HH MM SS.SS is the Right Ascension,
DD MM SS.S is the declination (do not include a + sign
for positive declinations) "type" is an integer
specifying the type of object. 0 = Supernova Remnant,
1 = Globular Cluster, 2 = Open CLuster, 3 = Diffuse
Nebula (HII region, etc), 4 = Planetary Nebula, and
5 = Galaxy. The "mag" is the visual magnitude. The
orrery program currently does nothing with the visual magnitude, but future versions may use it.

Changing the Magnitude Limit

By default, the orrery displays every star a person with excellent
eyesight located in a very dark area on a moonless night can see.
If your observing conditions are less ideal than that, it can be
helpful to use the "Mag. Limit" filed in the item menu to lower
the limit of the faintest object plotted. The plot below shows
the "Summer Triangle" region plotted with the default 6.6 limiting
magnitude on the left, and a 5.0 limiting magnitude on the right.

If you tap "Save to Configuration FIle" your new magnitude limit
will be the default the next time orrery is run.

Touchscreen Gestures

There are four types of touchscreen gestures which you can make
in the plotting area which are recognized by the orrery: Taps,
Zooms, Pans and Presses.

Taps

If you press the display area, and withdraw your finger or stylus
within 0.25 seconds, that gesture is considered a tap.

Tapping in the lower 1/5 of the display area will pan the display in
azimuth. If you are in fullscreen mode, then tapping in the upper 1/5
of the display will take you out of fullscreen mode. Tapping anywhere
else toggles between the default screen and the constellation screen.

Zooms

If you press the screen and trace out a roundish figure, and remain
in contact with the screen for more than 0.25 seconds, and if
the figure encloses a nontrivial (> 300 pixels) area, the gesture
is considered to be a zoom. As you move your finger or
stylus, the region you are outlining will be shown
as a green dotted line. After you release your finger
from the display, a red box will be shown.
The red box is a rectangle with the aspect ratio of the
display area, and the same area and centroid as the region you
traced out with your finger. The display will then be zoomed so
that the region in the red box fills the display area:

The image above shows the display immediately after the zoom gesture
has been made (left) and after the zoom has become active (right).
One may zoom an image which has already been zoomed.

Zooming can do some non-intuitive things, especially if you zoom near
the upper left or upper right of the display. This is because
the orrery's transverse mercator projection always has a line of
constant azimuth in the center. This means that something zoomed
at the edge of the display area will be rotated as it is zoomed, and
some of the stars you wish to display may be rotated out of the
display area. It is best, especially if you are zooming in on
an area near the zenith, to first pan the display so that the region
is near the center of the display, before zooming. The nice
thing about the transverse mercator projection is that a zoomed
area is displayed with the orientation it would have if you were
directly facing it at the time indicated by the display.

If your zoom area includes the zenith, the display any do weird
things. This is a bug.

Pans

A pan is like a zoom, but with a more linear, rather than roundish
gesture. A pan can be used to move the center of a zoomed region.
It has no effect if the display area is not zoomed. After you
release your finger or stylus following a zoom gesture, orrery
will show the region you traced out in green, and will draw a red
arrow showing the direction and size of the pan. After that,
the display is re-drawn with the new center position.

The image above shows the display immediately after a pan gesture
has been made (left) and following the re-drawing of the display
area (right).

Presses

If you push down on the touchscreen for more than 0.25 seconds, and
do not move your finger or stylus significantly while making contact,
you will have made a press gesture. Since one almost always moves
one's finger a little by while pressing the screen, some small motion
is allowed during a press gesture. This means that a zoom or pan
gesture cannot be arbitrarily small, because it will be interpreted
as a press.

If the screen is zoomed, then the press gesture unzooms it. If the
screen is already unzoomed, then the press gesture has the same
effect as a tap gesture.

Symbols

Symbol Key

If you select "About Orrery / Symbol Key" from the "opts" menu, you
will be shown an annotated list of the symbols used by the orrery,
which is reproduced below:

NOTE: the current version is 2.5.

Planet Symbols

The solar system symbols, used by default on the constellation
page (screen two), are the standard astronomical symbols for these
objects. They are explained here:
[2]

Plotted Lines

The dotted yellow line is the Celestial Equator, the intersection of
the Earth's equatorial plane with the celestial sphere. The red
dotted line is the Ecliptic. The Ecliptic is the intersection
of the Earth's orbital plane with the celestial sphere. The
Ecliptic is also the path of the Sun across the sky, and the intersection
points between the Celestial Equator and the Ecliptic are where the
Sun is at the time of an equinox. Constellations lying along the
Ecliptic plane are zodiac constellations. The planets and the Moon
are always near, but usually not exactly on, the Ecliptic.
The blue-green dotted line is
the Galactic Plane, the intersection of the plane of the Milky Way's
disk and the celestial sphere.

Displaying Stars Too Faint for the Unaided Eye to See

The default sky catalog used by the orrery contains every star
you can see with your unaided eye, even if you have
exceptionally good eyesight, and are located in a
very dark area on a moonless night. If you wish to display stars
which require binoculars or a small telescope to be seen, you can
download the file hipparcos_9.0.dat from the orrery area of the
gForge site:
[3]. You must then load that file to your phone
with the name /usr/share/orrery/hipparcos.dat (you will be overwriting
the smaller catalog which comes with the package). If you
prefer to put the file elsewhere (on your microSD, for example), you
may make /usr/share/orrery/hipparcos.dat a soft link.

The default orrery star catalog contains 9931 stars. hipparcos_9.0.dat
contains 83392 stars, and is complete to 9th magnitude. Note
that the orrery will be more sluggish if you use this larger catalog.
Most people definately won't want to use it. The plot below shows
Lyra with limiting magnitudes of 6.6 (left) and 9.0 (right).

System Requirements

Supported Phones

This program will run on either the neo1973 (gta01)
or the FreeRunner (gta02). Users of the neo1973
may wish to move the files to the microSD card, to
save space in the limited builtin flash memory
(see below).

Supported Software Stacks

This program has been tested running atop the
2007.2 and 2008.8 distributions. It probably will
work with FSO too. It is gtk based.

A note about FSO

At least some versions of FSO do not include the
file /usr/lib/libpopt.so.0 . orrery uses that
file, and will not run without it. If you cannot
get orrery to run on FSO, try issuing the command

opkg install libpopt0

and then launch orrery again.

Memory Requirements

This program requires 630 kbytes of storage space in the phone's
builtin flash storage or microSD card. By default, most of
the files (everything except the .desktop file, the launch
icon and the executable) are stored under /usr/share/orrery.
This directory tree may be moved elsewhere, if the new
location is specified with the -d switch on the orrery
invocation line in the .desktop file. The .desktop
file resides in /usr/share/applications .

Installing this Program

.ipk files for this program are now available for both the 2007.2
and 2008.8 stacks, at the gForge site. It is much easier to install
than it used to be. The latest .ipk files can be found here:
[4].

Known Bugs

Zooming the zenith area doesn't work

If you make a zoom gesture that includes the zenith, or if
you pan a zoomed region so that the zenith falls within it,
the orrery goes nuts.

Send more bug reports!

Revision(ist) History

Version 2.5:

New user features:
Added a to-scale Solar System view, which
shows the positions of the planets to
proper scale, with elliptical orbits.
Added the ability to display common
asterisms, rather than official IAU
defined constellations. Official
constellations are still shown by default.
Improved handling of the faint star catalog,
so that the normal catalog is used if you
chose to display only stars visible to the
unaided eye, but if you have installed the
faint star catalog, it will be used if you
choose to display stars that require
binoculars or a small telescope to see.
Added a display of the number of satellites
being tracked and being used for the last
fix, which is displayed when GPS position
mode is active. This was requested by a
user.
Bug Fixes:
In version 2.4, the Solar System View time
increments were always 1 day too small, which
made the +-1 day buttons do nothing at all.
That has been fixed.
Fixed a bug which lead to a nonterminating
loop if the moon phases were calculated at
a time within a few hours of the new moon.
Added a trap for the SIGPIP signal, so that
a shutdown of the socket to gpsd will no
longer crash the program. Now the
gpsd connection will be re-established, if
possible.
Cleaned up planet-related code.