Matthew Gates
Stellarium is a software project that allows people to use their home computer as a virtual planetarium. It will calculate the positions of the Sun and Moon, planets and stars, and draw how the sky would look to an observer depending on their location and the time. It can also draw the constellations and simulate astronomical phenomena such as meteor showers, and solar or lunar eclipses.
Stellarium may be used as an educational tool for teaching about the night sky, as an observational aide for amateur astronomers wishing to plan a night's observing, or simply as a curiosity (it's fun!). Because of the high quality of the graphics that Stellarium produces, it is used in some real planetarium projector products. Some amateur astronomy groups use it to create sky maps for describing regions of the sky in articles for newsletters and magazines.
Stellarium is under fairly rapid development, and by the time you read this guide, a newer version may have been released with even more features that those documented here. Check for updates to Stellarium at the Stellarium website.
If you have questions and/or comments about this guide, please email the author. For comments about Stellarium itself, visit the Stellarium forums.
You should visit the Stellarium website. Download packages for various platforms are available directly from the main page. Choose the correct package for your operating system2.1.
Check if your distribution has a package for Stellarium already - if so you're probably best off using it. If not, you can download and build the source. See the the wiki for detailed instructions.
After you run Stellarium for the first time, you will see a something
like one of the sides of the image shown in Figure ![[*]](crossref.png)
(depending on the time of day that you start the program).
At the top of the screen you will see: the date, the time, Stellarium's version number, the location of the observer, the field of view (FOV) and the current frame-rate (FPS). In the bottom-left corner of the screen is the main tool-bar. In the bottom-right corner of the screen is the time tool-bar. The rest of the screen is a graphical representation of the sky and the ground.
When Stellarium starts up, it sets its clock to the
same time and date as the system clock. However,
Stellarium's clock is not fixed to same time and date as the system
clock, or indeed to the same speed. We may tell Stellarium to change
how fast time should pass, and even make time go backwards!
So the first thing we shall do is to travel into the future! Let's
take a look at the time tool-bar (table ).
If you hover the mouse cursor over the buttons, a short description
of the button's purpose and keyboard shortcut will appear.
|
OK, so lets go see the future! Click the mouse once on the increase
time speed button 
.
Not a whole lot seems to happen. However, take a look at the clock
at the top-left of the screen. You should see the time going by faster
than a normal clock! Click the button a second time. Now the time
is going by faster than before. If it's night time, you might also
notice that the stars have started to move slightly across the sky.
If it's daytime you might be able to see the sun moving (but it's
less apparent than the movement of the stars). Increase the rate at
which time passes again by clicking on the button a third time. Now
time is really flying!
Let time move on at this fast speed for a little while. Notice how the stars move across the sky. If you wait a little while, you'll see the Sun rising and setting. It's a bit like one of those time-lapse movies except there are no clouds. Stellarium not only allows for moving forward through time - you can go backwards too!
Click on the real time speed button 
.
The stars and/or the Sun should stop scooting across the sky. Now
press the decrease time speed button 
once. Look at the clock. Time has stopped. Click the Decrease time
speed button four or five more times. Now we're falling back through
time at quite a rate (about one day every ten seconds!).
Enough time travel for now. Wait until it's night time, and then click the Real time speed button. With a little luck you will now be looking at the night sky.
|
As well as travelling through time, Stellarium lets to look around
the sky freely, and zoom in and out. There are several ways to accomplish
this listed in table .
Let's try it. Use the cursors to move around left, right, up and down. Zoom in a little using the Page Up key, and back out again using the Page Down. Press the backslash key and see how Stellarium returns to the original field of view (how ``zoomed in'' the view is), and direction of view.
It's also possible to move around using the mouse. If you left-click and drag somewhere on the sky, you can pull the view around.
Another method of moving is to select some object in the sky (left-click on the object), and press the Space key to centre the view on that object. Similarly, selecting an object and pressing the forward-slash key will centre on the object and zoom right in on it.
The forward-slash and backslash keys auto-zoom in an out to different levels depending on what is selected. If the object selected is a planet or moon in a sub-system with a lot of moons (e.g. Jupiter), the initial zoom in will go to an intermediate level where the whole sub-system should be visible. A second zoom will go to the full zoom level on the selected object. Similarly, if you are fully zoomed in on a moon of Jupiter, the first auto-zoom out will go to the sub-system zoom level. Subsequent auto-zoom out will fully zoom out and return the initial direction of view. For objects that are not part of a sub-system, the initial auto-zoom in will zoom right in on the selected object (the exact field of view depending on the size/type of the selected object), and the initial auto-zoom out will return to the initial FOV and direction of view.
Stellarium can
do a whole lot more than just draw the stars. Figure
shows some of Stellarium's visual effects including constellation
line and boundry drawing, constellation art,
planet hints, and atmospheric fogging
around the bright Moon. The controls main tool-bar provides
a mechanism for turning on and off the visual effects.
Table describes the operations of buttons on
the main tool-bar, and gives their keyboard shortcuts.
|
As you type, Stellarium will make a list of objects which begin with what you have typed so far, and the first item in this list will be automatically added to what you are typing (after the cursor). When you have typed enough letters to get to the object you are interested in, you can press return without having to complete the whole name.
For example, suppose we want to locate Mimas (a moon of Saturn). After typing the first letter of the name, m, Stellarium makes a list of objects whose name begins with M: Mars, Miranda, Mimas, Mercury, Moon. The first item in this list, Mars, is automatically filled in for us. Pressing return now would go to Mars, but we want Mimas, so we keep typing. After the letter i, Miranda is auto-completed. Again, it's not what we want, so we continue. After the third letter, m, Mimas is selected, so we simply press return or click the go button to locate it.
This feature can save some typing, and is useful for finding objects whose spelling is not certain.
The Help window
is useful as a quite reference to the key-strokes that may be used
to control various aspects of Stellarium. See section
for a complete list of key-bindings.
Pressing the `i' key on the keyboard toggles the display of the information window. This displays the version number of Stellarium and some information about the project.
As well as the regular key-bindings and the tool-bars, Stellarium
has another method for interaction with the user - the Text Menu,
or Text User Interface (TUI). The TUI is activated using
the m key, and is navigated using the cursor keys. Appendix
describes the commands that are available from the TUI menu.
The TUI menu is primarily used in Digitalis planetarium projectors,
where the TUI menu is controlled using a remote control by the planetarium
operator, but it is useful for the desktop user as well. Many of the
options in the TUI menu are duplicated elsewhere in the interface.
For example, the ability to set the maximum star magnitude
to label is also accessible via the configuration window
(see section ).
As mentioned in section ,
not all keys are documented in the Help window.
Some features of Stellarium are only available via the keyboard, and
are not easy to discover! Here is a full listing of Stellarium's key
bindings.
| Category | Key | Description
|
| Movement & object selection | Page up/down | Zoom in/out |
| CTRL+up/down cursors | Zoom in/out | |
| Mouse wheel | Zoom in/out | |
| Left mouse button | Select object | |
| Right mouse button | De-select object | |
| Backslash (\) | Auto-zoom out | |
| Forward-slash (/) | Auto-zoom in on selected object | |
| Space | Centre on selected object | |
| Display Options | Enter | Swap between equatorial and azimuthal mount |
| F1 | Toggle full-screen mode (not available on some architectures) | |
| c | Toggle drawing of constellations | |
| b | Toggle drawing of constellation boundaries | |
| v | Toggle drawing of constellation names | |
| r | Toggle drawing of constellation art | |
| d | Toggle star names | |
| n | Toggle nebulae names off / on (short) / on (long) | |
| e | Toggle drawing of RA/Dec grid | |
| z | Cycle through: show meridian line; show Alt/Azi grid; neither. | |
| p | Cycle through: no planet labels; planet labels; planet labels with orbits | |
| g | Toggle drawing of ground | |
| a | Toggle drawing of atmosphere | |
| f | Toggle drawing of horizon fog | |
| q | Toggle drawing of cardinal points (N, S, E, W) | |
| o | Toggle moon scaling (4x /1x) | |
| t | Toggle object tracking (moves the view to keep selected object in the centre) | |
| s | Toggle drawing of stars | |
| 4 or , | Cycle through: draw ecliptic; draw ecliptic & planet trails; draw neither | |
| 5 or . | Toggle drawing of equator line | |
| Windows & other controls | CTRL+s | Take a screenshot (will be written to stellarium*.bmp) |
| CTRL+r | Toggle script recording | |
| CTRL+f | Toggle search window | |
| h | Toggle help window | |
| i | Toggle information window | |
| 1 (digit one) | Toggle configuration window | |
| m | Toggle text menu | |
| ESC | Close any open windows (help, info, & configuration) | |
| Time & Date | 6 | Time rate pause (or script pause when a script is running) |
| 7 | Set time rate to zero (time stands still) | |
| 8 | Set time to current time | |
| j | Decrease time rate (or decrease script speed if a script is running) | |
| k | Set time rate to normal (1 second per second) | |
| l | Increase time rate (or increase script speed if a script is running) | |
| - | Move back in time 24 hours (press the ALT key at the same time to move back one sidereal day, or CTRL to move back one hour) | |
| = | Move forward in time 24 hours (press the ALT key at the same time to move forward one sidereal day, or CTRL to move forward one hour) | |
| [ | Move back in time 7 days (press the ALT key at the same time to move back 7 sidereal days) | |
| ] | Move forward in time 7 days (press the ALT key at the same time to move forward 7 sidereal days) | |
| Other | CTRL+c | Stop a running script |
| CTRL+q | Quit Stellarium. (command+Q on the Mac) | |
| < | Volume down (only when a script is playing) | |
| > | Volume up (only when a script is playing) | |
| 9 | Cycle through meteor shower rates: low; medium; high; very high | |
| CTRL+SHIFT+h | toggle horizontal image flipping (see section ) |
|
| CTRL+SHIFT+v | toggle vertical image flipping (see section ) |
|
| CTRL+SHIFT+g | If the currently selected object is a solar system body, move the observer to that body. | |
| CTRL+[num] | Make telescope [num] point at currently selected object (see
section ) |
Most of Stellarium's configuration is done using
the configuration window. To open the
configuration window, click the 
button on the main tool-bar. You can also press
the `1' key (digit one) to open the configuration window. The window
has several tabs for configuring various aspects of the program.
In addition to the configuration window, some operations may also
be performed using the text menu (see section ).
Some options may only be configured by editing the configuration file.
See section for more details.
The second tab in the configuration window
is ``Date & Time'' (figure ). In this tab
you will see controls for adjusting the year, month, day, hour, minute
and second.
There is also a display of the current time zone
setting, and time rate. The time zone setting may
be set using the TUI (see section for more
information).4.1
The positions of the stars in the sky is dependent on your location on Earth as well as the time and date. For Stellarium to show accurately what is (or will be/was) in the sky, you must tell it where you are. You only need to do this once - Stellarium saves your location so you won't need to set it again until you move.
To set your location, choose the ``Location'' tab in the configuration
window (figure ).
There are then three main methods4.2 that you may use to select your location:
Stellarium has several horizon graphics or landscapes. These may be changed by choosing the options under the Landscapes tab in the configuration window.
If the "Setting landscape updates the location" box is checked, changing the landscape will also change the location of the observer. This will set the home planet as well, if the landscape which is selected is for a different planet.
The Video tab in the configuration window
(figure ) offers the following setting options:
. The mathematical name for this projection method
is gnomonic projection.
.
.
The Rendering tab (figure ) in the configuration
window allows for
adjustment of the way Stellarium draws the scene. All the controls
are check boxes or numerical spin-buttons. By choosing values and
then clicking the button labelled `Set as default', the user can select
what options will be set when the program is started in future. Table
shows a list of these options and describes what
they do.
|
Stellarium supports several languages to some degree, although the internationalisation process is not yet complete.
When you first start Stellarium, it will try to determine the most
appropriate language settings from your system settings. You may also
customise your language settings in the Language tab of the configuration
window (see figure
).
In the language tab there are the following controls:
Stellarium has many data files containing such things as star catalogue data, nebula images, button icons, font files and configuration files. When Stellarium looks for a file, it looks in two places. First, it looks in the user directory for the account which is running Stellarium. If the file is not found there, Stellarium looks in the installation directory5.1. Thus it is possible for Stellarium to be installed as an administrative user and yet have a writable configuration file for non-administrative users. Another benefit of this method is on multi-user systems: Stellarium can be installed by the administrator, and different users can maintain their own configuration and other files in their personal user accounts.
In addition to the main search path, Stellarium saves some files in other locations, for example screens shots and recorded scripts.
The locations of the user directory, installation directory, screenshot save directory and script save directory vary according to the operating system and installation options used. The following sections describe the locations for various operating systems.
%USERPROFILE%\Stellarium\
%HOMEDRIVE%\%HOMEPATH%\Stellarium\
%HOME%\Stellarium\
Stellarium's installation directory
Within the installation directory
and user directory (defined in section
), files are arranged in the following
sub-directories.
It is also possible to add new landscapes or scripts by creating the relevant files and directories within the user directory, leaving the installation directory unchanged. In this manner different users on a multi-user system can customise Stellarium without affecting the other users.
The main configuration file is read each time Stellarium starts up, and settings such as the observer's location and display preferences are taken from it. Ideally this mechanism should be totally transparent to the user - anything that is configurable should be configured ``in'' the program GUI. However, at time of writing Stellarium isn't quite complete in this respect. Some settings can only be changed by directly editing the configuration file. This section describes some of the settings a user may wish to modify in this way, and how to do it.
If the configuration file does not exist in the user directory
when Stellarium is started (e.g. the first time the user starts the
program), one will be created with default values for all settings
(refer to section for the location
of the user directory on your operating system). The name of the configuration
file is config.ini5.2.
The configuration file is a regular text file, so all you need to edit it is a text editor like Notepad on Windows, Text Edit on the Mac, or nano/vi/gedit etc. on Linux.
The following sub-sections contain details on how to make commonly
used modifications to the configuration file. A complete list of configuration
file values may be found in appendix .
The user interface for setting the observer's longitude and latitude isn't very precise. For users with a penchant for accuracy, satisfaction may be achieved by editing the values in the configuration file like this:
If your screen resolution is not listed in the video tab of the configuration window, you may edit the configuration file to select it. It is also possible to specify how Stellarium should start - in windowed or full-screen mode:
Individual script commands
(see section ) may be entered and executed interactively
using a feature called the script bar. This feature is not
enabled by default, but you can enable it by altering the configuration
file:
Stellarium tries to determine the time zone based on your system settings. It is possible to over-ride this by specifying the time zone in the main configuration file.
Stellarium's behaviour can be modified
by providing parameters to the program when it is run, via the command
line. See table for a full list.
|
To start Stellarium using the configuration file, configuration_one.ini situated in the user directory:
stellarium -c configuration_one.ini
Stellarium is packaged with over 600 thousand stars in the catalogue,
but much larger star catalogues are available for download from the
sourceforge download site.
To use these catalogues, download the files and save them in the stars/default/
sub-directory of either the Installation Directory or the User Directory
(see section ).
There are five extra catalogue files available.
NOTE: You should have at least 512 MiB of RAM to load files stars_4_2v0_0.cat to stars_4_2v0_0.cat, and at least 1 GiB RAM to load the largest file (stars_8_2v0_0.cat).
See section for details of the contents
of these files.
Stellarium has the ability to record and play back sequences of commands in much the same way some applications allow the recording and executing of macros.
Using this mechanism it is possible to create presentations of astronomical events using Stellarium. Two scripts come with Stellarium that explore lunar eclipses. More are likely to be included in future releases of Stellarium5.3.
Scripts are found either <installation directory>/scripts or <user directory>/scripts and have the file name extension .sts. Some scripts may use image files. These may be placed in the same directory as the .sts file unless aome other path is specified in the script when referring to such files.
If you created a new script file while the text menu was active, you must turn off the text menu and turn it on again before the script will be avaiable in the menu.
Pressing CTRL-r will start and
stop script recording. Refer to section
to find out where script files will be created for your operating
system.
Recorded script files are created with a file name, recorded-*.sts, where the * is a three digit number. Thus the first recorded script will be called recorded-000.sts, the second recorded-001.sts and so on.
If you wish to rename a recorded script you should simply navigate
to the scripts sub-directory of the user directory
and rename the file as appropriate (see section
for the location of the user directory on your operating system).
Manually editing a script file may be done
using a simple text editor. To get yourself started, record a quick
script - go to a few objects using find and clicking on them, zoom
in and out using auto-zoom and see what this generates in the script
file. For a complete list of scripting commands see appendix .
This example script shows the occultation of Jupiter by the Moon in 2004. Note that the atmosphere and ground rendering is turned off so that they are not in the way if the location of the observer is set such that the event is not in the night time and/or above the horizon. This is a useful technique for scripting to avoid the need to set the location.
).
Stellarium can simulate light pollution. This
effect is turned on by using the TUI menu. Press the 
key and
navigate to item 6.1: Light Pollution Luminance. If the value
of this setting is greater than 0, an orange glow will be seen in
the night sky. The higher the value, the greater the brightness of
the light pollution.
The brightness of the light pollution will affect the brightness of the stars which are visible at a given zoom level - the more light pollution the brighter stars have to be to be visible.
It is possible to create your own landscapes for Stellarium. There are three types of landscape:
``strip'' panorama
image + a ground image.
For example, the Moon landscape that is provided with Stellarium has the following files:
.../landscapes/moon/apollo17.png
There is also an optional [location] section which is used to tell Stellarium where the landscape is in the solar system. If the [location] section exists, Stellarium can automatically adjust the location of the observer to match the landscape.
The Trees landscape that is provided with Stellarium is an example of the single fish-eye method, and provides a good illustration. The centre of the image is the spot directly above the observer (the zenith). The point below the observer (the nadir) becomes a circle that just touches the edges of the image. The remaining areas of the image (the rounded corners) are not used.
The image file should be saved in PNG format with alpha transparency. Wherever the image is transparent is where Stellarium will render the sky.
The landscape.ini file for a fish-eye type landscape looks like this (this example if for the Trees landscape which comes with Stellarium):
This method uses a more usual type of panorama - the kind which is produced directly from software such as autostitich. The panorama file should be copied into the <config root>/landscapes/<landscape_id> directory, and a landscape.ini file created. The Moon landscape which comes with Stellarium provides a good example of the contents of a landscape.ini file for a spherical type landscsape:
The multiple image method works by having a 360 panorama of the horizon split into a number of smaller ``side textures'', and a separate ``ground texture''. This has the advantage over the single image method that the detail level of the horizon can be increased further without ending up with a single very large image file. The ground texture can be a lower resolution than the parorama images. Memory usage may be more efficient because there are no unused texture parts like the corners of the texture file in the fish-eye method.
On the negative side, it is more difficult to create this type of landscape - merging the ground texture with the side textures can prove tricky. The contents of the landscape.ini file for this landscape type is also somewhat more complicated than for other landscape types. Here is the landscape.ini file which describes the Guereins landscape:
A step-by-step account of the creation of a custom landscape has been
contributed by Barry Gerdes. See Appendix .
An example location section:
planet = Earth
latitude = +48d10'9.707"
longitude = +11d36'32.508"
altitude = 83
Extended objects are those which are external to the solar system, and are not point-sources like stars. Extended objects include galaxies, planetary nebulae and star clusters. These objects may or may not have images associated with them. Stellarium comes with a catalogue of about 13,000 extended objects, with images of over 100.
To add a new extended object, add an entry in the .../nebulae/default/ngc2000.dat
file with the details of the object (where ... is either the installation
directory or the user directory). See section
for details of the file format.
If the object has a name (not just a catalogue number), you should
add one or more records to the .../nebulae/default/ngc2000names.dat
file. See section for details of the file
format.
If you wish to associate a texture (image) with the object, you must
also add a record to the .../nebulae/default/nebula_textures.fab
file. See section for details of the
file format.
Nebula images should have dimensions which are integer powers of two, i.e. 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 ... pixels along each side. If this requirement is not met, your textures may not be visible, or graphics performance may be seriously impacted. PNG or JPG formats are both supported.
Each deep sky image has one line in the ngc2000.dat file in the .../nebulae/default/ directory (where ... is either the installatiom directory or the user directory). The file is a plain ASCII file, and may be edited with a normal text editor. Each line contains one record, each record consisting of the following fields:
| Offset | Length | Type | Description |
| 0 | 1 | %c | Describes the catalogue type. I = Index Catalogue, anything else means NGC |
| 1 | 6 | %d | Catalogue number |
| 8 | 3 | %3s | Sets nType.
Possible values:
'Gx ' NEB_OC
'OC ' NEB_GC
'Gb ' NEB_N
'Nb ' NEB_PN
'Pl '
' '
' - '
' * '
'D* '
'***'
'C+N' NEB_CN
' ? ' NEB_UNKNOWN |
| 12 | 9 | %d %f | Right ascention hour; right ascention minute |
| 21 | 1 | %c | Declination degree sign |
| 22 | 7 | %d %f | Declination degree; Declination minute |
| 40 | 7 | %f | Angular size |
| 47 | 6 | %f | Magnitude |
Each line in the ngc2000names.dat file contains one record. A record relates an extended object catalogue number (from ngc2000.dat) with a name. A single catalogue number may have more than one record in this file.
The record structure is as follows:
| Offset | Length | Type | Description |
| 0 | 35 | %35s | Name (Note that messier numbers should be ``M'' then three spaces, then the number). |
| 37 | 1 | %c | |
| 38 | %d | Catalogue number | |
| 44 | 30? | %s | ? |
If an object has more than one record in the ngc2000names.dat file, the last record in the file will be used for the nebula label.
Each line in the nebula_textures.fab file is one record. Records are whitespace separated so there are not strictly any offsets for particlar fields. Note that filenames may not contains spaces, and are case sensitive.
Lines with the # character in the first column are considered to be comments and will be ignored. Empty lines are ignored.
The record format is as follows:
| Type | Description |
| int | Catalogue number |
| float | Right ascention |
| float | Declination |
| float | Magnitude |
| float | Texture angular size |
| float | Texture rotation |
