Converting an equirectangular image into another equirectangular image

Written by Paul Bourke
June 2017

The source code implementing the projections below is only available on request for a small fee. It includes a demo application and an invitation to convert an image of your choice to verify the code does what you seek. For more information please contact the author.

The following describes a utility to convert an equirectangular image into another equirectangular image. Why you might ask would one want to do that? There are at least 3 possible reasons.

  • When scaling images that wrap around horizontally (the 0 to 360 degree transition), such as cylindrical panoramas or equirectangular projections (spherical panoramas), one needs to be careful that the wrap-around seam is handled correctly. A standard scaling in image editing software that does not know about the wrap-around can result in hair-line defects on the left and right edge. While these may not be noticed when viewing the equirectangular image flat, they can be obvious when interactively navigating within the image or when the equirectangular is reprocessed to create other outputs (for example creating little planet images).

  • While equirectangular images have no natural "forward", there are occasions when presenting the equirectangular as a flat image that one wants subject matter in the image to be located in a particular location. In the terminology used below this is panning the camera, also known as changing the camera heading.

  • There are manual methods for both the above, but more difficult is leveling an equirectangular image captured with the camera not perfectly level. While in the past photographers capturing images that will be stitched/blended into an equirectangular would pay particular attention to leveling the tripod, today there are any number of one click hand held 360x180 degree cameras. This will be illustrated below in the case of the Ricoh 360 camera that conveniently stores the camera orientation as meta data in the image (exif data).

The usage string for the utility, called sphere2sphere, is given below. It employs a straightforward super-sampling antialiasing to avoid the usual effects that can arise from discrete sampling. It functions internally by considering each pixel (and subpixels) in the output image and finding the best estimate of the new pixel value in the input image. As such the performance is related to the size of the output image and supersampling level, it does not depend on the size of the input image except for the image reading time.

Usage string

Usage: sphere2sphere [options] sphericalimage
   -w n     output image width, default = input image width
   -h n     output image height, default = half image width
   -x n     tilt angle (degrees), default: 0
   -y n     roll angle (degrees), default: 0
   -z n     pan angle (degrees), default: 0
   -a n     antialiasing level, default = 2
   -f s     output file name

Critical in any such process is the order in which the rotation operations are performed, transforming in the order of roll-tilt-pan will not in general give the same results than if the rotations were performed in a different sequence. This will become clear later in the example using a Ricoh 360 camera. When specifying the rotation on the command line, because the image mapping is performed in reverse (output to input) the rotations are applied in reverse order. So for example

sphere2sphere -x 20 -z 30 -y 40 imagename.jpg

will perform the rotations in the order roll (-y), followed by a pan (-x), and lastly tilting (-x). The coordinate axis has z pointing up, y pointing forward and x to the right, a right handed coordinate system.


The following image is captured using a Ricoh 360 camera "randomly" orientated.

In general if the rotations involve more than a single axis, for example a tilt which would cause the horizon to be curved, finding the correction angles would be very difficult. In this case the exif data stored in the image by this particular camera can be used to immediately level it. There are many ways of possibly extracting this information, one method is to use a tool such as "exiftool", this gives the following.

>exiftool boathouse.jpg | grep Pose
Pose Heading Degrees            : 60
Pose Pitch Degrees              : -20
Pose Roll Degrees               : -5

Running sphere2sphere as follows

sphere2sphere -z 60 -x -20 -y -5 boathouse.jpg

gives the following. Note that at the time of writing the axes and meaning of positive and negative angles has been set to correspond to the conventions used by this camera, others may vary.


A simpler example of reorientating an existing level equirectangular by rotation about up vector. Noting of course that this only applies to the presentation as a normal image, or perhaps as the initial view direction for the normal interactive viewing of such images.

Rotating by -60 degrees aligns the equirectangular image to the wool packing machine (yellow) and places the doors symmetrically about the center.

sphere2sphere -z -60 shearing.jpg


The Samsung dual fisheye 360 camera also stores the pitch and roll angles as exif data in the jpeg image. Note they don't bother with the "heading" since in reality with these image there is no "front". The axes and rotation angles are different to the Ricoh but readily supported by this utility.

>exiftool samsung.JPG | grep "Angle"
Pitch Angle                     : 29.8
Roll Angle                      : -141.3