LightTools.py

From Film and Animation Resources Wiki
Jump to: navigation, search
Blackbody Application Window
Rendering Application Window
IOR Application Window
IOR Chart Window
Notepad Application Window

Contents

Downloads

About

A aggregate of smaller applications meant to be useful when setting up lighting or shading parameters for CG scenes. Includes a Kelvin to RGB converter with the ability to send colors directly to lights in Maya and Softimage, Fresnel and Schlick Index of Refraction calculations and graphs, a simple shader development interface, and a notepad. See the individual sections below for descriptions of each app.

Installation

  • Python 2.7 or greater is necessary (Tkinter and ttk installed).
  • download the .zip file and unpack in the desired location
  • Set environment variable 'LIGHTTOOLS' to the location of the install and create any aliases.
    • on *nix style systems:
export LIGHTTOOLS=/Path/to/install/directory/bhm_lightTools/
alias lightTools=$LIGHTTOOLS'/__main__.py'
  • Modify the file '.../bhm_lightTools/modules/preferences.py' with the appropriate paths and information for your system.
    • This is required before the application will boot properly. If not all paths exist on your system (for instance, the shader development paths, src,rel,includes...), then create placeholder directories for these somewhere on your system (even in this app directory), and point the paths to those locations. The logic will be added at some point in the future to avoid this, but for now, this should allow the app to start up...
  • If you set the alias above, you can simply type 'lightTools' into your terminal window to launch the app, otherwise: in a terminal window, 'cd' to the directory where the app was unpacked. Running the command 'python bhm_lightTools' (add the version name if you haven't removed it from the directory), will launch the __main__.py file included in the directory.
    • Starting up the app may be different depending on the system you are on. Check to see how your system launches Python scripts or contact me if you continue to have issues.
    • It is best to start the app with a command-line, as much of the data (stats, errors, etc..) is returned through the command-line, and information will be missed if you can't view it.

Blackbody

About

Calculates the RGB color values for a given light temperature in degrees kelvin.

  • The values are returned in linear gamma space, so no extra conversions are required for linear pipelines (they can optionally be returned in sRGB as well).
  • A color chip is also provided where the resulting color can be viewed and 'tweaked' manually.
  • Ability to send the resulting color values to the selected light(s) in either XSI/Softimage, or Maya
  • Returned values are echoed in the command line as well as the GUI, in a format easily copied to a RIB/Shader file or other non-supported cg software.

Usage

  • Choose a white balance (D65 values of 6504k are used as defaults)
  • Choose a desired light temperature in degrees Kelvin, or enter one of the various presets. These are listed below...
  • Click "Run" to calculate the values.
    • Manually entered values should be in the range of 1600k-25000k, as the algorithms don't support values outside of this range.
    • A white-point of D65 will return the most accurate results. These results are nearly identical to the 'blackbody' light shader provided in mental-ray.
    • The intensity value can be adjusted to lessen the intensity of the returned color (a value of 1 will essentially return the 'pure' color).
    • For example a perceptual 'middle gray' can be achieved by setting both 'white balance' and 'light temp'to D65 (the default), and 'intensity' to 0.18 (18% gray). Set the returned values to 'sRGB' (the default is linear). When calculated, the color-chip should show roughly a middle gray, with values close to 0.5 for all channels (actual values are a little less).
  • The color values may be sent to either Maya or XSI/Softimage by clicking the corresponding button in the 'Send To' area of the interface.
    • In order for this to work, both XSI and Maya will need to be configured. This process is described below.

Send To

XSI/Softimage and Maya can be easily configured to interact with the LightTools application by following the steps below. When the 'Send To Maya' or 'XSI' buttons are pressed, the current resulting color from the LightTools app will be sent to the corresponding 3d application and applied to the selected light(s).

XSI/Softimage
  • install the supplied xsiaddon (located in .../bhm_lightTools/xsi). This addon serves two main purposes:
    • Starts a 'server' by opening up a communication socket, and listening on the given port
      • This is started (and re-started) on startup of XSI. You will need to close and restart XSI after installing the addon.
      • If the connection seems to get corrupted at some point, save, close, and restart XSI to restart the server.
    • Registers a few python functions so that they may be called natively.
Maya
  • Copy the supplied 'bhm_mayaCommands.py' (located in .../bhm_lightTools/maya) file into a directory on your system that can be found by Maya
    • Mine is in: '/My Documents/Maya/scripts'
  • In Maya, open the script editor and type the following lines (in Python, not MEL):

from maya import cmds
import bhm_mayaCommands as bhm

  • Drag these two lines to a custom shelf, and edit the newly created button accordingly.
  • This script will have to be executed to start the communication socket and to register the appropriate Python commands with Maya.
Screenshots
Setting light color in Maya
Setting light color in Softimage

Presets

White Balance Presets

  • D65
  • indoor
  • outdoor

Light Temperature Presets

  • D65
  • candle
  • daylight (sun & sky)
  • light bulb
  • match
  • moonlight
  • outdoor shade
  • quartz
  • sky: overcast
  • sky: partly cloudy
  • sun: clouds,haze
  • sun: noon
  • sunrise
  • sunset
  • tungsten 2kw
  • tungsten 500w
  • tungsten 5-10kw

Render

About

An application to assist with shader development. Supports rendering and compiling with PRman, 3Delight, and Aqsis

  • Compiling, rib manipulation, and rendering all in one window
  • Helps avoid having to jump between 3 or 4 terminal sessions for writing/compiling/rendering shaders.
  • This is not meant to replace the traditional text-editor/command-line approach, but rather to work along side of it. If you currently use another GUI to develop your shaders (Slim, etc..), or if you prefer to work directly in a 3d app such as Maya or Softimage, then this app won't do you much good.

Screenshots

Auto shadowmap generation
Ambient Occlusion
Various default shader geometry
Custom shader geometry
Custom shader geometry

Usage

For anything besides basic functionality, make sure your paths are set up correctly, and point to meaningful locations. To edit the default paths, edit the '.../bhm_lightTools/modules/preferences.py' file.

  • 'Source' points towards to main source directory for your shader development.
    • The 'Types' pull-down menu is populated from the directories within your 'source' folder, so it should work with the names of your directories, even if they are different from my own.
    • A sample directory may look like this:
.../<shaderDev>/...
                /src/...
                     /surface/
                     /light/
                     /displacement/
                     /volume/
                     /...
                /rel/...
  • 'release' points to the directory to move the compiled shader to.
  • 'includes' should point to your location of any header or 'include' files for compiling your source files. ** This is currently ignored, but will be added in the future.

Compiling

  • Choose the type of shader from the dropdown menu
  • Enter the name of the shader in the entry box labeled "Shader:" (no extension ".sl" is necessary).
  • Press the "Compile" button in the main toolbar, and check for any errors (they will be printed to the command line window).
  • If errors occurred, fix, and re-compile.
  • Shaders are automatically moved to the release directory.
    • Note that the shader you compiled is not necessarily attached to the RIB file that is rendered for preview. You need to put the shader name into the rib-box below to actually attach it to the geometry. More on this below...

Rendering

Note that renders are in linear gamma space by default. This means that without some sort of gamma correction or LUT applied to the framebuffer, the image will apear dark. Before any adjustments are made to the lights or rib files, try adjusting your framebuffer's preferences. You can also edit the gamma directly in the file: '.../renderman/shaderBall.rib'. The line "Exposure 1.0 1.0," could be adjusted to "Exposure 1.0 2.4" for a sRGB-like view for example. An lin->sRGB LUT is provided in the main 'renderman' directory. It has been used/tested with 3Delight's i-display, however it has not been tested with any other framebuffers (PRman's 'IT' provides its' own sRGB lookup capabilities).

  • Choose your renderer
    • This can be selected and changed on the fly to easily test your shader with different renderers to ensure compatibility/consistency.
    • Three are listed by default (PRMan,3Delight,Aqsis), however you need to already have these installed and operational on your system for this to work.
  • Enter the RIB file to be rendered.
    • You may enter any rib file/directory you want; however, be aware that choosing a file other than the default 'shaderBall.rib' will more than likely break the functionality of the rib-boxes, and light checkboxes. If you wish to render something else, try supplying your own custom rib archive (described later), or if this isn't enough, you can even edit the three main rib files (shaderBall.rib, geometry.rib, and lights.rib). As long as you are cautious, these files can be manipulated and edited while retaining full functionality and compatibility with the GUI interface.
  • Select the geometry to render (teapot, sphere, torus, 'shaderball', are provided by default. More can be downloaded or created manually).
  • Edit the rib-boxes with the shader and any other attributes such as shader parameters.
  • Select the lights to enable in the scene.
    • It is often convenient to 'solo' a light(s) to see the how the shader reacts to a specific light (i.e. a rim light for instance).
  • Regenerate shadowmaps if necessary.
  • Press the render button in the main toolbar.
  • If any errors occur, they will be printed to the command-line.

RIB-boxes

The rib-boxes are where you do most of the customization before rendering. The information in these boxes is injected into the rendered rib file just before rendering. This is just an alternative to editing the rib file directly, and allows you to bypass having to keep yet another window/file open. Use the rib-boxes to:

  • apply shaders
  • set shader parameters
  • apply additional geometry specific attributes (such as displacement bounds)
  • set surface colors
  • etc...

There are two boxes provided. The upper box affects the 'primary' archive geometry, while the lower box affects any 'secondary' archives that might exist. This is to allow you to have a main 'development' shader applied to one object, and a more 'neutral' (i.e. plastic, etc..) shader applied to a secondary object (if it exists). Note that the only default objects that support the secondary rib-box, are the 'shaderball' and 'bulb' objects. The extra archives that can be downloaded above, have further examples of this. The rib-boxes have only two real commands that they support (note that they must be 'active' or selected for the commands to work):

  • ctrl-s will save the current information to file (i.e. make it the default).
  • ctrl-r will reload the saved information.
    • It is not necessary to manually save the information before rendering; however, if it is not saved then the boxes will re-load the last saved information on the next launch.

Lights

All lights in the default rib file are located in the '.../bhm_lightTools/renderman/archives/lights.rib' file. At launch, the app will scan through this file and automatically add the corresponding GUI elements to interact with it. This means that this lights archive file may be edited/altered/added-to at will; however, there are a few limitations and rules to follow in order for the GUI to respond correctly.

  • All lights must be declared in the following format:
LightSource "shadowspot" "key"                                                       # All on the same line (Lightsource "<shader>" "<lightname>"). Only this information on this line.
					"lightcolor" [0.9 1 0.8]                     # One shader parameter per line ("<parameter>" <value>)
					"intensity" 250 
					"point from" [5 6 -10]
					"point to" [0 1 0]
					"coneangle" [0.35]
					"float samples" 48
					"float blur" 0.006
					"string shadowname" ["./shadowmaps/key.shd"] # paths are relative to the main 'renderman' directory
  • All lights must be accompanied by a corresponding integer variable (boolean switch) in the format of:
Illuminate "key" 1      # Again, all on one line (Illuminate "<lightname>" <0 or 1>
  • This file, and the boolean values will be edited and overwritten any time that the corresponding check-box in the GUI is toggled. Therefore, you may edit this file, but beware that it should be closed upon finishing, or any changes you make may be lost.
  • In order for shadowmaps to be generated for a light, they must be of a spotlight format (i.e. include a "point from" and a "point to" declaration). Obviously not all spotlight shaders require this, however for the purposes of this app, it is most convenient if they do.

Shadowmaps

By default, shadowmaps are used for shadowing. Because of this, these shadowmaps need to be regenerated any time that the shader geometry is altered/changed significantly. By pressing the "reprocess shadowmaps" button, the shadowmaps will be automatically generated according to the geometry selected.

  • Shadowmaps are automatically generated for all spot-light type lights in the '.../renderman/archives/lights.rib' file. Any light without a 'from' and 'to' parameter will be ignored.
  • Note that some shadowmaps may be shared between renderers. For example: 3Delight can read shadowmaps generated by PRman; however, the reverse is not true. Aqsis cannot read the files generated by either 3Delight or PRman; however, both PRman and 3Delight are able to read the shadowmaps created by Aqsis... This means that if you have Aqsis on your system, you can render the shadowmaps using Aqsis, and then freely switch between other renderers without having to re-generate new maps.
  • For simplicity and compatibility between the renderers, currently only standard shadowmaps are generated. However, as these are essentially preview renders, even without DSM's the results seem to be passable even when using hair/fur geometry archives.
  • The shadowmap resolution may be adjusted by editing the 'res:' entry field next to the 'reprocess shadowmaps' button. The default value may be adjusted in the preferences file. A (perhaps overly large) value of 1024px is used by default. Shadow generation times will be affected by the resolution of the maps as well as the complexity of the selected geometry; however, minimal improvements in speed are seen in the range of 256-1024 resolutions. All shadowmaps are generated at the same resolution.
  • Shadow maps only need to be regenerated when changing the geometry archive used, or when switching renderers (see above for re-using maps between renderers).
  • If you wish to use raytraced shadows, you can edit the '.../renderman/archives/lights.rib' file. Replace the shadowmap name (i.e. 'key.shd') with 'raytrace'. Note that this is significantly slower to render in most cases.

Adding Custom Archives

The rendering app supports the ability to easily add your own custom rib archives as optional rendering geometry. The steps to add an archive are as follows:

  • Write the archive by hand or export if from your favorite 3d app.
    • archive should only contain the geometry specification (exclude any lights,shaders,WorldBegin/End statements,etc...)
  • Place the archive in a suitably named folder in the 'archives' directory. Within this folder, your rib files should be named 'primary.rib'(and 'secondary.rib', if there are two).
Folder Structure:
                 .../renderman/archives/...
                                        /<archive_name>/...
                                                        /primary.rib
                                                        /secondary.rib
  • That's it! The app will scan the directory on the next launch and add your archive to the list.
  • You may need to add some additional transforms and scaling onto your archive to make it fit the scene and match the other existing archives. This can be achieved by adding the necessary transform blocks directly in the 'primary' and 'secondary' files. Have a look through the supplied archives for examples of how to do this.
  • You can create more complex/nested archives if you wish, but just remember that your final archive names must match the above. As a reference, download the extra archives provided above, and examine the 'honda_car' archive. This showcases how to nest additional archives into the 'primary' and 'secondary' archives. This probably isn't a best-practice for production, but it greatly simplifies the addition of custom geometry into the app to provide alternative means of previewing your shaders.

IOR

About

This part of the application has just been replaced. The new charts should be pretty straight forward, but new information will be posted soon to hopefully clarify any issues. Thanks!

Notepad

About

Not a whole lot to say about this one... It is a place to take notes while you work, or to generate a log of your progress.

  • If used as a means to generate a log:
    • you can edit the 'yourname' variable in the preferences file to set the default name.
    • Information in the text field is appended to the selected log file, along with the artist name (yourname), and the current date.
    • You can view the selected log by pressing the 'View Log' button in the main tool-bar

History

  • v0.0.X
    • command line only. No GUI
  • V0.1.x
    • GUI created
  • v0.2.x
    • updated GUI
    • updated code and math
    • added dropdown menus for presets (under linux and windows, you may have to click on the drop-down a second time to get the values to populate to the correct field...)
  • v0.3.x
    • Expanded app to incorporate a few other tools (IOR tables, Shader-dev/rendering environment, and a notepad/logbook)
    • This also involved extensive (nearly complete) re-writes of much of the GUI and underlying modules. Because of this, much of the code is relatively fresh/untested, so let me know if you come across any issues...
    • Added some error checking in the preferences file to allow for some flexibility in folder structure and missing directories
    • Added new IOR graphing/chart app to replace the fairly useless IOR tables.
    • Added checkboxes to toggle IOR curves in IOR app
  • v0.3.4
    • Added hooks into Maya and Softimage/XSI for setting light parameters based of returned colors
    • Added 'simple' Fresnel curves in the IOR app for comparing against Schlick and complex Fresnel curves.
    • General tinkering and restructuring of app. Broke out each 'app' into separate modules as the main module was getting a bit long to navigate on its own.

Disclaimer

This software comes with no warranty, implied or otherwise. While the results are perceptually close, the math calculating the values is based heavily on estimations/approximations. This is meant as an artistic, not scientific, tool. Please use accordingly.

Personal tools