SkyScape planetarium program

v.1.3 by Mick Soar, July 2008.
Home page -



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

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

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.


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.


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.


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
?Show help window
SStyle of display dialog
TTime, date and location dialog
AAngle-of-view dialog
CCalculations dialog
GSave 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
KeyActionwith Shiftwith Ctrl
MForward one minuteForward four minutesAdjusts time backwards
instead of forwards,
by same amount.
HForward one hourForward six hours
DForward one dayForward seven days
NForward one calendar monthForward 3 months
YForward one yearForward seven years
PSet 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
LMake horizon Level
FToggle full-screen display
UpIncrease altitude
DownDecrease altitude
LeftDecrease azimuth
RightIncrease azimuth
Ctrl-Up Zoom in
Ctrl-DownZoom out
Ctrl-LeftRotate anticlockwise
Ctrl-RightRotate clockwise
Page-upIncrease declination
Page-downDecrease declination
HomeDecrease right ascension
EndIncrease 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):
Date dialog

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:

View dialog

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:

Set dialog

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.

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.


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


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.


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
The program also understands Swiss Ephemeris files if they're available; these can be downloaded from 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

Copyright © Mick Soar 2000-2016