Software: tgawarp

Full dome projection using a spherical mirror requires that the fisheye frames be distorted such that the result on the dome looks correct. This can be done in realtime using a locally developed QuickTime player but it can sometimes be useful to prewarp the frames of a fisheye movie. Reasons for doing this include playback from non-Apple hardware or playback from a lower end platform that may not be able to support the warp-on-the-fly technique. The description of how a frame is warped is defined by a so called warp mesh, described here. An example of such a mesh is given here: xyuv.data.

As an example, consider the polar gird on the left, the warped version for a particular projector/mirror/dome arrangement is shown on the right. The geometry specification is given at the top right of the image and corresponds to the warp file example given above.

tgawarp is a UNIX, command line style application available for Mac OS-X. The usage string is given below, the file naming convention for the fisheye frames is flexible enough to handle the naming conventions in common usage in the planetarium industry. This is design primarily to warp animation sequences rather than single frames.

Usage: tgawarp [options] tgafilemask mapfile
Options
   -w n    width of output image, height is determined by aspect ratio of mesh
   -a n    antialiasing level, default is 2 (minimum recommended)
   -n n    set the first frame number, default is 0
   -m n    set the frame step, default is 1
   -f      flip image vertically
   -i      ignore intensity mapping, default is to apply intensity
   -t      assume top truncated fidheye, default assumes full fisheye
   -o s    set output tga file mask, default is derived from input mask
Example 1: tgawarp -w 1024 frames%d.tga xyuv.map
           Expects frames called frame0.tga, frame1.tga .... etc in the current directory
           Will create output files called w_frame0.tga, w_frame1.tga .... etc in the
           current directory. The frames will be 1024 pixels wide, 2x2 antialiasing.
           The map file "xyuv.map" is expected in the current directory.
Example 2: tgawarp -w 1400 -a 3 -n 1 -o ../output/%05d.tga ../input/%05d.tga xyuv.map
           Expects files 00001.tga, 00002.tga ... etc in the directory "../input/".
           Will write the warped files 00000.tga, 00001.tga ... to "../output/".
           The frames will be 1400 pixels wide with 3x3 antialiasing.

• The width of the output image should match the native resolution of the intended display, normally a data projector. The aspect ratio and hence height of the image is determined automatically from the warp mesh file.

• Antialiasing is implemented as supersampling antialiasing and plays a major role in the performance and memory requirements. Typically 2 is sufficient.

• The program initially builds a lookup table, this can take quite a while but makes the subsequent image transformations relatively fast.

• The "-t" option is intended for frames where the fisheye image is truncated as per the common fisheye lens projection arrangement. Since the spherical mirror projection can generally cover more of the dome than the truncated fisheye, if one is working from such truncated frames the dome coverage of the warped result will be less than if full fisheye frames were used.

MacOS-X version:

The Sierra version works with Big Sur.
From Catalina onwards you will need to get past Apples additional security. The first time you want to run it right click on the application and "Open with terminal". After approving you want to run the application you can subsequently use it from the command line as intended.

Update: August 2017

tgawarp (contrary to what the name suggests) can now convert jpeg frames as well. This is in place for the "Sierra" version onwards.

Update: May 2007 - A version that operates on JPEG files

The command line string is identical to the TGA version except for an additional command line option (-q n) that sets the output file JPEG quality.

Usage: jpgwarp [options] jpegfilemask mapfile
Options
   -w n    width of output image, height is determined by aspect ratio of mesh
   -a n    antialiasing level, default is 2 (minimum recommended)
   -n n    set the first frame number, default is 0
   -m n    set the frame step, default is 1
   -f      flip image vertically
   -i      ignore intensity mapping, default is to apply intensity
   -t      assume top truncated fidheye, default assumes full fisheye
   -o s    set output image file mask, default is derived from input mask
   -q n    set the quality of the output jpeg file, 0 to 100
Example 1: jpgwarp -w 1024 frames%d.jpg xyuv.map
           Expects frames called frame0.jpg, frame1.jpg .... etc in the current directory
           Will create output files called w_frame0.jpg, w_frame1.jpg .... etc in the
           current directory. The frames will be 1024 pixels wide, 2x2 antialiasing.
           The map file "xyuv.map" is expected in the current directory.
Example 2: jpgwarp -w 1400 -a 3 -n 1 -o ../output/%05d.jpg ../input/%05d.jpg xyuv.map
           Expects files 00001.jpg, 00002.jpg ... etc in the directory "../input/".
           Will write the warped files 00000.jpg, 00001.jpg ... to "../output/".
           The frames will be 1400 pixels wide with 3x3 antialiasing.

Update: October 2007 - Saving lookup tables

The internal computation of a lookup table can take a significant mount of time, especially for large output image sizes and high antialising values. A new feature has been added whereby the lookup table will be saved to a file and can be used for subsequent runs. The requirement is that the same warp file is used, the same output dimensions, and the same antialiasing level. As such the lookup table has these parameters encoded into its file name, for example if the warp file is called "dell5100.data" then the lookup table will be save in the same location and called "dell5100_1920_1080_2.lup", where the output image width is 1920, the height 1080, and the antialiasing 2. The software will now automatically look for a matching lookup fable file, or the user can specify it on the command line, see the new "-l" command line option.