SkyScape planetarium program

Home page - http://moonchart.co.uk/skyscape/

Contents:

• Introduction
• Installation & system requirements
  
• Sky Display
  • Menus
  • Mouse
  • Key shortcuts
    • Pop-up dialogs
    • Date & time adjustment
    • Angle-of-view adjustment
• "Set" menu
  • Date, time & location dialog
  • Angle of View dialog
  • Style of Display dialog
    • Lines
    • Labels
    • Planets shown
    • Planet style
    • Projection types
    • Star magnitude
    • Star size
    • Below horizon
    • Horizon height
  • Full screen
  • Level horizon
• "Find" menu
  • Find Star
  • Find Constellation
  • Find Planet
• "Output" menu
  • Calculations window
  • Save map image
• Hints & ideas
  • Solar eclipses
  • Lunar eclipses
  • Planisphere
  • Sidereal Time
  • Precession
  • Equation of Time
• Acknowledgements

Introduction:

This program can be used to get an idea of how the stars and planets can appear at any given time and location on Earth. The graphic display can give a useful impression of the clear night sky, identifying and showing the stars and planets in their correct positions. The direction of view can be adjusted either by using the mouse simply to "drag" any part of the sky across the display, or by typing in either the azimuth and altitude, or the right ascension and declination, of the required direction of view. The width of the field of view can also be continuously adjusted, so that you can "zoom in" on any part of the sky.

The routines which calculate the planetary positions are derived from figures published by NASA's Jet Propulsion Laboratories, and are very accurate. They have further been adjusted to allow for light-travel time, so the positions given are the "apparent" positions, where the planets (and the Sun and Moon) would really be seen in the sky. This makes very little difference to the observed positions in the sky, but can make the calculations of rising and setting times more useful.

If the mouse is clicked close to a star or planet, the display will show the name of the object on screen closest to the mouse pointer. If the mouse is double-clicked anywhere in the sky display, the coordinates of that point will be displayed, with the name of the constellation containing it.

The database of stars is derived from the published "Bright Star Catalogue", and contains more than 9000 stars. The stars are displayed on screen all at the same size, but using both colour and brightness information from the database; this gives a much more effective display than using different-sized dots for stars.

Installation & system requirements:

On most desktop computers, the program can be run simply by double-clicking on the downloaded file (called skyscape.jar).

The program is written in the Java^TM programming language, which allows it to run under various different operating systems (including Windows, Macintosh and Linux); the computer needs to have a Java runtime environment installed on it, to enable it to run Java application programs. Many computers will have such a system installed already; if yours doesn't, there is a free download page at http://java.com.

The complete SkyScape program is packaged into a single executable Java file called skyscape.jar which should be saved somewhere on your machine. It's nice to give the program its own directory to live in; it will store its own configuration file there (when you 'save settings' from within the program). In a suitable graphical environment, you can then launch the program by just clicking (or maybe double-clicking) on this file. Alternatively, you can run this from the command line (in the directory/folder containing the jar file) by typing: java -jar skyscape.jar. The latest version of this program can be found at http://moonchart.co.uk/skyscape.

Swiss Ephemeris:

If any Swiss Ephemeris data files are in the same directory as the skyscape.jar file, SkyScape will try to use them if they cover the relevant dates. Otherwise it will revert to a version of Steve Moshier's calculations, which I've ported from C to Java. For the display of current positions in the sky, this makes little difference, but if you want to use the calculated times of rising and setting or exact full or new moon times,for example, it's highly recommended that you download the Swiss Ephemeris files.

Sky Display:

The main program window shows a map of the sky, according to the various input settings (date, location, viewing direction, display style, etc.). You can click on an object (star or planet) to find its name, or double-click on any point of the sky to find its coordinates, both in azimuth and altitude, and in right ascension and declination. The name of the constellation containing that point is also displayed.

Menus:

You can access the menus by using the other ("right") mouse button, or by pressing the Return (a.k.a. Enter) key in the sky-map window.

Mouse:

You can use the mouse to "drag" a point of the sky to another place on screen. After you've done that, the displayed horizon probably won't be level on the screen any more; you can level it up again by typing L.

