Stellarium and NightShade resourcesWritten by Paul Bourke
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.
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 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:
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
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
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.
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 imagesCompiled/rendered by Paul Bourke
Available with different (lower) fields of view or higher resolution on request.
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.
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 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/.