EarthDesk in a Dome

Written by Paul Bourke
July 2009, updated in April 2016

The following allows one to display current/live Earth images interactively on a planetarium dome (or iDome) using either a fisheye projection system or a spherical mirror based system. It uses EarthDesk to generate the spherical projections, and Quartz Composer to manage the display. It is provided mainly as a demonstration for those who may not have used Quartz Composer, an excellent tool for interactive graphics.

Quartz Composer

Quartz Composer is supplied free of charge with the Apple XCode development systems (also free). You are encouraged to look through the Quartz Composer patch in order to understand what is occurring. When you are ready to run the composition you need to enter full screen mode.


"pbmesh" is a Quartz Composer patch that implements the image warping technique used by the author to warp fisheye images for spherical mirror based projection (although it has a much wider range of application). pbmesh is also free, it needs to be copied into
   /Library/Graphics/Quartz Composer Patches
This must be exactly as shown above, it is NOT the same as a similar appearing directory called "Quartz Composer Plugins".

EarthDesk: Save to file

EarthDesk needs to be configured to save the image to a file rather than place it on the desktop. The setting for this is in the general preferences pane. The Quartz Composer patch will read this file at a time interval of the users choice.

EarthDesk: Projection and zoom settings

EarthDesk needs to be instructed to create an equirectangular projection, it is this projection that the Quartz Composer patch will wrap onto a sphere. It would be nice if EarthDesk had an option for a perfect 360 degree horizontal range, since it doesn't the user needs to adjust the zoom so that at least 360 degrees are visible. Controls are provided in the Quartz Composer composition to trim the resulting image to 360 x 180 degrees before wrapping onto the sphere.

Quartz Composer Composition

The Quartz Composer composition is well commented. The following indicates some of the more important adjustments. The reader is encouraged to explore Quartz Composer, it is a very capable environment in which to create dynamic visual displays, including for planetariums. It should be noted here there is a slight "hack" involved, that is, a fisheye image isn't actually generated. It relies on the fact that to a first approximation a circular objects in fisheye space is also circular.

iDome example

Update (April 2016)

As with any document of this type it can get out of date with updates in software and operating systems. Version 7 of EarthDesk (this document update based upon the release in April 2016) does things a little different and that will be documented here.

The setting to instruct EarthDesk to save files is now in the Advanced tab, select the "Screen Saver Only" option in the pop-down menu.

The images are now saved in a different location, the users Library folder and in the Application Support, see details below.

The saving frequency can be adjusted in the Appearance tab. The scale determines the longitude range, 80% seems to give 0 to 360. If the texture doesn't form a perfect seam this scale needs adjusting. A new QC composition is provided here, it is only slightly different from the previous version. Note the values in the image crop will still need adjusting, the exact degree of image padding depends on the aspect ratio of the your display. Normally it seems only a vertical letter box is required to remove the black bands at the top and bottom of the saved image. If you have pinching at the north and south pole, or back rings at the poles then the values in this crop patch need adjusting.

Unfortunately my license for the earlier release is no longer valid so the examples in this update have the unlicensed watermark.

Note that while this is implemented for a spherical mirror, it could be easily modified for simpler fisheye lens systems.