Depending on the speed of your computer, and also on how much detail is being displayed, there may be pauses as the machine catches up with where the mouse is. If these take too long, reduce the number of stars displayed, or the number of coordinate lines displayed.

Also, if you drag the mouse with the shift key held down, you can adjust the width and orientation of view (i.e. zoom in or out, and rotate the screen). Zoom in/out by moving the mouse away/towards you, rotate left/right by moving the mouse left/right.

Keyboard:

Although the dialogs are all accessible via the menu, they can also be accessed quickly using keyboard shortcuts from the main window:

Pop-up dialog access
Key	Action
?	Show help window
S	Style of display dialog
T	Time, date and location dialog
A	Angle-of-view dialog
V	Planet-finder
W	Constellation-finder
X	Star-finder
C	Calculations dialog
G	Save screen image

Some of the letter keys on the computer keyboard (specifically H, M, D, Y and N) can be used to nudge the date/time of the display forwards or backwards, without having to use the Set Date dialog window. Using the shift key causes the change to be bigger; using the control key causes the change to be negative (backwards in time). Details are given in the next table. If you look at the "Date, Time and Location" dialog, (accessible from the Set menu or by pressing T), you'll see the time and date there keep up with the changes you've made using the keyboard. The P key sets the display to the present time, from the computer's clock.

Time and Date adjustments
Key	Action	with Shift	with Ctrl
M	Forward one minute	Forward four minutes	Adjusts time backwards instead of forwards, by same amount.
H	Forward one hour	Forward six hours
D	Forward one day	Forward seven days
N	Forward one calendar month	Forward 3 months
Y	Forward one year	Forward seven years
P	Set to present time (system clock)

The cursor (arrow) keys, and the Page-up, Page-down, Home and End keys, can be used to adjust the direction & field of view, without having to use the Angle-of-view dialog; details are in the table below. Holding down the Shift key at the same time causes the change to be greater (10 degrees instead of 1). If you look at the "Angle of View" dialog, (accessible from the Set menu or by pressing A), you'll see the figures there reflect the changes you've made with the keyboard, and you can see exactly which way the display is angled.

Angle-of-View adjustments
Key	Action
L	Make horizon Level
F	Toggle full-screen display
Up	Increase altitude
Down	Decrease altitude
Left	Decrease azimuth
Right	Increase azimuth
Ctrl-Up	Zoom in
Ctrl-Down	Zoom out
Ctrl-Left	Rotate anticlockwise
Ctrl-Right	Rotate clockwise
Page-up	Increase declination
Page-down	Decrease declination
Home	Decrease right ascension
End	Increase right ascension

"Set" menu:

Date, time & location dialog:

This enables you to set the point in time for which the display is drawn. The display is recalculated as soon as any change is made. Clicking the "Set to Now" button sets the display date and time to be the current value of the computer system clock. Here's an illustration of how the dialog might look (though the details may vary):

As well as the date and time, this dialog also controls the longitude and latitude of the observer. The longitude and latitude can then be saved by using the "save settings now" button in the Style of Display dialog, so you can configure the program to start up using, for example, the latitude and longitude of the place where you live. The date and time are not saved; the program always starts up using the current system date and time.

The "Lat,Long." window here allows you to copy the latitude and longitude of a location directly from google maps. (In google maps, if you right-click on a point on the map and then select "What's here?", it will tell you the latitude and longitude in exactly this format, in decimal degrees, which you can then copy and paste into SkyScape.) You then need to click the "Apply" button to make use of these values.

Angle of View dialog:

This enables you to adjust the direction of view in the observer's sky, and also the width and orientation of the field of view. (You can also adjust these values using the mouse directly on the sky display, as described earlier.) Here's a picture of what this dialog might look like:

The direction of view (i.e. which way your telescope is pointing) may be set either in right ascension and declination (celestial coordinates), or in azimuth and altitude (horizon-based coordinates). Both azimuth (which means the bearing measured from North clockwise around the horizon to the point directly below the direction of view) and altitude (which is the angle from the centre of view straight down to the horizon) are measured in degrees and minutes. (One minute of arc is a sixtieth of a degree.) Declination is measured in degrees and minutes, while right ascension is measured in hours and minutes (with 24 hours in the full circle). As one set of values is adjusted, the other is automatically kept correct.

