Planetarium mode

Gaia Sky supports a couple of planetarium modes, depending on the projector setup.

Single-projector setup

Gaia Sky can output a true fisheye stream suitable for single-projector dome setups. If you need to separate the UI from the planetarium render window, you have two options:


Please use ‘Triangles’ or ‘Triangles (instanced)’ as the point cloud style to avoid the presence of seams. Using the legacy GL_POINTS mode will result in visible seams.

Just like the panorama mode, this planetarium mode runs by rendering the scene into a cube map (using separate renders for all directions +X, -X, +Y, -Y, +Z, -Z) and renders it using a fisheye projection. A few things need to be considered:

  • Cubemap side resolution – the resolution of each of the sides of the cubemap can be adjusted in the preferences window, planetarium mode tab.

  • Aperture angle – the default aperture is 180^\circ, corresponding to a half-sphere. However this angle can be adjusted to suit different dome types in the planetarium mode tab of the preferences window.

  • View skew – in focus mode, the view is skewed about 50^\circ downwards. This setting is not adjustable as of now.


To activate the planetarium mode, click on the dome-icon icon in the camera section of the control panel. Exit by clicking dome-icon again. You can also use the shortcut ctrl + p.


Planetarium mode

Multi-projector setup

Gaia Sky offers support for multi-projector setups, where a number of slave instances (each with its own viewport, field of view, warp and blend settings), are synchronized with a master (presenter) instance. Each slave is in charge of producing the image for a single projector and has a different view setup, geometry warp and blend mask. The current section only deals with the configuration of the view, warp and blend parameters for each slave.


The configuration and setup of the connection between master and slave instances is documented in the “Connecting Gaia Sky instances” section.

Additionally to the configuration needed to connect master and slaves, the slave instances need a special view, resolution, warp and blend configuration. These depend on the specifications, location and orientation of each projector, as well as the projection surface.

The following settings can be configured:

  • The yaw angle – turn the camera right

  • The pitch angle – turn the camera up

  • The roll angle – rotate the camera clock-wise

  • The field of view angle

  • The geometry warp file – a PFM file that contains the destination location for each source location in normalized coordinates

  • The blend mask – an 8-bit RGB or RGBA PNG file with the blending mask

The master-slave connection happens via the REST API server in Gaia Sky.

Gaia Sky offers two ways to configure these settings for each slave instance:

  • Using the MPCDI standard file format

  • Using the configuration file of Gaia Sky directly


Gaia Sky partially supports the MPCDI format in order to configure each instance. You will need a single .mpcdi file for each projector/gaia sky instance. Each file contains the resolution, the yaw, pitch and roll angles, the field of view angle and optionally a PFM warp file and a PNG blend mask. Gaia Sky does not support the MPCDI format fully, here are some caveats.

  • Only the ‘3d’ profile is supported

  • Only one buffer per display is supported

  • Only one region per buffer is supported, and this region must cover the full frame

  • Only linear interpolation is supported for the warp file

In order to set the .mpcdi file for an instance, set/edit the following property in the instance’s configuration file:[path_to_file]/instance_config.mpcdi

Gaia Sky configuration file

If you do not have the MPCDI files for your projector setup, you can also configure each instance directly using the Gaia Sky properties file for that instance.

Usually, each instance has a configuration file with the name config.slave[n].yaml, without the brackets, where n is the slave number. Open this file for each instance and set/edit the following properties.

# If you don't have an mpcdi file, use these next properties to
# configure the orientation. In order for this to work, you also
# need to set fullscreen=true, the right fullscreen resolution
# and the right field of view angle.

# Yaw angle (turn head right)[yaw angle in degrees]
# Pitch angle (turn head up)[pitch angle in degrees]
# Roll angle (rotate head cw)[roll angle in degrees]
# Warp pfm file[path to PFM warp file]
# Blend png file[path to 8-bit RGB or RGBA PNG file to use as blend mask]

Re-projection shaders

The planetarium mode can be simulated in a geometrically incorrect manner by using the post-processing re-projection shaders. These work on the final image after the perspective projection, and re-project it using different algorithms. Please, refer to the re-projection section for more details.

For some shaders, you may want to use a greater field of view angle than the maximum. You can do so by directly editing the configuration file. For example, we can set the field of view to 160^\circ like so:

      fov: 160.0

Finally, since the re-projection shaders stretch the image, it may be desirable to use a larger resolution for the back buffer. This operation is experimental and not recommended, but it works. Refer to the back-buffer scale section for more information.