Stellarium and NightShade resources

Update: The information below relating to warping in Stellarium and Nightshade is no longer the authors recommended approach, the text will remain purely for historical purposes. The author now recommends screen copy and warp as described in the new spherical mirror dome tools outlined here and titled: "Warping a screen capture". This has multiple benefits: the operator can navigate in the fisheye view separate from the imagery displayed on the dome, and existing customised warp meshes can be used for this and other content projection.

When employing screen warping with Stellarium the following are some useful tips.

• Lock the fisheye field of view to 180 degrees in the config.ini file, navigation section.

  init_fov                               = 180
  min_fov                                = 180
  max_fov                                = 180
  

• Set the fisheye and mask in the config.ini file, projection section.

  type                                   = ProjectionFisheye
  viewport                               = disk
  viewportMask                           = true
  

• In the video section of the config.ini file, force the application to open on the primary display and at your preferred dimensions. Fixing the position of the window will ensure the capture rectangle can be configured accordingly and will remain correct.

  fullscreen                             = true
  screen_number                          = 1
  screen_h                               = 960
  screen_w                               = 960
  screen_x                               = 200
  screen_y                               = 30
  

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.

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 trade off 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.

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

[projection]
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:

• Your monitor can handle the resolution (likely, and almost certain for CRT)
  
• Your projector can accept and downscale the resolution to its native resolution (usually the case, within reason, for current projectors)
  
• You retain the aspect ratio of your projector, eg: 4:3

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

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

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

[gui]
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:

[spheric_mirror]
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

Notes:

• The flipping is rather redundant, one normally wants to see the image correct on the monitor and flipped digitally using the projector controls (image flipping is supported in all known data projectors).

• The throw is defined differently to convention, it is normally quoted and measured as the projector/image distance divided by the image width. In any case, the difference between the conventional definition and the one here is just a factor of the projector aspect ratio. So commodity projectors (depending on the zoom have a throw of between 1.6 and 2.4 (depending on the zoom), this corresponds to a "image_distance_div_height" of between 2.1 and 3.2 for a 4:3 aspect ratio. In the above 2.67 corresponds to a throw of 2.0.

• Data projectors (except for very wide angle lens) generally have an offset lens. The degree of offset, except in projectors with mechanical lens shift, is fixed. The usual way of specifying this is as a percentage of the half image height, 0% is the on axis case, 100% is where the image starts at the center of the lens. Generally projectors with standard lens have an offset of between 90 and 110%. DLP projectors (usually favoured for dome projection due to high contrast ratios) commonly have offsets slightly above 100%, additionally ideal for spherical mirror projector since it allows the light to pass over the top of a level projector.

  

  Stellarium defines this offset as an angle, so for example in the above example with a throw of 2.0, the image height if the projector is 1m away is (1/2)*(3/4) = 0.375. For a projector with a 100% offset, the angle should be atan(0.375/2) = 10.6 degrees.

• In the "standard" (recommended) arrangement of the mirror with respect to the dome, the radius of the dome is not relevant.

• The texture triangle length should be reduced to 4 or 8 for improved quality. While this should have little performance issues for modern hardware, it may well be an issue on some machine configurations.

• Unfortunately the developers have chosen to implement their own warp mesh approach and file format rather the more general one employed by my existing software tools (and implemented by other developers). This precludes the elegant idea of having one mesh file for all applications at a particular site. Fortunately the above geometric approach is perfectly satisfactory for standard dome configurations.

• When starting up in warped fisheye mode there is a bug if flag_use_ext_framebuffer_object is set to true.

• On PPC and Intel Macs, running Stellarium in warped fisheye mode results in a crash on quitting, the OS reports "The application Stellarium quit unexpectedly." error message. Not a serious issue since one was quitting anyway, just an annoying error message.

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: polargrid.zip. 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.

Miscellaneous

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.

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.

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

Photos using an upright hemispherical dome.

Landscape images

Examples

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

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.

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

Notes

• The thickening of the lines/text towards the top of the image should not be interpreted as a thickening of the corresponding image on the dome. All the lines appear the same thickness irrespective of where they are on the dome.

• Star fields are very hard to successfully project with a single projector, this is especially so with only an XGA projector, fisheye or spherical mirror. As might be imagined while an HD projector is of little use for full fisheye projection using a fisheye lens, it is ideal for the spherical mirror which can take advantage of the additional width.

• Better results can be achieved with a fisheye lens configured in a truncated arrangement which is a closer match to the spherical mirror in terms of dome coverage.

• If the images are zoomed in there is an obvious difference between the sharp pixel edges in the fisheye and the slightly blurred lines in the warped image. In reality this is not necessarily a bad thing given that the lines are not inherently thicker, in computer graphics speak it is known as antialiasing and usually considered desirable. Indeed in my opinion the quality of both images would be improved if Stellarium performed antialiasing itself.

• It goes without saying that in order to get an exact image with a spherical mirror (the same as image on the dame as with a fisheye) a precise warping mesh is required. That is, one created specifically for the particular hardware being used.

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.

[spheric_mirror]
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

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

• The texture resolution for the warping is far too low, it introduces obvious creases in the image. I estimate at least twice the resolution is required, ideally it would be a config file variable.

• What happened to the ability to flip the image horizontally. Currently the image is reversed on the display, how strange! Ideally the default would be the opposite, correct on the display and use the projectors horizontal flipping to get the right effect in the dome. 99% of projectors have horizontal flipping in order to be used with rear projection screens.

• Turning on antialiasing (current MacBook Pro) didn't have any effect. A shame given the importance of antialiasing for good quality/appearing lines and text.

• Recommending users install the Mac version using MacPorts and use the command line to launch it is rather unfriendly and unnecessary. Convenient if you live in that world, rather antiquated otherwise. Cannot think of any other non-developer orientated product that does that.

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