Using Stellarium to generate animated simulations

Fabien Chéreau released the first version of Stellarium back in 2001 as a free, open source software package. Since then, developers have continued working to drive the software forward. Version 0.14.2 [1] was released in January 2016. Even so, version 0.13 is available in the source packages for all of the common distributions and is sufficient for most purposes. The current version has an advantage in that the developers corrected an annoying scripting error that had occurred in all previous versions. The software can be updated via the commands in Listing 1. A package or updates obtained from an unofficial source may contain defects.

$ sudo add-apt-repository ppa:stellarium/stellarium-releases
$ sudo apt-get update
$ sudo apt-get install stellarium
$ sudo apt-get upgrade

The concept underlying this software was introduced in a previous issue of Ubuntu User [2]. Additional user options deal with augmenting information about the astronomical objects and using scripting for controlling the display of the sky.

The basic Stellarium package contains data for approximately 600,000 stars with brightness of at least 10.5 magnitude (magnitude refers to the apparent brightness of stars). Under optimal conditions, humans can see around 6,000 stars, with magnitude 6 stars being the smallest discernible by the naked eye. This means that Stellarium displays the night skies as they are seen by the naked eye but also shows celestial objects that would otherwise be visible only through a telescope. For the user, the star catalogs offered by Stellarium are therefore important (see the "Star Catalogs" box for details).

Improving Stellarium

The software generates a status message when booted from the command line. For the first boot, the program should be called with the switch - -full-screen no . This setting disallows full-screen mode, thus making the terminal visible.

The option for installing extra data files about stars is found in the Configuration | Tools menu. Moving the mouse to the left edge of the window lets you select the suitable icon. Catalog 5 will add almost 2 million stars of up to magnitude 12. Catalog 9 extends the range to magnitude 18. A particular star with this magnitude is discussed later in this article.

The star catalogs for the basic version of Stellarium are found in the program directory /usr/share/stellarium/stars/default . Storing the catalog in this location prevents the user from accidentally making modifications. All of the extensions are stored in ~/.stellarium/ , except for the new stars, which are stored in ~/.stellarium/stars/default .

Large, real-life planetariums project displays of celestial objects by transmitting light through perforated spheres. Because these spheres are dependent on a single source of light, they cannot account for variations in the brightness of the objects. This shortcoming is remedied by using instruments to adjust the surface of each star according to its observed brightness.

Stellarium utilizes this approach as well. However the apparent size of the star reflects observations made by optical instruments, such as the human eye or a telescope equipped with a camera. Otherwise, it would be nearly impossible to recognize the stars and their colors. The program does have settings that permit the user to control the size of the star surface to a certain degree.

However, Stellarium distinguishes between objects such as planets, which have a discernible surface, and stars, which can look like mere points in the sky. More stars become visible as you zoom in on the sky with the mouse wheel. The surface area of the stars will barely change in appearance, but the planets will take on texture. The inner planets become illuminated as a crescent shape.

Larger stars come with an information box that contains their name. Clicking on the object with the left mouse button opens the box. Clicking with the right mouse button closes the box.

Controls in Hand

The Stellarium search function can be used to locate objects that are only visible when viewed through high-performance telescopes. Alternatively, the user can write a script that charts the coordinates for a target object and displays the path taken to arrive at the target as a small celestial show. (See the "Star Coordinates" box for more details.)

Adding data for stars of up to magnitude 18 makes it possible for the program to display even a small star at the correct location.

User-defined scripts are placed in the ~/.stellarium/scripts directory. These scripts are stored in text files. The scripting language uses syntax that borrows heavily from JavaScript. Therefore, the user should copy the instructions from Listing 2 into a text file and then save it with a suitable name and the extension .scc to the script directory.

core.moveToRaDecJ2000(-113.0564 , -0.8993, 0);

