Orrery

Overview
The orrery is a simple open-source application for Maemo 5 which displays the night (and day!) sky. It is nowhere near as elaborate as, for example, kstars, xephem or stellarium. It is intended to be a small, finger-friendly application, requiring no network connection. The current stable version is 3.2.x (the x just increments when bugs are fixed). The program version is shown on the "Symbol Key" page.

The most recent version of the program may be downloaded at from the garage project page. The version there may not have gone through the Maemo Community QA testing. The most recent version which has been vetted by the community is available in the Maemo Extras catalog. This wiki page describes the behavior of the version of the program available in the Extras catalog.

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.

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 N900 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. That allows the phase of the moon to be shown.

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 orrery as a compass
The green numbers at the bottom are the azimuth values. The azimuth is the angle, 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.

The azimuth compass which appears if you tap the bottom center of the default page shows the azimuth of the Sun and Moon, if they are currently above the horizon.

You can also use the "Planet Compass" to find directions. If the sun, moon or a planet is visible above the horizon, you can orient the azimuth portion of the planet compass with that object, and use the rest of the compass to find any other direction.

Why does this program put my phone in portrait mode?
The Transverse Mercator transformation works poorly when the phone is in landscape mode. As we all learned in school, Mercator maps of the earth become very distorted near the earth's poles. For the orrery program, that distortion is unacceptably large when the phone is in landscape mode, because the landscape aspect ratio results in too large a range of azimuth values being displayed. A future version of orrery will support landscape operation, using a different coordinate transformation for that display.

Constellations Display
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. Tapping the screen within the upper 4/5 of the display toggles in and out of the constellations page.



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, were 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 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 "Displayed 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.



Panning
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. The program tries to center the azimuth value near where you tap. If you tap near the left or right edges, it pans by the maximum allowed amount, +-40 degrees. Pan steps are quantized in increments of 5 degrees.

Selecting a New Center Azimuth
Panning to a new central azimuth by panning 40 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 near the center of the finger-pan area (bottom 1/5 of the display) The compass shown below will appear:



The locations of the Sun and Moon are shown if they are above the horizon (if they are too close together, only the Sun is shown). 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.

Main Menu


The main dropdown menu for the orrery has six options:

Other Pages
The "Other Pages" option takes you to a menu that allows you to display things other than the night sky. With the exception of the flashlight pages, which are dismissed by tapping anywhere on the screen, the "Other Pages" are dismissed by curved arrow in the upper right hand corner.



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 and Moon
The "Sun and Moon" 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 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 10 lunar months, centered on the current time (which of course can be changed with the time menu). The nearest time and date when each phase will occur is highlighted.

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

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

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.



The items shown on the Meteor Showers page are the horizon to not appreciably brighten the sky.
 * 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 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
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
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
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 non-circular:



Displayed Items
The "Displayed Items" page 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 "Displayed 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 luminous 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.

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.

Changing the Magnitude Limit
The magnitude scale for expressing the brightness of stars and planets is explained in a Wikipedia article. 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.

Change Time
The "Change Time" page 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.

If the Calendar checkbox is selected, you can choose the date and time (UT) using the normal Hildon selector widgets for these quantities. Note - this option only allows dates from 1900 to 2100 AD to be selected. To chose a date outside that time range, you must use the Text Entry option.

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.

Note about the Text Entry option: At this time, the numeric fields can only be changed with the keyboard's up/down arrow keys, or with text entry via the soft keyboard.

Change Location
This page allows you to select the position of the observer on the earth's surface. You can use the position derived by the N900 itself (either from cell tower coordinates or GPS), a user specified latitude and longitude, or a location selected from a menu.

If you chose the "Phone" option, the most recent position derived by the N900 will be used. If the phone has not yet established a position, the default location will be used until the phone has derived a position.

If you choose the "Custom" option, you may enter a new position by typing text into the "Name" field, and using the "Longitude" and "Latitude" selection widgets. Don't forget the "West", "East", "North" and "South" buttons - they select the sign of the latitude and longitude. Once you've entered a new custom position, you'll be given the option of saving it in your private catalog.

To choose a predefined position from a menu, select the "Menu" option near the bottom of the page. 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 would like to add additional cities, etc. to one of the menus other than the private menu, you may simply edit one of the menu files, and add the name, latitude and longitude of the location. The lists of locations are stored in ASCII text files under the menus subdirectory of the program installation area on your phone. You will need to reload the "Change Location" page for your new locations to become available.

How to change the default location from Boston
To change the default location, just use the "Change Location" menu option to select a new location as described above. That will make the currently selected position your new default location, which will be used whenever the program is started, unless "Phone" is selected as the source for position information.

Web Help Page
This button brings up this wiki page in the browser, provided you have a network connection.

Quick Tips
This button brings up a page with a few basic instructions for operating the program. It does not require a network connection.

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

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.

To unzoom - just press the screen for longer than 0.25 seconds, without moving your finger (much).

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.

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.

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

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

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.

You must load this file onto your phone, of course, but you probably will want to store it on the removable 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 installation of the orrery, 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/mmc1/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 "Displayed Items" menu option) 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, because it must process the larger star catalog.

The plot below shows Hyades star cluster with limiting magnitudes of 6.6 (left) and 9.0 (right).



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.

Chinese Color Scheme
In traditional Chinese astronomy, the zodiac is known as the Yellow Way, and the celestial equator is known as the Red Way. If you want the orrery to use that color scheme for great circles and constellations, edit the file, and make the first lineread

CHINESE_COLOR_SCHEME 1

You will need to restart the program.

Preserving the Private Catalog
If you installed the first version of the orrery program (3.0.x), and if you made location entries in the "Private catalog", upgrading to the 3..1.3-1 version will delete your "Private catalog", and all your saved locations will be lost. You may prevent this by using "X Terminal" to issue the following commands before upgrading:

mkdir /home/user/.orrery cp /opt/maemo/usr/share/orrery/menus/Private /home/user/.orrery/

Contact Information
Please send comments, suggestions, questions and/or abuse to orrery.moko@gmail.com