VLC warp movie player

Page by Paul Bourke
October 2013

Fast-Start guide (Jan 2017)


The following is the next iteration in warping movie players, that is, movie players that take a movie along with a mesh file describing the warping and on the fly play the movie with that warping applied. The development of this is based upon the need for image warping in the planetarium industry when using a spherical mirror but it is equally required for many fisheye projection systems into planetariums, as well as a multitude of other non-planetarium applications. The original Apple Mac only solution can be found here, probably still the highest performing solution. Another solution based upon Quartz Composer, also Apple Mac only, can be found here.

The solution described here is based upon VLC, a popular open source movie player. Before buying this solution it is recommended that you download and install the unmodified VLC player to check that it runs and performs as expected on your hardware. Please note that in most cases one still needs a custom mesh file describing the warping.

User guide for VLC can be found here: https://wiki.videolan.org/Documentation:User_Guide/

It should be noted that QuickTime (.mov) files are not optimal in VLC (as compared to the Apple Mac QuickTime player). It is generally accepted the mpg movies will perform the best using the VLC player.

All warping functionality is implemented using OpenGL technology. As such, the correct OpenGL output module must be selected in order for video warping to take effect. The video output module can be changed using the "Output" option on the "Video" preferences tab. The following table lists the correct output module for each operating system:

Microsoft Windows OpenGL video output
Mac OS X Mac OS X OpenGL video output

MSWindows configuration screen shots

Configuring OpenGL output.

Setting the mesh file and forcing the aspect ratio to that of the intended display or projector.

Mac configuration screen shots

In order to have any selected options take effect, the user must click "Save" on the Preferences window, and reload any currently playing videos (by stopping and then re-playing them).

While there may be variations due to the exact version of the Mac OS, the following will allow non-mirrored mode. This can be useful for playing a movie on the projected display and still be able to use the primary monitor display ... for example, to load subsequent movies.

Known issues

  • If the end user already has the standard VLC player installed, the options selected under the modified VLC player will overwrite those already saved, and visa versa. To prevent this from occurring, the user may launch the application from the terminal, with the parameter --config=<configurationfilename> to specify which configuration file should be written to and read from. A short cut can also be created, to launch VLC with the same parameter.

  • There may be some VLC functionality that does not make sense with the warping version of VLC, for example the zoom features.
Note, February 2016

In addition to warping fisheye movies for spherical mirror projection into domes, the warping can be used more broadly. To create a warp mesh one only needs to understand how to calculate where points in the destination image originate in the source image. Still in the planetarium space, some suppliers of fisheye lens systems in order to maximise pixels on the dome don't inscribe the fisheye in the projected image height but rather use more of the image width up to the whole image width. This in turn means that only a portion of the dome is used but this is often acceptable for directional seating domes. Rather than modify the fisheye movie, a mesh can be created to form the correctly offset fisheye.


Example of fisheye circle in truncated 4:3 projector rectangle.

Note that this is different to so called offaxis fisheye projections which are required when the fisheye projector may not be in the center of the dome, but meshes can be created to correct for the image distortion encountered in that case.

Further VLC configuration screen shots for Mac