No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

This package contains MATLAB functions that convert to and from different types of environment map representations. Most of the code was implemented following the book:

E. Reinhard, G. Ward, S. Pattanaik, and P. Debevec. High dynamic range imaging. Morgan Kaufman, 2005.

Please see the book for more details.


The main features of this package are:

  1. Support for many different environment map formats;
  2. Easy integration of additional formats;
  3. Automatic computation of solid angles;
  4. Intuitive integration with Matlab with overrides of common functions such as imresize, imshow, etc.


The supported formats are:

  • Sphere: spherical format, useful for mapping from a photo of a metallic sphere. Rays are very distorted close to the edge of the circle.

  • Angular: typical format for storing environment maps, because it minimizes distortions and is relatively compact;

  • LatLong: latitude-longitude (equirectangular).

  • Cube: 6-faced representation. Commonly used.

  • Octahedral: projection of a sphere onto an octahedron.

  • SkyAngular: convenient way to visualize the top hemisphere of the environment map only, with minimal distorsions. Warning: converting to this format will entirely drop the bottom half of the environment map!

  • SkyOctahedral: projection of the top hemisphere onto the top half of an octahedron. Warning: converting to this format will entirely drop the bottom half of the environment map!


The world coordinates (x,y,z) have the following reference frame:

     ^ y
     .----> x
z  v

The camera would be looking in the negative z direction.

The EnvironmentMap class

The EnvironmentMap class provides unified functionality and renders the use of the individual functions obsolete. It makes the creation and manipulation of environment maps very easy! Here's an example:

  1. Load an environment map from file (this assumes the file stores the environment map in the latitude-longitude format):

       envmap = EnvironmentMap('path/to/file', 'latlong');
  2. Resize the environment map:

       envmap = imresize(envmap, [500 NaN]);
  3. Display the environment map:

  4. Convert to the 'angular' representation:

       envmap = envmap.convertTo('angular');
  5. Rotate the environment map (now in angular representation) by 90 degrees around the x-axis (see SpinCalc.m in the 3rd_party directory for more on the nomenclature for representing rotations):

       envmap = envmap.rotate('EA213', [90 0 0]);
  6. Get the (x,y,z) directions corresponding to each pixel in the environment map:

       [x,y,z,valid] = envmap.worldCoordinates();

    The valid variable indicates which pixels in the environment map correspond to "valid" directions. For example, the pixels outside the circle in the "angular" representation are invalid, while there are no invalid pixels in the "latlong" representation.

The EnvironmentMapFormat class

The EnvironmentMapFormat class is used as an enum type to store all supported formats (see above). For convenience, it contains a format() function which allows conversion from strings. For example:

$ fmt = EnvironmentMapFormat.format('sphere');


This software package depends on the following (included) 3rd-party libraries (see the 3rd_party directory):


All functions assume that their inputs is in double format in the [0, 1] range. im2double should do the trick.


  • 10/30/12: Moved to github. Refer to commit messages for updates.

  • 04/19/11: Fixed small but in envmapWorld2SkyAngular.m which prevented correct conversion from skyAngular to latlong format.