Stellarium User Guide

Matthew Gates


Copyright © 2008 Matthew Gates. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".


Contents

1. Introduction

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.

2. Installation

2.1 System Requirements

2.2 Downloading

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.

2.3 Installation

2.3.1 Windows

  1. Double click on the stellarium-0.9.1.exe file to run the installer.
  2. Follow the on-screen instructions.

2.3.2 MacOS X

  1. Locate the stellarium-0.9.1.dmg file in finder and double click on it, or open it using the disk copy program.
  2. Have a browse of the readme file, and drag Stellarium to the Applications folder (or somewhere else if you prefer).
  3. Note that it is better to copy Stellarium out of the .dmg file to run it - some users have reported problems when running directly from the .dmg file.

2.3.3 Linux

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.

2.4 Running Stellarium

Windows
The Stellarium installer creates an item in the Start Menu under in Programs section. Select this to run Stellarium.
MacOS X
Double click on Stellarium (wherever you put it).
Linux
If your distribution had a package you'll probably already have an item in the Gnome or KDE application menus. If not, just use a open a terminal and type stellarium.

3. Interface Guide

Figure: A composite screenshot showing Stellarium in both day time (left) and night time (right)
Image 001

3.1 Tour

After you run Stellarium for the first time, you will see a something like one of the sides of the image shown in Figure [*] (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.

3.1.1 Time Travel

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.


Table: Time control tool-bar buttons
Button Shortcut key Description
Image timerate_decrease j Decrease the rate at which time passes
Image timerate_normal k Make time pass as normal
Image timerate_increase l Increase the rate at which time passes
Image time_normal 8 Return to the current time & date


OK, so lets go see the future! Click the mouse once on the increase time speed button Image timerate_increase. 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 Image timerate_normal. The stars and/or the Sun should stop scooting across the sky. Now press the decrease time speed button Image timerate_decrease 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.

3.1.2 Moving Around the Sky


Table: Controls to do with movement
Key Description
Cursor keys Pan the view left, right, up and down
Page up / Page down Zoom in and out
Backslash (\) Auto-zoom out to original field of view and viewing direction
Left mouse button Select an object in the sky
Space Centre view on selected object
Forward-slash (/) Auto-zoom in to selected object


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.

3.1.3 Main Tool-bar

Figure: Screenshot showing off some of Stellarium's visual effects
Image 002

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.


Table: Main tool-bar buttons
Feature Tool-bar button Key Description
Constellations Image constellation_button c Draws the constellation lines
Constellation Names Image constellation_name_button v Draws the name of the constellations
Constellation Art Image constellation_art_button r Superimposes artistic representations of the constellations over the stars
Azimuth Grid Image grid_button z Draws grid lines for the Alt/Azi coordinate system
Equatorial Grid Image grid_button e Draws grid lines for the RA/Dec coordinate system
Toggle Ground Image ground_button g Toggles drawing of the ground. Turn this off to see objects that are below the horizon
Toggle Cardinal Points Image cardinal_button q Toggles marking of the North, South, East and West points on the horizon
Toggle Atmosphere Image atmosphere_button a Toggles atmospheric effects. Most notably makes the stars visible in the daytime
Nebulae & Galaxies Image nebulae_button n Toggles marking the positions of Nebulae and Galaxies when the FOV is too wide to see them
Coordinate System Image coord_type_button Enter Toggles between Alt/Azi & RA/Dec coordinate systems
Goto Image goto_button Space Centres the view on the selected object
Flip image (horizontal) Image fliph_button CTRL+SHIFT+h Flips the image in the horizontal plane. Note this button is not enable by default. See section [*]
Flip image (vertical) Image flipv_button CTRL+SHIFT+v Flips the image in the vertical plane. Note this button is not enable by default. See section [*]
Search Image find_button CTRL+f Toggle the display of the object search window
Configuration Image config_button 1 (digit one) Toggle the display of the configuration window
Night Mode Image night_mode_button [none] Toggle ``night mode'', which changes the coloring of same display elements to be easier on the dark-adapted eye.
Help Image help_button h Toggle the display of the help window
Quit Image on_off_button CTRL+q Close Stellarium


3.1.4 The Object Search Window

Figure: The search window
Image search_dialog

The Object Search window provides a convenient way to locate objects in the sky. Simply type in the name of an object to find, and then click the ``go'' button or press return. Stellarium will point you at that object in the sky.

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.

3.1.5 Help Window

Figure: The help window
Image help_dialog

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.

3.1.6 Information Window

Figure: The information window
Image info_window

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.

3.1.7 The Text Menu

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 [*]).

