"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 this, 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, uppercase 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
-f full screen
-d verbose/debug mode
-i s read image
-r s read existing geometry file
Right mouse button for popup menus
Keyboard
h camera home
p,d,m choose projector, mirror, or dome
X,Z,x,z modify position (projector or mirror)
R,r modify radius (mirror or dome)
A,a modify tilt angle (projector or 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 popup 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 popup 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 popup 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
Installation instructions
It is assumed that the user is familar with the Apple operating system and has at least some familiarity wth running UNIX style applications from the command line.
Rename one of the config files supplied above as "last.cfg". Place it in the same directory as the "meshmapper" application.
For a hemispherical display you can choose/create your own calibration fisheye image, or use the following (radialgrid.tga). This image should also be placed in the same directory as the "meshmapper" application.
Ensure X11 is installed and running. See optional installs on the installation CD/DVD from Apple.
"cd" to the directory containing the "meshmapper" application.
Run "meshmapper" from the command line, for example type
./meshmapper
Use either the xterm or the terminal program supplied by Apple and
located in the Applications/Utilities directory. If using the later then the
DISPLAY variable will need to be set, for example if you are using tcsh
setenv DISPLAY localhost:0
Choose the preferences menu item, this sets the Apple GLUT preferences. Note the mouse emulation is only required if you don't have a 3 button mouse. Quit from "meshmapper" by choosing "quit" from the menu bar, this will ensure the preferences are saved.
 |
 |
Run the "meshmapper" from the command line in full screen mode and using the
radialmesh alignment image. For example, type
meshmapper -f -i radialgrid.tga
Proceed as above to adjust the parameters until the image is aligned as desired.
Using the menus, save the xyuv mesh data, it is this file that can be used with the warping movie player and other software following that convention. For example for "warpplayer" you may choose to rename this map file "default.data" and place it in the same directory as the warpplayer application.
Notes
If you have an intrenal and external display they must be mirrored. Note that "interesting" things happen if the builtin display on the Mac is not the same as the resolution and/or aspect of the projector. The bottom line is that for optimal quality the builtin display should be the same or higher resolution than the projector native resolution. In this case Mac OS-X will honour the lowest resolution which will be the projector.
The center of the dome is the origin of the coordinate system. All components (dome, mirror, and projector) are assumed to be centered on the x,z plane (y=0). Z axis points up and the projector lies along the x axis.
All units are metric (meters) and angles in degrees.
The program needs to be run in full screen mode.
Recommended mesh resolution is 60 or greater, this is the vertical resolution and the horizontal resolution will be set depending on the aspect ratio of the projector to give mesh cells that are approximately square.
Since the configuration settings are read and saved each time the program is run, the configuration doesn't need to be done in one session. Indeed it is useful to be able to tweek the configuration each time the parameters change slightly eg: after maintenance and cleaning at which point the projector/mirror may be slightly disturbed.
This program can be used to create single pre-warped still images. Load the image "meshmapper -i yourfisheyeimage.tga", a window dump is created by hitting the "w" key. The window dump will be called "0000.tga" the first time, "0001.tga" the second time and so on.
The various shading/fading options are intended to cope with fading the image to black at the back of a planetarium dome, for example. This is important to both remove the extreme distortion that can occur behind the mirror and also to reduce the interreflections arising from very bright images just behind and above the mirror.