LightGen Plugin

This plugin is an HDRShop-compatible executable by Jonathan Cohen, original concept by Paul Debevec, at the USC Institute for Creative Technologies for generating a set of directional light sources to approximate a lightprobe image. This is useful because it allows you to use image-based lighting with standard non-global illumination renderers.

The corresponding lightprobe image.
Rendered with 20 directional light sources.
The 20 lights in latitude/longitude format.

First, you must have HDRShop, which is free for non-commerical and academic use and is available here. To install the plugin, download it from the bottom of the page. Create a directory on your system called "plugins" which is in the same directory as the HDRShop executable, HDRShop.exe. Copy the file "lightgen_plugin.exe" into this directory. When you start HDRShop, the option "lightgen_plugin" should appear in the "Plugins" menu.

The plugin operates on a lightprobe image that is in latitude-longitude format, which is the format of the lightprobe shown above. To convert a lightprobe into this format, load the lightprobe into HDRShop. Then select "Image->Panorama->Panoramic Transformations" from the main menu. This will pop up the panoramic transformations dialog box. Select the lightprobe image as the "Source Image" and select which format it is in (for example, if it is a high-dynamic range image of a mirrored ball, select "Mirror Ball"). In the destination section, select "Latitude/Longitude" from the list box, and select a destination resolution of 128 x 64. Higher resolution is not needed, and it merely slows down the light generation algorithm. Finally, hit "Ok" to perform the conversion.

A new image in latitude/longitude format should now be displayed. You might want to center it and zoom in (press '5' on the number pad to center it, and '[CTRL]+' to zoom in.) Select "lightgen_plugin" from the "Plugin" menu. This will pop up the plugin dialog box. The plugin takes the following options:

Output filename

The output that the plugin generates. It specifies the directional lights in different formats.

Output file type

The format of the generated lights. Formats are Text, Arnold Render File, MEL, Radiance, or Houdini script.

Number of lightsources

The number of lightsources to approximate the lightprobe with. In some rare cases, the plugin will actually generate fewer lightsources than specified.

Max number of iterations

The plugin uses an iterative algorithm based on K-Means clustering. This is guaranteed to converge eventually, but to keep it from running away, you can limit to total number of iterations. 100 is usually plenty.

Number of searches

The iterative algorithm uses a gradient ascent technique to optimize the placement of lights. If might therefor get stuck in local optimima. To alleviate this, you can run the search multiple times and take the overall best results. A value of 5 gives good results.

Scale total light intensity

Check this if you'd like to set the total intensity of the lights the Lightgen generates.

Desired total light intensity

By default, Lightgen will generate lights that are very bright, since it adds up the total intensities of the pixels in the lightprobe image, and sets the lights to have that total intensity. Instead, you can tell Lightgen to rescale the intensities of the lights so they fall in a more reasonable range. The intensity is computed as luminance, or 0.3 * Red + 0.59 * Green + 0.11 * Blue.

Once the options are selected, hit "Execute" to run the plugin. There is a bug in HDRShop where if the plugin takes a while to execute, HDRShop will think it has died and will report a failure. However, even if HDRShop reports a failure, the plugin is running just fine so you can ignore this warning. The output can be fed to standard modeling programs as follows:


A simple text file. Each light is listed in order, followed by its color as R G B and its direction as a unit vector X Y Z.


The output file is a valid scene description file and can be included in any ARF file.


Copy the output text file from a text editor into the Script Editor window, and hit [Numpad Enter], or select "Source Script" from the file menu of the Script Editor. The lights will be added to the scene. Update 9-13-01. Normalizes light colors by dividing r,g,b by the maximum of the three, then sets the intensity of the light to be this max. This way the colors are all between 0 and 1. Update 11-1-01. Creates a Locator called "lightgen_control" with an attribute "dimmer." The intensities of the lights are keyed linearly to the dimmer attribute. So to halve the intensities of the lights in the scene, for example, set dimmer to 0.5.


Source the resulting file into HScript. It will add the lights to the scene description. It also generates a variable called "lightgen_dimmer" that can be used to dim all of the lights simultaneously. Update 9-13-01. Fixed a bug so lightgen should now work with both mantra and vmantra. Update 10-01-01. Generates blur shadows from the lights, where the blur value can be set from the variable lightgen_blur. Also lets you set the distance that it places the light sources from the origin via the variable lightgen_scale.


The output file is a valid Radiance scene description file.

LightWave 3D

Arnie Cachelin from NewTek wrote a converter from the text output format to LightWave3D. It is available here. He has asked that anyone with problems or comments post to the NewTek discussion forum. The script divides the colors by the max value, and then sets the light intensity to that max. It also creates a null object as the parent of the lights.
Final Note

if you don't set the "Scale total light output" option, the values of the lightsources may be very bright. This is because the total light output from the scene is equal to the sum of all the pixel values in the lightprobe image, which is usually pretty high. This is why, for example, the Houdini version creates a variable called lightgen_dimmer to make it easier to scale down the lightsource intensities. In Maya, you'd have to scale all the lights by hand.


The executable may be downloaded here. It is provided free for academic and non-commercial use although full copyright is maintained by the University of Southern California. If you want a new file format, be sure to send me a template for the file that the plugin should generate.

For feedback or requests, send us an email.



Thanks Tim Hawkins for helpful discussions and Craig Halperin, Marcos Fajardo, and Brian Emerson for help with testing. And thanks to Chris Tchou for writing the awesome HDRShop.

Footer With Address And Phones