Stellarium and NightShade resources

Written by Paul Bourke

New: Update for Stellarium and NightShade, May 2012
New: Update for Stellarium version 11.1
New: Update for version 0.9

Stellarium warped for spherical mirror projection

Please note that the configuration options discussed here have been tested on the Mac OS-X version 0.8 of Stellarium unless otherwise noted. The config file on that platform is located in the directory (~/Library/Preferences/Stellarium). In general they have also only been tested with the projector-mirror-dome are arranged in the orientation preferred by the author, it is also the optimal setup for a number of reasons.

The following are some brief notes and recommendations on how to configure Stellarium so that it warps images correctly for projection using a spherical mirror. For more details on this form of projection see the following: dome projection on a budget. It is not intended for this document to discuss details of dome design, what projector models work best, what mirror size to choose, or how to source first surface mirrors, and so on .... for a discussion of these and other questions please contact the author.

At the time of writing the latest version of Stellarium was 0.8.2, as such these comments refer to that version. This was the first version with spherical mirror distortion support and there are still issues to be resolved, hopefully in the release of the next version at which point this document will be updated. The current implementation is at least functional.

Recommended configuration

There are a large number of ways the spherical mirror and projector can be arranged within the dome space. One of the key advantages of this technique, compared to fisheye solutions, is that the projection gear can be moved to the edge of the dome thus freeing up the best viewing position, the center. Therefore the recommended mirror position is up against the rim of the dome, the projector will be placed some distance along the line from the mirror center to the dome center. The exact position depends on the size of the mirror, the throw and zoom of the projector, and the degree of dome coverage you with to achieve. Typically I use and recommend mirrors with a radius of 0.37m or larger (smaller than this limits the choice of projectors due to focus limitations). The projector, if it has the throw of most commodity projectors, will typically be located around 1m away from the mirror. In the case of Stellarium, and indeed for almost all spherical mirror style projection, the center of the mirror, the center of the dome, the center of the light source, the zenith of the dome and the optical axis of the projector, are all assumed to lie in the same plane.

The coverage of the projector frustum on the mirror is of course variable and controls the amount of dome coverage. There is a tradeoff between dome coverage and the pixel efficiency (ie: image resolution and therefore perceived quality). In other words, if only a small portion of the mirror is used the dome coverage will be lower but at a higher resolution than if a larger portion of the spherical mirror is used. As a starting point and the coverage recommended by the author as a good compromise is as follows: align the lower row of pixels from the projector to lie along the mirror equator, position and/or zoom the projector so that the center of the upper row of pixels lie along the top of the mirror. Note that the mirror shown is of the security/safety type that is less than a 1/4 sphere, for images and measurements see this.

Stellarium configuration 0.8.2

In Stellarium V0.8.2 the option for running in spherical mirror mode can be found in the configuration menu (video tab), the option can be made permanent within the config.ini file. The later file also allows one to set up the geometric parameters required for a correctly warped result. In general, for a successful result you will need to run Stellarium in full screen mode.

fullscreen                     = true
distorter                      = fisheye_to_spheric_mirror

One usually will want to limit the fisheye image to the unit circle, this option (viewport) is also available through the configuration window.

type                           = fisheye
viewport                       = disk

The screen width and height options should be set to the native resolution of your projector. You will however get better results if you set the resolution higher as long as:

This "trick" in order to get higher quality results depends on the scalar found within the projector and may not be required in the next release of Stellarium.

Given the configuration described above and a 5m radius dome, the following would be a convenient starting point for the warping parameters. Please note that the flipping options will only work in the next release, at that time one will be able to view and drive using the computer display. The mirroring will be achieved by setting the projector to horizontal flip mode (eg: "floor-rear" configuration, the exact terminology may change depending on the projector manufacturer).

projector_gamma                = 0.3
projector_position_x           = 0.0
projector_position_y           = 4.0
projector_position_z           = 0
mirror_position_x              = 0.0
mirror_position_y              = 5.0
mirror_position_z              = 0.0
mirror_radius                  = 0.37
dome_radius                    = 5
zenith_y                       = 0
scaling_factor                 = 1.2
flip_horz                      = true
flip_vert                      = false

Most of the above are self explanatory. The position of the projector is a little ambiguous because it isn't always obvious where the focal point is, as a rough measure a position 5cm behind the front of the lens will be close. In order to align the imagery more precisely on the dome I suggest turning on the azimuthal grid (z key) and look straight up. The pole can be aligned to the pole of the dome and the horizon line aligned to the rim of the dome. Achieve this by varying the "scaling_factor" and the "zenith_y". The scaling factor is essentially adjusting for the projector zoom and throw. The zenith_y is adjusting the overall tilt of the projector frustum.