The view width, also measured in degrees, adjusts the magnification, or how much you "zoom in" to the display. A small width means more magnification.

The "orientation" of the screen is the amount by which the screen image is then rotated - for a value of zero, the observer's zenith will be above the centre of the screen (possibly off-screen, depending on the width of view). Telescopes which invert the image can be simulated with an orientation value of 180°.

This dialog also has a few buttons which will quickly change the view to looking due North, or East, etc., or towards either the equatorial or the ecliptic poles.

Style of Display dialog:

This enables you to control what features are displayed on the sky map. Various labels and coordinate lines can be turned on or off, and there are also choices for other options, as detailed below.

When the program starts, it has default values for the various options. If you change the settings, and then click the "save settings now" button in this dialog, the new settings will be saved and automatically loaded and used again the next time the program is run. Note that this also automatically saves the current longitude and latitude values (from the Set Time, Date & Location dialog), though not the time or date.

Here's a screenshot of how this dialog might look:

• Lines: There is a whole series of checkboxes here, allowing you to choose which coordinate lines will be drawn on the display. The selection includes the three main spherical coordinate systems: Ecliptic longitude and latitude, Equatorial RA and declination, and Horizon-based azimuth and altitude.

  There are also options to show the standard constellation boundaries (which are adjusted for the precession of the equinoxes), or "stick-figure" constellation shapes. The coordinate lines of the ecliptic system are drawn in green; those for the equatorial system in red, and those belonging to the horizon-based system are light blue. The constellation boundaries are drawn in darker blue.

  The "graticule" option just draws some circles centred on the centre of view. The radii of the circles are 10, 30, 50, etc. degrees; and when you're zoomed in sufficiently, circles of radius 2, 4, 6 and 8 degrees also appear.

  The 'galactic equator' is an approximate centre-line of the Milky way, our galaxy.

  The 'Earth shadow' option draws the limits of the Earth's umbra and penumbra at the distance of the Moon, which can be used to watch the progression of a virtual lunar eclipse. It's clearer if the planet style is set to 'dots', not glyphs, so the Moon is drawn to scale.

• Labels: The base circles of the three spherical coordinate systems can be labelled: the horizon is labelled with the cardinal compass points, the equator is labelled (in red) in hours from 1 to 24, and the ecliptic is labelled (in green) with the traditional zodiac names. Also, the planets and brighter stars can be labelled with their proper names, and the constellations with the standard abbreviations of their names. To see the full name of a constellation, double-click the mouse on it.

• Planets shown: The Sun, Moon and the eight planets (other than the Earth), from Mercury to Pluto, can be shown, or just those planets which are sometimes visible with the naked eye (i.e. leaving out Uranus, Neptune and Pluto; and only showing the seven "moving lights" that gave us the seven days of the week), or just the Sun and Moon, or none.

• Planet style: The Sun, Moon and planets can be shown as symbols (glyphs), or as dots like the stars. If you don't know what a particular glyph represents, either click on it with the mouse (which will make a label appear on it), or else label all the planets using the Planet Labels checkbox above. In "dots" mode, the Moon is drawn to scale, showing the correct phase. You need to zoom in somewhat to see it.