3.1.8 Other Keyboard Commands

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  [*])

4. Configuration

Most of Stellarium's configuration is done using the configuration window. To open the configuration window, click the Image config_button 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.

4.1 Setting the Date and Time

Figure: Configuration window, Date & Time tab
Image date_and_time_dialog

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

4.2 Setting Your Location

Figure: Configuration window, location tab
Image location_dialog

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:

  1. You can set your location by where you live on the map. This is convenient, but it isn't very precise. You can zoom in and out of the map by rolling the mouse wheel, and drag zoomed-in the map around with the right mouse button.
  2. If you know your longitude and latitude4.3, you might want to can set it using the controls at the bottom of the window.
  3. In the Landscape tab of the configuration window, check the ``Setting landscape updates the location'' box, and select a new landscape. The obserever location will be set to the location for that landscape.
Once you're happy that the location is set correctly, click on the ``Save Location'' button, and close the configuration window.

4.3 Setting the Landscape Graphics

Stellarium has several horizon graphics or landscapes. These may be changed by choosing the options under the Landscapes tab in the configuration window.

Figure: [*]Changing the landscape
Image landscapes_dialog

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.

4.4 Video Mode Settings

Figure: Setting up the video mode
Image video_dialog

The Video tab in the configuration window (figure [*]) offers the following setting options:

Projection
Selecting items in this list changes the projection method which Stellarium uses to draw the sky. Options are:

perspective
Perspective projection keeps the horizon a straight line. The maximum field of view is $ 150^{\circ}$ . The mathematical name for this projection method is gnomonic projection.
orthographic
Orthographic projection is related to perspective projection, but the point of perspective is set to an infinite distance. The maximum field of view is $ 180^{\circ}$ .
equal area
The full name of this projection method is, Lambert azimuthal equal-area projection. The maximum field of view is $ 360^{\circ}$ .
fisheye
Stellarium draws the sky using azimuthal equidistant projection. In fish-eye projection, straight lines become curves when they appear a large angular distance from the centre of the field of view (like the distortions seen with very wide angle camera lenses). This is more pronounced as the user zooms out. The maximum field of view in this mode is $ 180^{\circ}$
stereographic
This mode is similar to fish-eye projection mode. The maximum field of view in this mode is $ 235^{\circ}$
cylinder
The full name of this projection mode is cylindrical equidistant projection. The maximum field of view in this mode is $ 233^{\circ}$
Disk viewport
This check-box, when selected, adds a black circular border around the main view. Using the zoom functions to set the field of view, it's possible to simulate looking through binoculars or a telescope eyepiece - useful if you want to know how much of a constellation you can see at once with a given instrument.
Viewport Distorter
This is a special modifier to the projection mode intended for use with a projector and a spherical mirror. With this set up it is possible to create a low-cost projection system for making a small planetarium.

4.5 Rendering Options

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.

Figure: Configuration window, rendering tab
Image rendering_options


