Extending the Stellarium virtual planetarium

Star Power

Article from Issue 186/2016

Expand the Stellarium virtual planetarium with new objects and environments in just a few simple steps.

The Stellarium planetarium program shows a realistic sky in 3D, calculates and displays star movements, and lets you prepare and evaluate observations. A previous article [1] introduced the software and looked at some of its capabilities. In this article, I focus on extending the software with plugins, additional materials, and little-known features.


Most distributions offer Stellarium version 0.13.3 in their repositories, which is the version I discuss here. Version 0.14.2 was released January 2016 [2]. You can install the program on newer computers without problem; however, it isn't possible on older systems if they don't support OpenGL 2.1 or later. Your only recourse then is to install the legacy program, version 0.9.

The directories for the program's files are based on the Linux standard: The data resides in /usr/share/stellarium/, and you should not change the data in this directory or its subdirectories. Only on rare occasions with a compelling need should you access this directory with root privileges. The program stores userspace data below ~/.stellarium/. Naturally this directory is empty immediately after the installation.

To track notifications, start the program in the terminal by entering stellarium. The landscape often fills up the screen before you can finish reading all the output; if necessary, you can re-read the messages in the ~/.stellarium/log.txt file.

Depending on the time of day, you'll see either a virtual, cloudless sky or the night sky (Figure 1). Vertical and horizontal bars with buttons appear when you move the mouse to the bottom left corner. If you click the small black triangles there, the bars stay on the screen permanently.

Figure 1: Stellarium usually starts in full-screen mode. The controls only appear if you move the cursor into the bottom left corner.

Clicking the rectangle with outward-pointing arrows in the center of the bottom bar (or pressing F11) toggles between full-screen and window mode; clicking the icon at the bottom right terminates the program.

You can determine the visible display detail using the top two icons in the vertical menu to select the location (top) and time of day (next from top). An observer in Casper, Wyoming, on March 4, 2016, would see the sky shown in Figure 1 looking southwest at 21:56.


The icons on the left in the bottom menu bar turn on the constellations. Asterism names differ depending on the culture chosen. With the Western default setting, names of stars and constellations in the northern hemisphere were derived from Greek and Arabic astronomy; in the southern hemisphere, names were assigned during medieval seafaring in the Age of Discovery.

To select the cultural basis of names, use the third icon from the top in the vertical menu column, click the Starlore tab, then check the Use native names for planets from current culture box at the bottom.

Constellations reside in the /usr/share/stellarium/skycultures/western subdirectory as 512x512-pixel black and white photos. In Figure 2, I replaced the warrior Orion with a butterfly image from Wikipedia [3] (Figure 3). The stars that make up the belt now represent the body of the butterfly, and Rigel and Betelgeuse form the tips of the wings. Stellarium interprets black as transparent, and the PNG images do not need an alpha channel. The program also accepts images in JPG format, and it doesn't seem to require square images.

Figure 2: Stellarium displays constellations on request, which you can replace with your own pictures as required. (Landscape GFDLv1.2 [4])
Figure 3: This butterfly against a black background is suitable as a new image for the Orion constellation. (CC-BY-SA 4.0 [5])

The easiest way to project the butterfly on the sky is to replace the image file /usr/share/stellarium/skycultures/western/orion.png with your own photo of the same name. A better approach, however, would be to expand the program without deleting anything. The "Own Constellations" section summarizes the steps for doing this.

Own Constellations

To begin, copy the /usr/share/stellarium/skycultures/western/ directory to ~/.stellarium/skycultures/western. To do this, create the skycultures subdirectory.

Now, rename the western subdirectory (e.g., to westernm), edit the .stellarium/skycultures/westernm/info.ini file, and replace the name western there with the name of the new directory, westernm. Next, replace the orion.png image file with your own image.

In constellation_names.eng.fab, change the line

Ori  "Orion"  _("Orion")


Ori  "Orion"  _("Orion Butterfly")

The butterfly thus has its own name. After restarting, a new entry called Westernm can be found in the Starlore tab. If you select it, the butterfly appears in the sky.

Your Own Landscape

Stellarium provides a series of landscape images over which the stars stretch. A sample image [6] is fine for experimenting with your own environment [7]. A Stellarium panorama image has edges that fit together seamlessly with a cylindrical equidistant projection (Sky and viewing option window | Markings | Cylinder) that covers 360 degrees in width and 180 degrees in height (i.e., a width-to-height ratio of 2:1). In this kind of projection, longitudes map to equally spaced vertical lines and latitudes map to horizontal lines.

To create your own panorama for Stellarium from an original image, you first need to change the width of the image to 4048 pixels without distortion. Then, embed the photo in a 4048x2024-pixel transparent background so that the horizon is in the middle (Figure 4). Any transparent areas on the bottom of the image must be colorized; otherwise, stars will shine through. The sky, then, is made transparent. Finally, save the image in PNG format.

Figure 4: A panorama that you can install in a few steps in Stellarium. (Top) original panorama. (Bottom) scaled image with transparent sky.

To integrate the new panorama in Stellarium, you must first create the stellarium/landscapes/mountain user directory. The name mountain refers to the new environment. Copy the edited Panorama – spitzkoppe_4048.png in this example – to mountain/spitzkoppe_4048.png.

More data relating to the environment is found in the mountain/landscape.ini file (Listing 1). Line 5 specifies the projection, and line 6 the name of the image file. Lines 8 and 9 refer to images that the software places over the panorama, as required. They are commented out in this example. To integrate new images correctly, just create them in the same way as the panorama. It is important that the length-to-width ratio matches. Lines 11 to 14 define the location; but Stellarium doesn't evaluate this information. After restarting Stellarium, a new entry called Mountain appears in the Sky and viewing options window icon (third from the top) below the Landscapes tab.

Listing 1


01 [landscape]
02 name = mountain
03 author = Ikiwaner / Wikipedia
04 description = Spitzkoppe; source: https://commons.wikimedia.org/wiki/File:Spitzkoppe_360_Panorama.jpg
05 type = spherical
06 maptex = Spitzkoppe_4048.png
07 ;maptex_illum = Spitzkoppe_illum.png
08 ;maptex_fog = Spitzkoppe_fog.png
10 [location]
11 planet = Earth
12 latitude = -21d52'09"
13 longitude = +15d11'59"
14 altitude = 1000

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Stellarium

    If you like astronomy but you don’t like sitting outside on cold nights, try stargazing from a virtual planetarium.

  • FOSSPicks

    Graham Morrison looks at VCV Rack, Audible Instruments, TripleA, Neofetch 3.3.0, TripleA, Eolie 0.9, and more!

  • FOSSPicks

    This month Graham reviews Tuning Workbench Synth, Stellarium 1.0, sake, Wonder Shaper, and Samplebrain.

  • Google Open Sources Liquid Galaxy

    The cluster of computers that create 360-degree live panoramas is now open.

  • Gifts for Gamers: Some End-of-Year Recommendations, Part 1

    Christmas is a time for rest and contemplation. To intersperse the period with some distraction on long winter evenings, a number of Linux games can prove some diversion, as this article will show.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More