Tuesday, September 30, 2008

Warp Patch for Quartz Composer

Warp Patch for Quartz Composer

Intended primarily for fulldome projection using a spherical mirror
Also used as a navigable movie player
Modelled after the warpplayer application

Written by Christopher Wright @ Kineme
Design by Paul Bourke

The Quartz Composer patch discussed here warps an image (or movie) in an arbitrary way as specified by a user generated mesh stored in a simple text file. There are many potential applications for this but the motivation for this capability arose from a very precise requirement, namely the warping of images for projection into immersive spaces by using a projector and a spherical mirror.

This document assumes the reader is familiar with the topics listed above, namely the use of a spherical mirror as a low cost single projector solution for immersive displays. And that this technique requires image warping such that the result appears correct on the final surface. Additionally, the concept of navigable movies ... movies where each frame consists of more than a limited perspective projection and the viewer may change his/her view while the movie plays.

In all the above applications an image is warped (distorted) using a regular mesh consisting of vertex coordinates (x,y), texture coordinates (u,v) and an intensity mapping (i). The patch described here adds this warping support to Quartz Composer and is a direct analog to the existing stand alone application "warpplayer" (it uses the exact same warp mesh file format) except that it adds the enormous additional functionality of Quartz Composer to create more dynamic/interactive experiences. The rest of this document will concentrate on applications intended by the original designer of the patch, every attempt has been made to keep it general so that hopefully other uses will rise.

Description of inputs

  • Mesh file: file name of ascii warp mesh, if the file name starts with "/" then it is an absolute file path, if it starts with a "~" then it is relative to the users home directory, otherwise relative to the current Quartz Composition directory. For portability reasons the last option is usually the preferred one.

  • Texture control u, v: either clamp or wrap.

  • X,Y,Z position: provided for generality, not used for the purposes discussed here.

  • Width, Height: this controls the width and height of the panel the image/movie is displayed on. For the purposes discussed here one is always running in full screen mode, for the image/movie to fill the frame the width and height should be the inverse of the aspect ratio. So for 4:3 aspect the width and height should be 0.75, for 16:9 it should be 0.5625.

  • Delta u,v: These modify the mesh texture coordinates of the warping mesh. Not all adjustments make sense, the most common for panoramic images/movies is to map the mouse movement to the delta u input to enable horizontal panning.

  • Theta: This also modifies the texture coordinates of the warping mesh. For the applications discussed here it is mostly used for rotating a fisheye projection for planetarium content.

  • Image: This is the input port for the image (or movie).