Tools for Spherical Mirror Projection

Written by Paul Bourke
First version: October 2019

Contents

Name Description Spherical mirror Fisheye
Fisheye movie player Plays a fisheye formatted movie Yes NA
360 movie player Plays an equirectangular formatted movie with controls to pan and tilt. Yes Yes
360 VR movie player Plays a VR (stereoscopic) top-bottom equirectangular movie with controls to pan and tilt. Yes Yes
Standard movie player Plays a standard (non-fisheye) movie. Provides controls to set the height and scale of the movie frame on the dome. Yes Yes
Warped text viewer Places user chosen text on the dome including control of text position. size, colour ... Yes Yes
Fisheye slide player Runs a slide show of fisheye images, warped. Slide show can be manually or automatically advanced. Yes NA
Standard slide player Runs a slide show of standard (non-fisheye) images, warped. Slide show can be manually or automatically advanced. Yes Yes
Fisheye movie pre-warp Converts a fisheye movie to a prewarped movie. EXPERIMENTAL Yes NA


Short history and older software by the author

In 2003 the author developed the idea of using a spherical mirror for fulldome projection instead of the much more expensive fisheye lens options. Initially fisheye movies were pre-warped but it was quickly realised that was not a sensible approach, rather the fisheye movie should be warped during playback. Fortunately this is something that is straightforward for the graphics cards of the time and now. In 2005 the warpplayer software was developed to do exactly that, for Apple Macs. Later in 2013, a modified version of VLC was created that supports real-time warping and was available for Mac and Windows.

Unfortunately the above two solutions are showing their age and the realities of the technology they were built on means they are difficult to maintain. On the Mac at least, the following is an attempt to bring things up to date and base the solution on a more stable and future-proof (as far as one can) footing.

Before purchasing

All the playback solutions below have demonstration versions, PLEASE download and test these before purchasing. If for some reason the demo version does not work for you please contact the author. Please be advised that some of the downloads are rather large, this is due to the inclusion of short fisheye movies for testing purposes.

Licensing

  • Purchasing one of the solutions below entitles you to the whole set and the meshmapper application.
  • The license is for a single computer, please respect this.
  • Please contact the author for a quotation if you require licenses for multiple machines or clients.


 
Fisheye Movie Player

Introduction

The following documents a new (2019) Apple Mac fisheye movie playback solution for planetariums using a spherical mirror projection system. It is intended to replace the older, and less featured, WarpPlayer application. It includes a simple control pane to select between different user installed fisheye movies, volume control, fisheye positioning, pause/play button and a preview on the operator console. And of course it allows one to supply a custom warp mesh for precise warping.

Display settings

The software expects two displays, the primary display identified by having the Apple menu bar along the top, and a secondary display attached to the data projector. These displays should not be mirrored, the settings accessed from the system preferences are shown below.

Note that in general the two displays will not be the same size. The secondary display will typically be either 1920x1080 or 1920x1200, the primary display will be whatever the laptop or iMac screen resolution is.

Player controls

When the player application is run, two windows will be created. One window will be on the secondary display, it will be full screen and it is where the warped movie will play (on the data projector). The other window will appear on the primary display, it will not be full screen, it contains the movie controls and will appear as follows although the movie name and preview rectangle will obviously reflect other movies than the two examples shown here.

The meaning of the items on this window should be obvious. The fisheye movie is previewed in the lower rectangle, the image on the secondary display is the warped version of this. The sound volume slider shown is a multiplier on the system sound levels, so when the slider is all the way to the right then the system sound level will be in effect. When the slider is all the way to the left then there will be no audio.

In this example, the image on the secondary display will appear as follows, namely the warped version of the fisheye movie.

This approach of using the secondary display facilitates seamless presentations. That is, one can launch the different tools independently without the audience seeing anything strange occuring between them, for example: menus bars, other windows, etc. The control pane on the operators screen would normally be invisible to the audience.

Warp Mesh

Any projection using a spherical mirror requires a description of how the fisheye is warped, such that after passing through the optical system (projector and mirror) the result on the dome looks correct. This is described by a mesh (vertices and texture coordinates) and stored in a so called warpmesh file. Ideally a warp mesh is created specifically for each installation since the warping required will depend on the exact geometry/optics. A tool for calibrating a particular installation is meshmapper and is provided with this application. Some installations find they can use a generic warpmesh and adjust the geometry/optics to match.

Correct warping depends not on the resolution of the projector but only on the aspect ratio, the ratio of the width to height in pixels. Two versions of this software are supplied for the two most common aspect ratios suited to spherical mirror projection, namely 16x9 and 16x10. 16x9 is suitable for projectors of resolution 1920x1080 and 1280x720, although the later is not recommended by the author. The most common 16x10 aspect ratio is for projectors with a resolution of 1920x1200 (UXGA+) and 2560x1600 (WQXGA). Other common data projection aspect ratios are 4x3 and 5x4, but these are not recommended for spherical mirror projection due to low pixel efficiency. Readers are asked to contact the author if they require a version of the software for a different aspect ratio, or for higher resolution projectors such as WQXGA, 4K, and UHD.

