Vuo as a playback solution for domes

Written by Paul Bourke
September 2019

Update: For current dome playback tools see: Tools for Spherical Mirror Projection


The following presents Vuo as a possible movie playback solution, or indeed other realtime graphical experiences, for domes. It illustrates the key features of Vuo through an example. While it focusses on single projector systems employing a spherical mirror, it can also be used for fisheye systems that might require warping due to an off-center fisheye lens, or multiple projector systems assuming the warp and blend data is available. The features of Vuo that make it an ideal choice for the task are as follows:

  • There is a warping node in Vuo, previously introduced here, that is extremely general and can support a wide range of image warping applications.

  • Vuo leverages the high performance hardware assisted graphics built into every current Mac hardware and OS.

  • It supports ShaderToy style GLSL shaders providing for custom high performance image transformations.

  • Vuo, while not free, is very reasonably priced for what it is capable of. In the discussion here it is a replacement for Quartz Composer that the author has used for similar purposes in the past. At the time of writing QC is essentially a dead product, not supported by Apple.

  • It is simply a fun environment for producing real-time graphics. The example here is based upon the current version at the time of writing, namely version 1.2.0.

Warped fisheye

Some of the key capabilities of Vuo will be presented next in the form of an example. This might be the basis of a very simple movie playback system for a dome with a spherical mirror. This example will assume there is a warp mesh available and customised for the dome projection configuration in question, and that the computer is configured with two displays, one being the primary display and the other a secondary display connected to the projector. A screen capture of the two displays might be as follows, the left hand being what the operator sees on their display, the right hand is the fullscreen image connected to the data projector. Note, the displays are not mirrored and while this is the configuration assumed here Vuo is flexible enough to handle other arrangements.


Primary display, eg: laptop screen

Secondary display, eg: projector

To follow along at home, the following zip file: warpfisheye.zip can be downloaded. A few fisheye movies need to be copied into the "movies" directory. Upon running the Vuo program with the Vuo project file provided the Vuo editor window should look something like the following.


The purpose of this document is not to be a tutorial on Vuo, there are lots of resources already on-line for that. In what follows the key parts of the Vuo project will be discussed, this in conjunction with other on-line material should be a fast start to learning Vuo and being able to modify the project here to meet your exact needs.

From the above screen shot it is clear that Vuo is a graphical programming paradigm where nodes, which have inputs and outputs, are connected together by cables. When reading the Vuo documentations or tutorials a key concept to pay attention to is the distinction between event and data signals on the cables. The main impediments to getting results at the start are firstly getting into the right mind set, this tends to be more difficult for those used to similar systems which while similar often work differently. Secondly there are a lot of built-in nodes so finding the right node or combination for the task requires some searching and experimenting.

Broadly speaking, the upper half of the project screen cature above is concerned with the secondary display, that is, producing the warped fisheye full screen. The lower half is concerned with the smaller window on the primary display, it consists of 4 buttons for playing, pausing and stepping to the next movie along with the name of the movie currently being played. The project is arranged such that inputs are managed by the nodes on the left (keyboard, movie name, and buttons) while outputs (windows and their contents) are managed by the nodes on the right. The different categories are further hilighted by colour, for example blue for inputs, yellow for outputs and grey for movie handling.


The display the windows appear on is indicated by the "Change Fullscreen Status" nodes, see red outlines above

The section of the project shown below is responsible for determining what movie files are available in the movies directory, managing the movie selection from the keyboard or button options, and finally delivering the movie name to the "Play Movie" node.

The key to the use of Vuo in this context is the warping node, this uses the exact same warp mesh files that are used elsewhere, such as the original WarpPlayer application and the VLC based movie player. Anyone planning on supporting spherical mirror playback are encouraged to support these warping files.

For correct operation it is important that all the red circles in the following are consistent, specifically have the same aspect ratio. That is, the aspect ratio of the projector in the fullscreen status node, the aspect ratio assumed in the warp mesh file, and the aspect ratio selected as the output of the warp node. Note that the size, 1920x1080 in this example, doesn't necessarily need to match the native resolution of the projector but it makes sense that it does.

An exercise for the reader might be to place a small preview of the fisheye (prewarped) on the controller window, only takes one extra node, or two if you want the frame. See example in the left image below.


360 movie player

With the advent of so called VR (head mounted) displays, there is an increasing number of 360 movies being recorded. In the context of a dome one can of course extract a fisheye projection with a virtual fisheye camera pointing in any direction. With the addition to the above Vuo project of a GLSL shader node, the shader code to extract a fisheye from a equirectangular formatted movie, and some navigation controls one can readily interactively tilt and pan in real-time within a 360 movie.

This first example of a 360 video of sheep shearing the Vuo project extracts a fisheye view suitable for a fisheye lens projection system. Note the equirectangular is shown on the primary screen control window. While all rotations (roll, tilt, pan) are possible, normally only panning is useful. The tilt is generally fixed depending on the tilt angle of the dome, or the angle in a horizontal dome corresponding to natural viewing largely dependent on the seat tilt angle.

One can obviously add a warping node to achieve the same thing for a spherical mirror projection system, the example below is a 360 video recording from steel mill in India.

Similarly the warp node, with a suitable mesh, can be used to present a fisheye correctly on a dome where the fisheye lens may not be in the center of the dome, for example there may be a optomechanical star projector in the center.