Table: Display options in the configuration window rendering tab
Control Name Action when selected
Stars Turns on the drawing of the stars. The drawing of the Sun is not affected
Stars Names Up to mag Turns on the labelling of named stars. There is a spin box next to this option which controls the brightest magnitude of the stars that are labelled (remember, the lower the number, the brighter the star!)
Star Twinkle Amount Turns on star twinkles. There is a spin box for setting the amount of twinkle
Constellations Lines Turns on the drawing of the lines between stars that help to visualise the constellations
Constellations Names Turns on name labels near the centre of each constellation
Nebulas Names. Up to mag Turns on the drawing of nebulae and galaxies. A limit may be set as to the magnitude of the objects which will be shown
Also display Nebulas without textures When selected, nebulae for which there are no images are also displayed (as yellow and grey blobs)
Planets Turns on drawing of the planets (Mercury, Venus etc.)
Moon Scale Magnifies the size of the moon by 4x. People perceive the Moon to have a larger angular size than it actually does. This feature compensates for this illusion (which doesn't apply so much to computer screens as it does in the sky!)
Planets Hints Draws a small circle around the planets, and labels them with the appropriate name
Equatorial Grid Draws grid lines for the RA/Dec coordinate system (see section [*])
Equator Line Draws the celestial equator line
Azimuthal Grid Draws grid lines for the Altitude/Azimuth coordinate system (see section [*])
Ecliptic Line Draws the ecliptic line
Ground Draws the ground. If this option is de-selected, the ground becomes transparent. Note that the daylight effects go a bit weird if you do this, so it's usually a good idea to turn of atmosphere if you turn off ground. It might also be helpful to use the equatorial coordinate system when the ground is turned off
Cardinal Points Draws markers for North, South, East and West on the horizon
Atmosphere Draws atmospheric effects. This means the sky brightens when the sun is above the horizon, and that there is a haze around the moon
Fog Draws a slight fog near to the horizon
Meteor Rate per minute Changes the rate at which meteors are displayed4.4


4.6 Language Settings

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:

Program Language
This is the language which is used for the user interface of the program, i.e. text in windows, mouse-over hints for the button bars etc. If you change this setting, you must save settings and re-start stellarium for your changes to take effect.
Sky Language
This is the language used to label astonomical objects such as the planets. Changes to this setting come into effect immediatley.
Sky Culture
The sky culture is the astronomical tradition used to define the constellations and common star names. This setting also affects constellation art. Changes to this setting come into effect immediatley.
Save as default button
This buttons saves yor language settings so that future Stellarium sessions use the settings. If you do not save, your changes will be lost when Stellaium exits.
Figure: Configuration window, language tab
Image language_dialog

5. Advanced Use

5.1 Files and Directories

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.

5.1.1 Windows

installation directory
By default this is C:\Program Files\Stellarium\, although this can be adjusted during the installation process.
user directory
This is the Stellarium sub-folder in the Application Data folder for the user account which is used to run Stellarium. Depending on the version of Windows and its configuration, this could be any of the following (each of these is tried, if it fails, the next in the list if tried).

%APPDATA%\Stellarium\

%USERPROFILE%\Stellarium\

%HOMEDRIVE%\%HOMEPATH%\Stellarium\

%HOME%\Stellarium\

Stellarium's installation directory

Thus, on a typical Windows XP system with user ``Bob Dobbs'', the user directory will be:

C:\Documents and Settings\Bob Dobbs\Application Data\Stellarium\
Stellarium version 0.9.0 did use the %APPDATA%\Stellarium folder. Thus if a config.ini file exists in the %USERPROFILE%\Stellarium\ directory, that will be oser in preference to the %APPDATA%\Stellarium\ directory. This is to prevent users of version 0.9.0 from losing their settings when they upgrade.

screenshot save directory
Screenshots will be saved to the Desktop.
script save directory
Recorded scripts will be saved in the scripts sub-folder of the user directory.

5.1.2 MacOS X

installation directory
This is found inside the application bundle, Stellarium.app. See the Inside Application Bundles for more information.
user directory
This is the Library/Preferences/Stellarium/ sub-directory of the users home directory.
screenshot save directory
Screenshots are saved to the users Desktop.
script save directory
Recorded scripts will be saved in the scripts sub-folder of the user directory.

5.1.3 Linux

installation directory
This is in the share/stellarium sub-directory of the installation prefix, i.e. usually /usr/share/stellarium or /usr/local/share/stellarium/.
user directory
This is the .stellarium sub-directory of users home directory, i.e. ~/.stellarium/.
screenshot save directory
Screenshots are saved to the users home directory.
script save directory
Recorded scripts will be saved in the scripts sub-folder of the user directory, i.e. ~/.stellarium/scripts/.

5.1.4 Directory Structure

Within the installation directory and user directory (defined in section [*]), files are arranged in the following sub-directories.

landscapes/
contains data files and textures used for Stellarium's various landscapes. Each landscape has it's own sub-directory. The name of this sub-directory is called the landscape ID, which is used to specify the default landscape in the main configuration file.
skycultures/
contains constellations, common star names and constellation artwork for Stellarium's many sky cultures. Each culture has it's own sub-directory in the skycultures directory.
scripts/
contains scripts and files which are used by scripts (e.g. images used in a script).
nebulae/
contains data and image files for nebula textures. In future Stellarium will be able to support multiple sets of nebula images and switch between them at runtime. This feature is not implemented for version 0.9.1, although the directory structure is in place - each set of nebula textures has it's own sub-directory in the nebulae directory.
stars/
contains Stellarium's star catalogues. In future Stellarium will be able to support multiple star catalogues and switch between them at runtime. This feature is not implemented for version 0.9.1, although the directory structure is in place - each star catalogue has it's own sub-directory in the stars directory.
data/
contains miscellaneous data files including fonts, solar system data, city locations etc.
textures/
contains miscellaneous texture files, such as the graphics for the toolbar buttons, planet texture maps etc.
If any file exists in both the installation directory and user directory, the version in the user directory will be used. Thus it is possible to override settings which are part of the main Stellarium installation by copying the relevant file to the user area and modifying it there.

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.

5.2 The Main Configuration File

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 [*].


5.2.1 Setting Your Location Precisely

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:

[init_location] 
name = Widdringon 
latitude = +55 14'30.00" 
longitude = -01 37'6.00" 
altitude = 53
The values for longitude and latitude are positive for North and East, negative for South and West. The format of the number is in degrees minutes and seconds. The value for the altitude is in meters.

5.2.2 Setting the Display Resolution

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:

[video]  
fullscreen = true 
screen_w = 1680 
screen_h = 1050

5.2.3 Enabling the Script Bar

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:

[gui] 
flag_show_script_bar = true
The script bar appears in the main tool-bar as a long button containing a > prompt. Clicking on it with the mouse will give it focus - it will grab keyboard input. After typing a command (e.g. select planet Mercury) pressing Enter will execute it. You may also use the up and down cursor keys to navigate through previously executed commands.

5.2.4 Setting the Time Zone

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.

[init_location] 
timezone = CET

5.3 Command Line Options

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.


Table: Command line options
Option Option Parameter Description
-help or -h [none] Print a quick command line help message and exit.
-version or -v [none] Print the program name and version information, and exit.
-config-file or -c config file name Specify the configuration file name. The default value is config.ini.

The parameter can be a full path (which will be used verbatim) or a partial path.

Partial paths will be searched for inside the regular search paths unless they start with a ``.'', which may be used to explicitly specify a file in the current directory or similar.

For example, using the option -c my_config.ini would resolve to the file <user directory>/my_config.ini whereas -c ./my_config.ini can be used to explicitly say the file my_config.ini in the current working directory.

-full-screen yes or no Over-rides the full screen setting in the config file.
-home-planet planet Specify observer planet (English name).
-altitude altitude Specify observer altitude in meters.
-longitude longitude Specify latitude, e.g. +53d58\'16.65\"
-latitude latitude Specify longitude, e.g. -1d4\'27.48\"
-list-landscapes [none] Print a list of available landscape IDs.
-landscape landscape ID Start using landscape whose ID matches the passed parameter (dir name for landscape).
-sky-date date The initial date in yyyymmdd format.
-sky-time time The initial time in hh:mm:ss format
-fov angle The initial field of view in degrees.
-projection-type ptype The initial projection type (e.g. perspective).


5.3.1 Examples

To start Stellarium using the configuration file, configuration_one.ini situated in the user directory:

stellarium -config-file=configuration_one.ini

stellarium -c configuration_one.ini

5.4 Getting Extra Star Data

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.

5.5 Scripting

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.

5.5.1 Running Scripts

  1. Press the m key to open the text menu. Use the cursor keys to select option 7.1 (local scripts). Press return and the "select and exit to run" text will be highlighted.
  2. Use the up and down cursor keys to select your script. Press return and then exit the text menu with the m key and the script will start to execute.
Note that while scripts are running, some key bindings are altered. Specifically, the time-rate keys j, k and l alter the rate at which the script progresses, and may press CTRL-c to stop the script and result normal operation.

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.

5.5.2 Recording Scripts

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

5.5.3 Editing Scripts

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 [*].

5.5.4 Example script

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.

clear 
flag atmosphere off 
flag ground off 
wait duration 2 
date local 2004:12:7T8:39:32 
select planet Jupiter pointer off 
flag track_object on 
zoom fov 0.5 
wait duration 2 
timerate rate 30 
script action end 

5.5.5 Scripting Hints and Tips

5.6 Visual Effects

5.6.1 Light Pollution

Stellarium can simulate light pollution. This effect is turned on by using the TUI menu. Press the $ m$ 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.

5.7 Customising Landscapes

It is possible to create your own landscapes for Stellarium. There are three types of landscape:

Single Fish-eye Method
Using a fish-eye panorama image.
Single Spherical Method
Using a spherical panorama image.
Multiple Image Method (also called ``old style'' landscapes)
Using a series of images split from a $ 360^{\circ}$ ``strip'' panorama image + a ground image.
Each landscape has it's own sub-directory in <user directory>/landscapes or <installation directory>/landscapes. The name of the sub-directory is called the landscape ID. The sub-directory must contain a file called landscape.ini which describes the landscape type, texture filenames and other data. Texture files for a landscape should by put in the same directory as the landscape.ini file, although if they are not found there they will be searched for in the .../textures directory, allowing shared files for common textures such as the fog texture.

For example, the Moon landscape that is provided with Stellarium has the following files:

.../landscapes/moon/landscape.ini

.../landscapes/moon/apollo17.png

The landscsape.ini file must contain a section called [landscape], which contains the details necessary to render the landscape (which vary, depending on the type of the landscape).

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.

5.7.1 Single Fish-eye Method

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

[landscape] 
name = Trees 
type = fisheye 
maptex = trees_512.png 
texturefov = 210
Where:

name
is what appears in the landscape tab of the configuration window.
type
identifies the method used for this landscape. ``fisheye'' in this case.
maptex
is the name of the image file for this landsape.
texturefov
is the field of view that the image covers in degrees.

5.7.2 Single Panorama Method

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:

[landscape]  
name = Moon  
type = spherical  
maptex = apollo17.png
Where:

name
is what appears in the landscape tab of the configuration window.
type
identifies the method used for this landscape. ``spherical'' in this case.
maptex
is the name of the image file for this landsape.
Note that the name of the section, in this case [moon] must be the landscsape ID (i.e. the same as the name of the directory where the landscape.ini file exists).

5.7.3 Multiple Image Method

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.

Figure: Multiple Image Method of making landscapes.
Image faq_landscape

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:

[landscape] 
name = Guereins 
type = old_style 
nbsidetex = 8 
tex0 = guereins4.png 
tex1 = guereins5.png 
tex2 = guereins6.png 
tex3 = guereins7.png 
tex4 = guereins8.png 
tex5 = guereins1.png 
tex6 = guereins2.png 
tex7 = guereins3.png 
nbside = 8 
side0 = tex0:0:0.005:1:1 
side1 = tex1:0:0.005:1:1 
side2 = tex2:0:0.005:1:1 
side3 = tex3:0:0.005:1:1 
side4 = tex4:0:0.005:1:1 
side5 = tex5:0:0.005:1:1 
side6 = tex6:0:0.005:1:1 
side7 = tex7:0:0.005:1:1 
groundtex = guereinsb.png 
ground = groundtex:0:0:1:1 
fogtex = fog.png 
fog = fogtex:0:0:1:1 
nb_decor_repeat = 1 
decor_alt_angle = 40 
decor_angle_shift = -22 
decor_angle_rotatez = 0 
ground_angle_shift = -22 
ground_angle_rotatez = 45 
fog_alt_angle = 20 
fog_angle_shift = -3 
draw_ground_first = 1
Where:

name
is the name that will appear in the landscape tab of the configuration window for this landscape
type
should be ``old_style'' for the multiple image method.
nbsidetex
is the number of side textures for the landscape.
tex0 ... tex<nbsidetex-1>
are the side texture file names. These should exist in the .../textures/landscapes directory in PNG format.
nbside
is the number of side textures
side0 ... side<nbside-1>
are the descriptions of how the side textures should be arranged in the program. Each description contains five fields separated by colon characters (:). The first field is the ID of the texture (e.g. tex0), the remaining fields are the coordinates used to place the texture in the scene.
groundtex
is the name of the ground texture file.
ground
is the description of the projection of the ground texture in the scene.
fogtex
is the name of the texture file for fog in this landscape.
fog
is the description of the projection of the fog texture in the scene.
nb_decor_repeat
is the number of times to repeat the side textures in the 360 panorama.
decor_alt_angle
is the vertical angular size of the textures (i.e. how high they go into the sky).
decor_angle_shift
vertical angular offset of the scenery textures, at which height are the side textures placed.
decor_angle_rotatez
angular rotation of the scenery around the vertical axis. This is handy for rotating the landscape so North is in the correct direction.
ground_angle_shift
vertical angular offset of the ground texture, at which height the ground texture is placed.
ground_angle_rotatez
angular rotation of the ground texture around the vertical axis. When the sides are rotated, the ground texturer may beed to me ratated as well to match up with the sides.
fog_alt_angle
vertical angular size of the fog texture - how fog looks.
fog_angle_shift
vertical angular offset of the fog texture - at what height is it drawn.
draw_ground_first
if 1 the ground is drawn in front of the scenery, i.e. the side textures will overlap over the ground texture.
Note that the name of the section, in this case [guereins] must be the landscsape ID (i.e. the same as the name of the directory where the landscape.ini file exists).

A step-by-step account of the creation of a custom landscape has been contributed by Barry Gerdes. See Appendix [*].

5.7.4 landscape.ini [location] section

An example location section:

[location]

planet = Earth

latitude = +48d10'9.707"

longitude = +11d36'32.508"

altitude = 83

Where:

planet
Is the English name of the solar system body for the landscape.
latitude
Is the latitude of site of the landscape in degrees, minutes and seconds. Positive values represent North of the equator, negative values South of the equator.
longitude
Is the longitude of site of the landscape. Positive values represent East of the Greenwich Meridian on Earth (or equivalent on other bodies), Negative values represent Western logitude.
altitude
Is the altitude of the site of the landscape in meters.

5.8 Adding Nebulae Images

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.

5.8.1 Modifying ngc2000.dat

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

5.8.2 Modifying ngc2000names.dat

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.

5.8.3 Modifying nebula_textures.fab

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