• Projection types: Looking at the (real) sky, the stars appear to lie on a huge sphere surrounding us ("the celestial sphere"), but the computer screen is flat, so some distortion is necessary to fit the one onto the other. Some choice is possible, however, and the program implements a few different types of projection, to map a star's position from the sphere to the plane screen.

  In all cases, there is an "origin" point on the screen - initially the centre of the screen window - which represents the point in the sky which the observer (or the telescope) is looking directly towards - this depends on the direction of view in azimuth & altitude, as well as on the observer's location on Earth, and the time and date. The distance from this screen-origin to the image on screen of some other point depends on the angular distance separating those two points in the sky.

  • The orthogonal projection is the one which makes the sphere look most like a three-dimensional sphere, and permits seeing no more than half of the whole celestial sphere at a time. It looks on screen like a globe; you have to imagine it's concave - it seems easier to see it as convex!

  • In the equal area projection, the screen distance (from the screen origin) is, as it happens, proportional to the sine of half the angle, so the radial scale decreases further from the screen origin, and this has the effect of preserving areas accurately. That is, equal-sized areas of the sky are shown as equal-sized areas on screen. This naturally results in some distortion of shape, slightly worse than the equidistant projection, especially for points a long way from the screen origin. Otherwise, it looks very similar to the equidistant projection, and can similarly show the whole sphere at once.

  • With the equidistant projection method, this screen distance (from the screen origin) is simply proportional to the celestial angle. This kind of projection allows very large viewing angles, so we can zoom out to see the whole celestial sphere on screen at once. Note that only distances to/from the "origin" point of the screen are represented all to the same scale; distances between other pairs of points will be stretched to fit them on to the flat screen.

  • In the stereographic projection, the screen distance is proportional to the tangent of half the angle, which results in distortion of area, but does preserve angles. This means that small shapes (e.g. the arrangement of a small group of stars) have much the same shape on screen, but the scale gets very large a long way from the origin. All circles on the sphere appear as circles on the screen, intersecting at the same angles. This projection also allows large viewing angles in theory, but they look pretty weird.

  • The central projection is in a sense the most obvious kind of projection, in that it's what you'd see if you held an empty picture frame up in front of you and looked at the sky through it. It makes the screen distance (from the screen origin) proportional to the tangent of the celestial angle. It further restricts the maximum field of view, however, and causes greater distortion near the edges of the frame. One nice thing about it is that the horizon (and any other great circle) is displayed as a straight line.

  For small fields of view, all these projection methods give very similar results, and become virtually identical as the field of view gets very small.

• Star magnitude: This choice effectively lets you set how many stars will be displayed, according to their apparent brightness. The "magnitude" of a star is a measure of apparent brightness, which gives a higher number to dimmer stars, so the higher the number you select here, the more stars will be shown. The time taken to redraw the display will be longer when more stars are displayed. Star magnitudes are on a logarithmic scale, where adding 5 to the magnitude value indicates making the star's apparent brightness 100 times less, so many more stars are displayed as the magnitude value chosen is increased.

• Star size: This refers to the size of the dots drawn on the screen to represent the stars. The best setting for you will probably depend on the screen you're using.

• Below horizon: Stars below the horizon can optionally be shown, or shown dim (coloured dark blue) or not shown at all. When they are not shown at all, no lines or labels are shown below the horizon either.