In order to use a site specific specific warping the warp mesh file should be named "warpmap.data" and placed in the package contents for the app. This is achieved by right mouse clicking (or control-click on laptop touch panels) on the application icon and choosing "Show Package Contents" from the pop-up menu, see below.

The result, after expanding the Contents and Resources folders will look like the following, simply replace the warpmap.data file with the one designed for your particular set-up by the company you purchased the system from, or as a result of running the meshmapper calibration.

Movies

This fisheye movie player allows one to play any one of a number of movies. The movies that appear upon clicking the "Previous movie" and "Next movie" button are the ones found in the movies directory, also located in the Contents and Resources folder. To create your own playlist simply copy the movies you wish to play into that directory, as an example two short fisheye movies are supplied, see below.

Navigation

  • On occasion it is useful to be able to rotate the fisheye on the dome, this can be accomplished by holding the shift key down and moving the mouse left and right.

  • If you decide you want to play a movie (or two) on the spur of the moment and you haven't already copied it into the movies directory, you can simply drag/drop the movie onto the control pane. That movie or movies will then appear at the end of the movie list.

Test before buying

To test before buying please download one of the following demonstration versions. These are full featured except the movie is converted to greyscale the words "Demo version" are added. Please report problems with the demonstration version to the author.

Fisheye Movie Player Demo for 16x9 aspect projector
Fisheye Movie Player Demo for 16x10 aspect projector


 
360 Movie Player

The following operates essentially the same as the above except in this case it accepts a 360 movie, as typically captured from one of the 360 movie cameras on the market. The format of the image is expected to an equirectangular projection, 360 degrees of longitude and 180 degrees of latitude. The image should have a 2:1 aspect ratio, for example

This movie player assumes a spherical mirror based projection system. If you have a fisheye lens projection system then the author is happy to produce a version for you, but additional information is required such as the pixel radius of the fisheye projection. Please contact the author for a version in this case, there is no additional cost for this customisation.

Instructions

The following assumes the reader is familiar with the documentation above for the fisheye case, only the differences will be presented. The expected display settings are the same as for the above. Namely two displays, the secondary connected to the data projector. The player controls are very similar, except now the preview shows the full equirectangular frame instead of a fisheye.

The 360 movie is previewed in the lower rectangle, the image on the secondary display is the warped version of an extracted fisheye view. See below for a description of how to interactively move this fisheye selection.

In this example, the image on the secondary display will appear as follows.

Movies are added to the play list by adding them to the "360video" directory, again located in the Package Contents for the application. Alternatively to temporarily add movies to the playlist they can be dragged onto the player controls window.

Navigation

There are an infinite number of fisheyes that can be extracted from an equirectangular. The best can depend on the content and the orientation of the dome and/or seating. The arrow keys can be used to shift the fisheye view, the left and right arrows change the longitude, the up and down arrows change the latitude. Auto repeat is also supported for continuous movement. Alternatively one can shift the fisheye by holding the shift key and moving the mouse while the player control window is active. Note that fast movement can be disorientating, smooth gradual movement is recommended.

Warning

360 movies can be much more compute/graphics demanding than fisheye movies. For one thing, for the same resolution they are twice the size. In addition to the warping required, which is the same as for the fisheye player, in this case the fisheye needs to be first extracted. As such, the computer power required for smooth playback may be more demanding.

Test before buying

360 Movie Player Demo for 16x9 aspect projector
360 Movie Player Demo for 16x10 aspect projector
360 Movie Player Demo for fisheye projector


 
360 VR movie Player

A version of the above 360 movie player is also provided for so called "VR" 360 movies. These movies are intended for stereoscopic viewing in VR headsets, the frame is split into two halves vertically. The equirectangular movie for one eye in the top half of the frame and the equirectangular movie for the other half is in the bottom half of the frame. This player otherwise operates identically to the 360 movie player described above.


 
Standard (non-fisheye) movie player

The following is in the same style as the two players above except this expects to play a standard (non-fisheye) movie on a section of the dome. Conceptually the movie is playing on a plane that is tangential to the hemispherical dome surface, it is tilted at some angle and a certain distance away.

This movie player assumes a spherical mirror based projection system. If you have a fisheye lens projection system then the author is happy to produce a version for you, but additional information is required such as the pixel radius of the fisheye projection. Please contact the author for a version in this case, there is no additional cost for this customisation.

Instructions

The following assumes the reader is familiar with the documentation above for the fisheye case, only the differences will be presented. The expected display settings are the same as for the above. Namely two displays, the secondary connected to the data projector. The player controls are very similar to the previous players except now there are two additional sliders. One controls the angle of the movie plane above the spring line of the dome, the other controls the size of the movie and therefore how much of the dome it covers.

Two different angle and scale values are shown below. The first is lower on the dome, the second is higher on the dome and slightly larger.

Movies are added to the play list by adding them to the "videos" directory, again located in the Package Contents for the application. Alternatively to temporarily add movies to the playlist they can be dragged onto the player controls window.