After restarting Stellarium, you can call the script via Configuration | Script . Any comments and error messages will appear in the terminal window. If necessary, the script can be edited retroactively. Changes are implemented without the need to restart the program. It suffices instead to stop the script, save the changes, and restart the script.

An initial invocation of the program may well be disappointing. Although Stellarium will point out the correct location in the sky, the Einstein ring may be covered by the day sky and the earth. Therefore, the user may need to use the mouse to switch the atmosphere, the foreground, and the clock using the icons in the menu at the bottom of the screen. If so, the user should turn the mouse wheel until the star appears. If an additional image of the Einstein ring has been installed, the display screen will look approximately like the example in Figure 1. Otherwise, only an inconspicuous point with magnitude 17.95 will be visible. As it turns out, this point does not actually represent a star, but rather two galaxies.

Figure 1: A script command can be used to point the virtual planetarium automatically to the Einstein ring.

The script in Listing 3 performs the same task as that performed by Listing 2, except that animation has been added. In line 18, the user will recognize the command from Listing 2, which positions the section of the sky at the correct star coordinates. The third parameter is non-zero and controls how fast the virtual telescope pivots. In this case, the pivoting occurs within 10 seconds.

01 // Name: Einsteinring SDSS J162746.44-005357.5
02 // License: Public Domain
03 // Author: rp 2016
04 // Description: Locate and zoom to the Einstein ring SDSS J162746.44-005357.5. In order to make the ring visible, the user first needs to add its image to the nebulae.
05
06 core.debug("Einsteinring");
07 core.goHome();
08 StarMgr.setLabelsAmount(3);
09 LabelMgr.deleteAllLabels();
10 label = LabelMgr.labelScreen("Einsteinring SDSS J162746.44-005357.5", 20, 20, false, 30, "#aa0000");
11 LabelMgr.setLabelShow(label, true);
12 LandscapeMgr.setCurrentLandscapeID("grossmugl",5);
13 LandscapeMgr.setFlagLandscape(true);
14 LandscapeMgr.setFlagAtmosphere(true);
15 core.wait(2)
16 core.setTimeRate(0);
17 core.debug("def. line of vision");
18 core.moveToRaDecJ2000(-113.0564 , -0.8993, 10);
19 core.wait(8);
20 core.debug("def. image detail");
21 StelMovementMgr.zoomTo(0.8, 15);
22 LandscapeMgr.setFlagLandscape(false);
23 LandscapeMgr.setFlagAtmosphere(false);
24 core.wait(10);
25 core.debug("display star labels");
26 StarMgr.setLabelsAmount(10);
27 core.wait(6)
28 core.debug("zoom in + display grid lines");
29 GridLinesMgr.setFlagAzimuthalGrid(true);
30 StelMovementMgr.zoomTo(0.01, 15);
31 core.wait(8)
32 label = LabelMgr.labelScreen("Diameter: 2 arcsec", 20, 60, false, 30, "#aa0000");
33 LabelMgr.setLabelShow(label, true);

Lines 1 through 4 are comment lines. The reserved words Name , License , Author , and Description are the identifiers that Stellarium inserts as short descriptions into the script.

The core.debug command in line 6 lists its parameters in the terminal output, which lets the user immediately figure out how far the script has advanced. Line 7 opens the view to the sky as if the program had just been started, and line 8 limits the output of labels to those for the large stars. For the higher magnifications in line 26, the program outputs all of the names known to it.

Line 10 writes its own text on the screen. Lines 12 through 14 control the appearance of the landscape. Line 16 stops the time; otherwise, stars shown at a high magnification would disappear too quickly from the display screen because of the earth's rotation. The program pauses for eight seconds in line 19 until the line of vision sets itself. Line 21 controls the magnification via the aperture angle. It takes 15 seconds to show a 0.8 degree section of the sky.

In line 30, the script zooms in further into the section of the sky. A short pause makes apparent the extent of magnification required for viewing the object. The grid lines (line 29) indicate the scale.