Calibration tool for dome projection using a spherical mirror and single projector.Available for Mac OS-X
Written by Paul Bourke
Subsequent notes for a 8m dome (Updated 2012)
"meshmapper" is a utility that allows one to create precise warping maps for projection systems using a single projector and a spherical mirror, a technique called variously "sphemir" and "mirrordome". These may be upright domes such as these, planetariums such as these, and even more exotic spherical environments such as these. The following is a brief outline of the procedure one might use, please note that because the software described here is "utility" style UNIX application, one is expected to have some technical skills ... it is also still evolving.
In essence the software is a simulator that takes as inputs the geometric and optical characteristics of the projection system. Some of these parameters can be measured reasonably accurately, others are more difficult. The idea is that one inputs an image for which the result on the projection surface is known, the parameters are then adjusted until the correct (known) visual result is obtained on the projection surface. For example, in a dome one knows the correct appearance of a polar grid (lines of longitude and latitude) such as the following image: radialgrid.tga.zip.
If the correct parameters are applied to the simulator then the image will appear correct on the dome, "meshmapper" allows the operator to interactively modify the parameters until the correct visual effect is obtained, for example, for an upright dome this would be the test pattern appearing on the dome as follows.
The parameters required fall into three groups as follows:
While some parameters such as the positions of the components can be measured reasonably accurately, others can be determined less well. In particular, estimating the projector throw (varies with zoom setting), the projector tilting and offset angle. These can be varied using keyboard controls in order to achieve a precise match. For example, the image and settings (top left corner panel) for the above calibration is shown below.
The parameters are changed by first selecting which object will be modified (projector, mirror, or dome) by using the keys "p", "m", or "d". The object being modified is indicated in the panel on the top left of the display. Parameter values are then changed by using the lower and upper case of various letters, lower case decreases the value, upper-case increases the value. So for example once the mirror object is chosen, then hitting the "r" key will reduce the radius of the mirror, while "R" will increase the radius of the mirror. Positions of the mirror and projector (dome is fixed at the origin) can only be adjusted in the x-z plane using the keys "x", "X", "z", and "Z". For more details see the usage string below, "meshmapper" is a command line utility, the following string is displayed with "meshmapper -h".
Usage: meshmapper [options] tgaimage Options -h this text -p use a polar mesh rather than cartesian -f full screen -d verbose/debug mode -r s read existing geometry file Left mouse button for popup menus Keyboard h camera home p choose to modify projector m choose to modify mirror d choose to modify dome 0,1,2,3,4 choose to modify mesh node n modify nothing x,X modify position (projector, mirror, mesh) z,Z modify position (projector, mirror, mesh) y,Y modify position (mesh) r,R modify radius (mirror or dome) a,A modify tilt angle (projector or dome) b,B modify bearing (dome) t,T modify throw (projector) o,O modify offset (projector) f modify dome top (dome) w windowdump esc,q quit
Various additional options are available through the pop-up menus (right mouse button). Of particular note is the mesh resolution and the image geometry. The keyboard keys shown in the usage above are also available on screen, see the "Toggle interface help" in the pop-up menu.
The current settings are saved in a file called "last.cfg" that will be saved in the same location as the application. A sample configuration file is given for an upright dome (upright.cfg) and a planetarium configuration (planetarium.cfg). These can be used as starting points for the two different orientations (rename them "last.cfg"). These are just text files and can be edited as such before running "meshmapper", indeed this is usually the way one would start with a new calibration. At the time of writing the aspect ratio (typically 4/3 or 16/9) can only be set by editing this file.
Once the calibration is complete a warping mesh file can be written using the "Save XYUV warp mesh", see the pop-up menus. The file saved is called "test_xyuv.data", this is the file that is used to warp fisheye frames (in this example) and is described here and used for example in this warp-on-the-fly movie player.Coordinate conventions
It is assumed that the user is familiar with the Apple operating system and has at least some familiarity with running UNIX style applications from the command line.
How do I go about writing my own warping software?Answer
It turns out the mathematics is quite intractable ... by that I mean hard to solve because of the variables required to define a data projector. So all my alignment work has involved a simulation of the physical parameters. So, you need the geometry and optics of projector, the spherical mirror and the dome. You can see the parameters that go into my simulation in the top left of the second image above. What one does is imagine a ray through a grid sampling of the projectors rectangular frustum. This ray, in 3D space hits the spherical mirror (or not), is reflected through standard equal angle of incidence and reflection about a normal of the intersection point on the sphere, it then hits the dome (or not). Given the point on the dome you can work out what the 3D fisheye ray coordinate (phi,theta) and in turn the position (r,theta) on the 2D fisheye image. At this point you have a mapping between the fisheye (u,v) coordinate and the position in the image being projected. So if you create a mesh where the vertices are the original grid sampling, the texture coordinate is the calculated (u,v) coordinate. Complicated, but once you get the hang of it the concept is easy, the rest is in the details.