The background images can be found in the "backgrounds" directory in the package contents. The exact background can be chosen with the left and right arrow keys. Other backgrounds can be added, it is expected that they are square and fisheye projections.

A version of the above standard video movie player is also provided that does not do any warping. This is intended for direct fisheye projection rather than spherical mirror systems. This player otherwise operates identically to the standard video movie player described above.

Test before buying

StandardVideo Movie Player Demo for 16x9 aspect projector
StandardVideo Movie Player Demo for 16x10 aspect projector
StandardVideo Movie Player Demo for fisheye projector


 
Warped text viewer

The motivation of this utility is to put messages on the dome, warped correctly. These may be welcome messages, exit instructions, questionnaires, etc.

The background image selection (should be a fisheye), the warp mesh file, and the text message can be customised by editing/replacing the corresponding files in the package contents.

The current control pane looks as follows.

The output on the secondary display as follows.

A version of the above is also provided that does not do any spherical mirror warping. This is intended for direct fisheye projection, the secondary display might look something like this.

Test before buying

Warped text viewer demo for 16x9 aspect projector
Warped text viewer demo for 16x10 aspect projector
Warped text viewer for fisheye projector


 
Fisheye Slide Player

This software plays a slide show consisting of fisheye still images.

The slide images and the warp mesh file can be customised by editing/replacing the corresponding files in the package contents.

The current control pane looks as follows.

The output on the secondary display as follows.

Fisheye Slide Player demo for 16x9 aspect projector.
Fisheye Slide Player demo for 16x10 aspect projector.


 
Standard Slide Player

This software plays a slide show consisting of standard (non-fisheye) images, correctly warped for fisheye projection or spherical mirror projection.

The slide images and the warp mesh file can be customised by editing/replacing the corresponding files in the package contents.

The current control pane looks as follows.

The output on the secondary display as follows.

Secondary display example for a fisheye projection system.

Standard Slide Player demo for 16x9 aspect projector
Standard Slide Player demo for 16x10 aspect projector
Standard Slide Player demo for fisheye projection.


 
Fisheye movie pre-warp (EXPERIMENTAL)

The following tool allows one to create a prewarped version of a fisheye movie, suitable say, for playing from a low end device such as a media player. Note that in general the author does strongly recommends not creating prewarped versions of fisheye movies for other purposes, much better to warp live on the fly. One reason for discouraging this is that a pre-warped movie only really suits a specific geometric/optical setup and as such cannot result in a correct warp across different dome installations.

Unlike the previous pipeline by the author this tool does the movie conversion without the need to extract the movie frames, warp them individually and then reassemble the movie.

The operation of the tool is quite straightforward. A movie should be drag-dropped onto the conversion application window, shown below. The start button should be pressed at which stage the conversion process will start, the application will quit when complete. The converted movie will have the same name as the original movie except with the word "_warped" appended. This warped movie will be saved to the Desktop. The movie will be either H.264 (the default) or H.265 if that option is chosen, the movie will use the .mov container and extension.

The tool is supplied with sample warp mesh files for the two most common aspect ratios for spherical mirror projection. The instructions for using a custom warp mesh is described for the other players listed above.

Test before buying

Fisheye pre-warp video converter Demo for 16x9 aspect projector
Fisheye pre-warp video converter Demo for 16x10 aspect projector

Note on MOV

The tool above has been created primarily for Apple Macs, hence the choice of MOV as the movie container. It is accepted that this is not always the container of choice for Windows machines. It is quite easy to convert from MOV to mp4 (for example) in a lossless way by using the free ffmpeg software (there are lots of other ways as well but many/most will involve an undesirable recompression.

   ffmpeg -i moviename.mov -vcodec copy -acodec copy moviename.mp4


 
Buying

All the above software is available for the one price, that is, if you buy one then the others are also available. This includes meshmapper for creating customised warp mesh files. Please test the demonstration versions first, these are full featured except the movie is converted to greyscale and the words "Demo version" are added. Please report problems with the demonstration versions to the author. When you are ready, click on the PayPal purchase button below.

Customisation

The author is prepared to consider customised versions of the tools here, or new features. If you have feature requests feel free to send them by email. If multiple people ask for the same feature then it may be implemented in the future. Alternatively you may wish to commission a new feature or other customisation. The cost of any customisation will depend on the degree of difficulty and whether you require exclusive rights or if it can be shared with the community.

Update history

  • October 2019: First release of the fisheye movie player.
  • November 2019: Added drag and drop of movies to temporarily add to playlist.
  • November 2019: Created demo version for testing before buying.
  • November 2019: Fixed window size for retina displays.
  • December 2019: Released first version of the 360 movie player.
  • January 2020: Released first version of the standard (non-fisheye) movie player.
  • February 2020: Released pre-warping movie converter
  • March 2020: Released player for VR (stereoscopic) 360 movie
  • March 2020: Fixed a problem with the "standard movie player when used in countries that use commas instead of periods for the decimal separator.
  • March 2020: Added background image to "standard video" player.
  • March 2020: Added fast forward control and buttons, where appropriate.
  • April 2020: Updated all apps to version 1.1 with new features and interface consistency. Also added fisheye versions where appropriate.