For example, if the zoom is increased in the above configuration to 1.0 the result is shown in the image on the left below. the vertical zenith value can be dropped to lower and correctly position the bottom of the image to the spring line (as described above) of the dome.


When doing the alignment it is helpful to make the azimuthal grid as clear as possible. The following is one way to do this.

projector_gamma                = 0
azimuthal_color                = 1.0,1.0,1.0

The next most common adjustment is to reduce the projector position to be below the mirror so that light can be reflected over the top without causing a shadow (projector_position_z < 0). While this can be a rather tedious and repetitive process (adjusting both scaling and zenith value to get the right result), it only has to be performed once for a given configuration.

In the navigation section I suggest the following.

init_fov                       = 180
init_view_pos                  = 0.000001,0,0.99999

In general one wants to remove any menus that may overlap into the fisheye circle.

flag_show_fps                  = false
flag_menu                      = false
flag_help                      = false
flag_infos                     = false
flag_show_topbar               = false
flag_show_time                 = true
flag_show_date                 = true
flag_show_appname              = false
flag_show_fov                  = false
flag_show_selected_object_info = true
flag_show_flip_buttons         = false
flag_show_script_bar           = false
flag_script_allow_ui           = false

Stellarium configuration 0.9 (Sample configuration file)

With the release of Stellarium 0.9, support for spherical mirror projection is greatly improved, although there are still some rather frustrating aspects to a number of their implementation choices. I will not repeat the settings above that version 0.8 and 0.9 have in common, the spherical mirror section that gives the right results for the standard spherical mirror projection arrangement is as follows:

projector_gamma                = 0.3
projector_position_x           = 0
projector_position_y           = 4
projector_position_z           = 0
mirror_position_x              = 0
mirror_position_y              = 5
mirror_position_z              = 0
mirror_radius                  = 0.37
dome_radius                    = 5.0
image_distance_div_height      = 2.67
projector_delta                = 10.6
projector_alpha                = 0
projector_phi                  = 0
flip_horz                      = false
flip_vert                      = false
distorter_max_fov              = 180
texture_triangle_base_length   = 8
flag_use_ext_framebuffer_object = true

In the video section, most modern graphics cards and drivers have no issue with non power of two textures. Somewhat smoother operation can be achieved by matching the maximum frame rate to the vertical refresh of the projector, this is usually 60Hz and this should also be set in the monitors control panel for the display. In any case, since locking to vertical refresh should be enabled to avoid tearing, there is no possibility of frame rates above the refresh setting of (typically 60 to 85 Hz for digital displays and pretty much exclusively 60Hz for digital projectors).

horizontal_offset              = 0
vertical_offset                = 0
minimum_fps                    = 10
maximum_fps                    = 60
distorter                      = fisheye_to_spheric_mirror
non_power_of_two_textures      = true


Stellarium configuration 11.1

The configuration file now seems to reside in "Library/Application Support/Stellarium" within the users home directory.

Unfortunately while the warping was never ideal, it is now broken on a couple of fronts. My understanding is that the last correctly operating version in this regard was 10.2.

Landscapes are handled a little different, they reside in "Library/Application Support/Stellarium/landscapes/" in the users home directory. At the bare minimum they require a spherical projection and a landscape.ini file. Note that other projections are supported besides spherical, but that is the most general and recommended by the author. An example is given in this zip file: This version of Stellarium allows one to add the landscape through the gui rather than adding manually. See "Sky and Viewing Options menu", and choose the "Landscape" tab.


Colour calibration

While not related to Stellarium, I cannot emphasise enough the importance of performing a computer/projector colour calibration when projecting fulldome. This is straightforward if you are using Mac OS-X, see the displays control panel. Creating and using a correct colour profile significantly improves the colour and contrast levels. In general data projectors have a very high (or low depending on which way you define it) gamma. Values of more than 3 are not uncommon, this corresponds to 1/3 in the Stellarium gamma correction setting.

Gain and black levels

Note also that by its very nature there is a lot of light inter-reflection inside a dome onto other surfaces of the dome. Ideally dome surfaces have gains that are as low as 0.5 and projectors with good black levels make a big difference to the final image contrast. For this reason one tries to use a projector with a contrast ratio of at least 2000:1, this normally is only available in DLP projectors ... at least in the commodity projector range.

Aspect ratio

In general, wide screen 16:9 projectors offer higher pixel efficiency when using a spherical mirror.