• Horizon height: Sets the altitude of the circle used to represent the "horizon" in the sky-map display. Note: this is the horizon used when calculating rise and setting times, in the calculations window.

  For example, you could choose to only show brightly the stars more than say 10° above the theoretical or "true" horizon, since it may be hard to observe stars lower than that. Or you could set the horizon height to -6° (6 degrees below the theoretical horizon) and step the time forward until the Sun just crosses that line; (or use the calculations window to display the calculated time when this happens) - that is the beginning or end of "civil twilight" as usually defined.

  "Nautical twilight" (when the horizon can be distinguished at sea) is reckoned to occur when the Sun is no more than 12° below the true horizon. "Astronomical twilight" (when it's still too light for serious astronomical observations) is when the Sun is no more than 18° below the horizon.

Full screen:

Makes a full-screen display, without borders or title bar. Using this display option, you can then save a gif image that is the same size as your screen!

Level Horizon:

This re-orients the display, so that the horizon appears level (and the "orientation" value is zero). The option is greyed out if the orientation is already zero. It's a useful option to use after you've been using the mouse to adjust the display, as this usually changes the orientation.

"Find" menu:

Find Constellation:

Select the constellation name from the given list, and press Return. The display will centre on the selected constellation, showing its boundary and the stars it contains. You can hide its boundary line again by pressing Escape.

Find Star:

Select a star name from the given list, and press Return. The display will centre on the selected star,and label it. The display will then remain centred on the screen until the direction of view is changed or Escape is pressed; as with 'Find Planet' below.

Find Planet:

Select the planet's name, or "Sun" or "Moon" from the given list, and press Return. The display will centre on the selected object, which will remain centred on the screen until the direction of view is explicitly changed or Escape is pressed.

This means, incidentally, that if you press a key to only change the time - like D or H for example - the chosen star or planet will remain centred on screen, and the angle of view is changed to accommodate that. If you repeatedly press the D key (or hold it down, in most cases, so it repeats automatically), then time will keep advancing on screen, and you'll see the changing relationship of the planet you selected, to the other planets and stars. See the Solar and Lunar Eclipses sections below for more on this.

"Output" menu:

Calculations Window

Shows the calculations output window. This is a text area showing the calculated values of various phenomena; currently there are two buttons to produce output, and one to clear the display.

• Planet positions:

  The apparent positions of the currently displayed planets, Sun and Moon are printed, in right ascension and declination, azimuth and altitude, and in ecliptic coordinates.

• Rise/set, culminate:

  The next culminate, set, nadir and rise times of the currently displayed planets, Sun and Moon are printed in the calculations output window. Note: the rising and setting times are calculated using the horizon height specified in the Style of Display dialog, so you can calculate when the sun is, for example, more than 18° below the "true" horizon.

  Note that for some situations, where either the observer's latitude is a long way North or South, and/or the value of the horizon height is a long way from zero, it may be that some or all of the Sun, Moon and planets do not actually rise or set at all, during a 24-hour period. If this is the case, then obviously only the culminating and nadir times can be displayed.

Save image:

This option will save an image file of the skymap as it currently appears on screen. A file dialog window opens first, where you enter a filename to use for the saved image.

Hints & ideas:

When you (single-) click on a star to find its name, the program chooses the object actually displayed on screen closest to the mouse pointer. To reduce the risk of confusion, you can reduce the total number of stars shown with the Star magnitude choice in the Style of Display dialog. You can also zoom in (decrease the view width) to separate the stars better.

When you double-click on a point on screen to find its coordinates, you'll get a more accurate result if you zoom in more, as the mouse resolution will then be better.

The speed of animation of the display depends not only on the speed of your machine, but also on how many stars and coordinate lines are displayed. Turning down the maximum star brightness can make "dragging" the screen more effective. Otherwise you have to wait longer for the screen to refresh.

Solar eclipses:

If you select 'Sun' in the Find Planet dialog, the Sun will be centred on the screen (until the direction of view is changed or Escape is pressed). If just the displayed time is changed, the Sun remains selected, so you can for example watch how a solar eclipse progresses by selecting 'Sun' (or 'Moon', in fact) and then sliding time forwards and back using the 'M' and 'Ctrl-M' keys. You should have the Style of Display 'Centre' option set to topocentric (as solar eclipses are very sensitive to your exact position on Earth!), and the 'Planet Style' option to 'Dots' so you see the lunar and solar disks drawn to scale.

Lunar eclipses:

If you select the 'Earth's shadow' option in the Style of display dialog then the outlines of the Earth's umbra and penumbra - as seen at the distance of the Moon - are drawn. If you select 'Moon' in the Find Planet dialog, the Moon will be centred on the screen. If just the displayed time is changed, the Moon remains selected, so you can for example watch how a lunar eclipse progresses by selecting 'Moon' or 'Sun' and then sliding time forwards and back using the 'M' and 'Ctrl-M' keys. You should have the 'Planet Style' option to 'Dots' so you see the Moon drawn to scale with the Earth's shadows.

Planisphere:

This is a printed design, showing stars and constellations over almost all the celestial sphere, on one plane (the paper). It then has a second sheet of paper with a cut-out area which, if you adjust it correctly, allows you to see just which stars will be above the horizon at any particular time, (without using a computer!). You can buy them ready-made - the exact shape of the cut-out depends on your latitude on Earth - but the program will allow you to print one for any latitude you choose (except very close to the equator).

Use either the Equal-area, the Equidistant, or the Stereographic projection method (because Orthogonal and Central projections can't give a wide enough field of view). Then for Northern latitudes set the direction of view to 90°N declination (you can use the "Equ. N" button on the Angle of View dialog), or for Southern latitudes set the direction of view to 90°S declination (you can use the "Equ. S" button on the Angle of View dialog).

You also need to zoom out to a large view width of at least 180° + 2×( 90° - latitude), so that the whole horizon is on screen, and then you can print a planisphere for the current latitude. You may find it easiest to see if you also set the view orientation to 180°. You should print the starmap with the below-horizon stars set to "show", but with no planets, and no azimuth/altitude or horizon lines.

You'll also need to print another copy with the horizon line included (and labelled too if you like); you cut around the horizon line on this copy, and throw away the middle bit, making a window through which to view the first sheet. The two sheets must remain centred, and as the lower sheet rotates under the cut-out window, the changing stars are seen. You might use some transparent film to hold the top sheet with a pin through the centres of both sheets, so it rotates easily.

Sidereal Time:

This means the "star time", as distinct from "solar time". As the Earth spins, the Sun appears to rise and set, giving us the notion of solar time, measured in days, but because the Earth is orbiting around the Sun as well as spinning on its axis, each day the Sun appears to have moved slightly against the background of the stars. If we ignore the Sun and instead watch the stars rising and setting each day, we see that they appear to spin around us slightly faster than the Sun, and a "sidereal day" is about 4 minutes shorter than a solar day.

The sidereal time for a given observer is, by definition, the RA (right ascension) of the observer's zenith (the point directly overhead the observer). RA is measured in hours, with "Aries zero" - the point where the ecliptic crosses the equator, where the Sun is on the (Northern hemisphere) Spring equinox - as the starting point.

You can see the observer's meridian and the equator on screen (so long as you have the checkboxes for "Observer's meridian" and "Equator" checked in the Style of Display dialog), and if you double-click on the intersection of these two lines, the program will display the RA of the intersection point, which is is the sidereal time for that observer at that time. (Note: use the intersection point that is above the observer's horizon - there is another diametrically opposite! If you have the "Below Horizon" option set to "Hide", then you'll only be able to see the right one, anyway.)

Precession:

The "Precession of the Equinoxes" refers to the way the position of the Sun against the background of stars changes from year to year (i.e. looking at the position of the Sun on the Spring equinox each year). This change happens very slowly, and makes a complete circle only after some 25,800 years. If you enter a date that is a few hundred years in the past or future, you will notice the effects of precession, particularly if you have the "Constellation Boundaries" option checked in the Style of Display dialog. If you enter a date about 200AD, and turn on the labels for "Ecliptic" and "Constellation names", you will see that the zodiac names on the ecliptic are more closely aligned with the corresponding constellations than they are today. This is because these names were first applied to the ecliptic around that time, and since then the precession of the equinoxes has caused them to move away from the original stars. They will line up again in another 24,000 years or so!

Equation of Time:

The phrase "Equation of Time" refers to how the time when the Sun reaches its highest point in the sky, varies from day to day. At this moment, the sun is on (i.e. directly over) the observer's meridian, i.e. the sun's azimuth is due South (or North) of the observer, but because of both the ellipticity of the Earth's orbit and the inclination of the Earth's axis of spin, this doesn't happen at the same time on the clock each day. It can deviate from local mean noon by more than 15 minutes.

If you set the time to local mean noon (i.e. noon GMT plus or minus an allowance for longitude at the rate of 4 minutes of time for each degree of longitude), you will see the sun close to the observer's meridian. (Highlight the observer's meridian using the checkbox in the Style of Display dialog.) Then repeatedly pressing the D key will run time forward one day at a time, and you will see the varying position of the Sun at this same time, from day to day.

Acknowledgements:

The stellar data is derived from the Bright Stars catalogue (BSC5).
The lunar and planetary positions are derived from Steve Moshier's planetary routines at www.moshier.net.
The program also understands Swiss Ephemeris files if they're available; these can be downloaded from http://www.astro.com/swisseph/ and should be stored in the same directory as the skyscape.jar file. It's highly recommended to do this if you're interested in knowing the planets' positions, since these calculations are much more accurate than the formulae built into the program.
Java is a trademark of Sun microsystems.
Thanks to all who have helped.

The SkyScape download page, and the latest version of this document, are at http://moonchart.co.uk/skyscape.