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:
- Support for many different environment map formats;
- Easy integration of additional formats;
- Automatic computation of solid angles;
- Intuitive integration with Matlab with overrides of common functions such as
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
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:
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');
Resize the environment map:
envmap = imresize(envmap, [500 NaN]);
Display the environment map:
Convert to the 'angular' representation:
envmap = envmap.convertTo('angular'); imshow(envmap);
Rotate the environment map (now in angular representation) by 90 degrees around the x-axis (see
3rd_partydirectory for more on the nomenclature for representing rotations):
envmap = envmap.rotate('EA213', [90 0 0]); imshow(envmap);
Get the (x,y,z) directions corresponding to each pixel in the environment map:
[x,y,z,valid] = envmap.worldCoordinates();
validvariable 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
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
SpinCalcfor rotation representations, by John Fuller (http://www.mathworks.com/matlabcentral/fileexchange/20696-function-to-convert-between-dcm-euler-angles-quaternions-and-euler-vectors)
All functions assume that their inputs is in double format in the [0, 1]
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.