Sample screen shots (Click to enlarge)




Photos using an upright hemispherical dome.



Landscape images

Compiled/rendered by Paul Bourke
Available with different (lower) fields of view or higher resolution on request.


Location Preview landscape.ini
Cahill, Sydney, Australia
Photographer: Peter Murphy
name = Cahill
type = fisheye
maptex = landscapes/cahill_1024.png
texturefov = 360
Eliza, Sydney, Australia
Photographer: Peter Murphy
name = Eliza
type = fisheye
maptex = landscapes/eliza_1024.png
texturefov = 360
Coogee Cementary, Sydney, Australia
Photographer: Peter Murphy
name = Coogee
type = fisheye
maptex = landscapes/coogee_1024.png
texturefov = 360
Star Sphere
Mathematics: Dan Thomasson
name = Spheres
type = fisheye
maptex = landscapes/spheres_1024.png
texturefov = 360
Bayon, Cambodia
Photographer: Peter Murphy
name = Bayon
type = fisheye
maptex = landscapes/bayon_1024.png
texturefov = 360
Angkor Wat, Cambodia
Photographer: Peter Murphy
name = Angkor
type = fisheye
maptex = landscapes/angkor_1024.png
texturefov = 360
Bakheng, Cambodia
Photographer: Peter Murphy
name = Bakheng
type = fisheye
maptex = landscapes/bakheng_1024.png
texturefov = 360
Hampi, India
Courtesy: Sarah Kenderdine
name = Hampi
type = fisheye
maptex = landscapes/hampi_1024.png
texturefov = 360
Courtesy: Peter Morse
name = Antartica
author = Peter Morse
description = Antarctica
type = spherical
maptex = artic.png

Stellarium: Warping quality comparisons

The following comparisons are provided in an attempt to address some confusion over how the image quality of a fisheye frame is affected by the warping process applied for projection using a spherical mirror. The image on the left is the fisheye frame from Stellarium. The image on the right is an optimal warping of the identical view settings. The algorithm is not particularly special, the fisheye is rendered to a texture slightly larger (by between 30 to 50%) than the screen height. This resulting fisheye texture is then mapped onto a mesh with appropriate vertex and texture coordinates to accomplish the correct distortion. The slightly larger image rendering and the texture mapping has a negligible performance hit on modern graphics cards.

Warped fisheye
XGA (768x768)
XGA (1024x768)
SXGA+ (1050x1050)
SXGA+ (1400x1050)
HD (1080x1080)
HD (1920x1080)

Photograph of Stellarium image in the iDome (Photographic difficulties accepted)

Nightshade version 10.2.1. Mac OS: Lion [Website downlink says 11.12.1]

The configuration file for Nightshade is now located in the users home directory in a hidden folder called .nightshade. For those familiar with the UNIX command line it is ~/.nightshade/config.ini. A sample config file is given here: config1021.ini.

The settings relating to the spherical mirror are given below. These are similar to the "standard 16 x 9" warp file others use/distribute. The approach is generally to adjust the scaling until the horizontal span is right and then adjust the zenith to raise or lower the horizon.

projector_position_x           = 0.0
projector_position_y           = 3.5
projector_position_z           = 0.0
mirror_position_x              = 0.0
mirror_position_y              = 5.0
mirror_position_z              = 0.0
mirror_radius                  = 0.35
dome_radius                    = 5.0
zenith_y                       = 0.05
scaling_factor                 = 1.3
projector_gamma                = 0.3
flip_horz                      = true
flip_vert                      = false

name                           = perth
latitude                       = -28d48'0.0"
longitude                      = +115d55'55.20"
altitude                       = 0
landscape_name                 = forest
home_planet                    = Earth

The two outstanding variables are "zenith" and "scaling". zenith seems to try and compensate for lens offset and projector tilt. scaling seems to relate to the projector throw/zoom. The x axis is perpendicular to the page in the image above, I doubt very much whether anyone mounts the projector/mirror at other than perpendicular to dome. If they did I would doubt very much whether the correct warping would be performed. The basis for this believe is that it does not seem possible for the two variables zenith and scale to be able to cope with projector lens offset, rotation, and throw.

Remaining issues, comments ...

Stellarium version 11.2. Mac OS: Lion

The configuration file (config.ini) for Stellarium is located in the user directory, Library directory, Application Support directory, Stellarium directory. Somewhat inconvenient to new users since the Library directory is hidden by default. For those familiar with the UNIX command line it would be ~/Library/Application\ Support/Stellarium/.

Unfortunately the resulting warping is still not correct, seems to have been broken since version 10.2