Tools for Spherical Mirror Projection using Parametric GLSL shader

Short history and older software by the author

In 2003 the author developed the idea of using a spherical mirror for fulldome projection instead of the much more expensive fisheye lens options. Initially fisheye movies were pre-warped but it was quickly realised that was not a sensible approach, rather the fisheye movie should be warped during playback. Fortunately this is something that is straightforward for the graphics cards of the time and now. In 2005 the warpplayer software was developed to do exactly that, for Apple Macs. Later in 2013, a modified version of VLC was created that supports real-time warping and was available for Mac and Windows. In 2019 the existing movie playback solution was abandoned and a new suite of tools developed, these includes support for 360 images or movies, as well as rectilinear, non-fisheye, content.

On thing all the software above had in common was that they employed a mesh with texture coordinates to achieve the warping of the fisheye required such that content looked correct on the dome despite the non-linear effects the spherical mirror introduced. Despite the recent tool development in 2019, the calibration software meshmapper was even older, and while functional was unfriendly and increasingly hard to support on current versions of MaxOS. Additionally, the use of a finite resolution mesh, which relied on texture interpolation on the graphics card was not ideal as 4K projectors started to become more prevalent.

Which brings us to the new solution developed here. Specifically, instead of using a mesh to achieve the image warping required, a parameterised model is used and implemented as a GLSL shader. The proof that this was a viable approach arose from the same technique being developed for offaxis fisheye projection. Such a shader approach can be efficiently implemented on modern graphics cards including the various recent offerings from Apple, and they perform the warping on a pixel by pixel basis rather than requiring mesh interpolation.

The approach here creates a simulation of the projection system, that is, the parameters that describe the projector, spherical mirror and the dome. Finding the correct parameters is conducted while projecting a test pattern into the dome, the test pattern is usually chosen such that one knows what it should look like, typically a polar grid of rings and radials. The parameters are adjusted until the result on the dome appears correct. One might ask why one doesn't simply measure all the parameters? One can for some of them, such as the size of the dome, the distances and dimensions of the spherical mirror and so on. But there are other parameters that are difficult to measure, for example, the degree of lens shift, the exact throw of the projector lens, the tilt of the projector. The control panel for the calibration tool is as shown.

The coordinate system employed and the meaning of the parameters is shown below. Not shown is the projector throw which depends on the zoom, it is defined as the distance of the projector divided by the width of the image when projecting onto a flat wall. It should also be noted that the measure for the projector position refers to the position of the entry pupil of the lens, this is not generally known exaactly.

The parameter labelled "Projector x direction" refers to the direction the projector is pointing, along the positive x axis for a planetarium style projection and towards the negative x axis for an iDome style projection.

There are some assumptions / constraints, they are:

• The projector is lying in the x-z plane, projector y coordinate = 0.
  
• The projector is only rotated about the y axis (pitch), no roll or pan.
  
• The dome is symmetric about the x-z plane.
  
• The mirror is aligned with the x-z plane, y=0.
  

Calibration instructions

The following are instructions for performing a calibration.

• Run the "Parametric spherical mirror calibration". This needs to be performed with the projector connected as a secondary display, not mirrored. This is the main difference to the earlier meshmapper software. The secondary display should be configured to the native resolution of the projector, typically one of 1920x1080, 1920x1200, 3840x2160, 4096x2160.

• Choose the preset closest to the physical and optical arrangement being calibrated. There are two generals sets that are very different, planetarium style and iDome style. The "p" key will step through various starting parameter sets for common configurations.

• Adjust the parameters through the interface provided until the test pattern matches expectations on the dome. The keyboard commands adjust the parameters coarsely, pressing the tab key toggles to/from a finer adjustment. The up and down arrow keys step through different test patterns.

• Once the desired parameter is found press the "s" key to save the parameters to a file called "parameters.data", this will appear on the desktop. If this is to be the starting point for future calibrations then the "parameters.data" files should be copied into the Applications Resources. Do this by right clicking on the "parametric spherical mirror calibration" application and choosing "Show Package Contents", the "Parameters.data" file in the resources directory should be replaced by the save one.

  

• The process of copying the "parameters.data" into the resource folder of the application package contents will be the same for application that are design to play back content on the dome, for example, a movie player.

Downloads

The calibration software
Demo version of the parametric warping movie player

Generating a mesh

To support legacy systems, the following command line utility will generate a warping mesh from the parameter file. The minimal input is a saved parameter file from the calibration software introduced above.

Usage: generatemesh [options] parameterfile
Options:
  -w n    Horizontal mesh vertices, default: 150
  -h n    Vertical mesh vertices, default: 100
  -a n    Aspect ratio of the project being used, default: 1.77778
  -d      Enable verbose mode for debugging, default: off

The outputs from the mesh generator are as follows:

• parameters_warpmesh.data - This is the legagy warp mesh.

• parameters_mesh.obj and parameters_mesh.mtl - Mesh with vertices and uv coordinates to perform a warping in realtime OpenGL style applications.

• parameters_mask.tga - A mask for the active warping portion.

Parameter file

The order of the parameter file is as follows:

• projector position, x and z axes

• projector tilt angle about the y axis

• projector direction, -1 if it points towards the origin (iDome), 1 if it points away (planetarium)

• projector vertical lens shift

• projector throw

• dome radius

• dome tilt angle about the y axis

• the type of back fading, only applicable to planetarium style arrangement

• dome flip status

• mirror position in the x and z axes

• mirror radius

• cut in the xy plane

• cut in the yz plane