1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>FreeMat: vtkLightKit</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">FreeMat
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('vtkrendering_vtklightkit.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">vtkLightKit </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Section: <a class="el" href="sec_vtkrendering.html">Visualization Toolkit Rendering Classes</a> </p>
<h1><a class="anchor" id="Usage"></a>
Usage</h1>
<p>vtkLightKit is designed to make general purpose lighting of vtk scenes simple, flexible, and attractive (or at least not horribly ugly without significant effort). Use a LightKit when you want more control over your lighting than you can get with the default vtk light, which is a headlight located at the camera. (HeadLights are very simple to use, but they don't show the shape of objects very well, don't give a good sense of "up" and "down", and don't evenly light the object.)</p>
<p>A LightKit consists of three lights, a key light, a fill light, and a headlight. The main light is the key light. It is usually positioned so that it appears like an overhead light (like the sun, or a ceiling light). It is generally positioned to shine down on the scene from about a 45 degree angle vertically and at least a little offset side to side. The key light usually at least about twice as bright as the total of all other lights in the scene to provide good modeling of object features.</p>
<p>The other lights in the kit (the fill light, headlight, and a pair of back lights) are weaker sources that provide extra illumination to fill in the spots that the key light misses. The fill light is usually positioned across from or opposite from the key light (though still on the same side of the object as the camera) in order to simulate diffuse reflections from other objects in the scene. The headlight, always located at the position of the camera, reduces the contrast between areas lit by the key and fill light. The two back lights, one on the left of the object as seen from the observer and one on the right, fill on the high-contrast areas behind the object. To enforce the relationship between the different lights, the intensity of the fill, back and headlights are set as a ratio to the key light brightness. Thus, the brightness of all the lights in the scene can be changed by changing the key light intensity.</p>
<p>All lights are directional lights (infinitely far away with no falloff). Lights move with the camera.</p>
<p>For simplicity, the position of lights in the LightKit can only be specified using angles: the elevation (latitude) and azimuth (longitude) of each light with respect to the camera, expressed in degrees. (Lights always shine on the camera's lookat point.) For example, a light at (elevation=0, azimuth=0) is located at the camera (a headlight). A light at (elevation=90, azimuth=0) is above the lookat point, shining down. Negative azimuth values move the lights clockwise as seen above, positive values counter-clockwise. So, a light at (elevation=45, azimuth=-20) is above and in front of the object and shining slightly from the left side.</p>
<p>vtkLightKit limits the colors that can be assigned to any light to those of incandescent sources such as light bulbs and sunlight. It defines a special color spectrum called "warmth" from which light colors can be chosen, where 0 is cold blue, 0.5 is neutral white, and 1 is deep sunset red. Colors close to 0.5 are "cool whites" and "warm whites," respectively.</p>
<p>Since colors far from white on the warmth scale appear less bright, key-to-fill and key-to-headlight ratios are skewed by key, fill, and headlight colors. If the flag MaintainLuminance is set, vtkLightKit will attempt to compensate for these perceptual differences by increasing the brightness of more saturated colors.</p>
<p>A LightKit is not explicitly part of the vtk pipeline. Rather, it is a composite object that controls the behavior of lights using a unified user interface. Every time a parameter of vtkLightKit is adjusted, the properties of its lights are modified.</p>
<p>.SECTION Credits vtkLightKit was originally written and contributed to vtk by Michael Halle (<a href="#" onclick="location.href='mai'+'lto:'+'mha'+'ll'+'e@b'+'wh'+'.ha'+'rv'+'ard'+'.e'+'du'; return false;">mhall<span style="display: none;">.nosp@m.</span>e@bw<span style="display: none;">.nosp@m.</span>h.har<span style="display: none;">.nosp@m.</span>vard<span style="display: none;">.nosp@m.</span>.edu</a>) at the Surgical Planning Lab, Brigham and Women's Hospital.</p>
<p>To create an instance of class vtkLightKit, simply invoke its constructor as follows </p>
<pre class="fragment"> obj = vtkLightKit
</pre> <h1><a class="anchor" id="Methods"></a>
Methods</h1>
<p>The class vtkLightKit has several methods that can be used. They are listed below. Note that the documentation is translated automatically from the VTK sources, and may not be completely intelligible. When in doubt, consult the VTK website. In the methods listed below, <code>obj</code> is an instance of the vtkLightKit class. </p>
<ul>
<li>
<code>string = obj.GetClassName ()</code> </li>
<li>
<code>int = obj.IsA (string name)</code> </li>
<li>
<code>vtkLightKit = obj.NewInstance ()</code> </li>
<li>
<code>vtkLightKit = obj.SafeDownCast (vtkObject o)</code> </li>
<li>
<code>obj.SetKeyLightIntensity (double )</code> - Set/Get the intensity of the key light. The key light is the brightest light in the scene. The intensities of the other two lights are ratios of the key light's intensity. </li>
<li>
<code>double = obj.GetKeyLightIntensity ()</code> - Set/Get the intensity of the key light. The key light is the brightest light in the scene. The intensities of the other two lights are ratios of the key light's intensity. </li>
<li>
<code>obj.SetKeyToFillRatio (double )</code> - Set/Get the key-to-fill ratio. This ratio controls how bright the fill light is compared to the key light: larger values correspond to a dimmer fill light. The purpose of the fill light is to light parts of the object not lit by the key light, while still maintaining constrast. This type of lighting may correspond to indirect illumination from the key light, bounced off a wall, floor, or other object. The fill light should never be brighter than the key light: a good range for the key-to-fill ratio is between 2 and 10. </li>
<li>
<code>double = obj.GetKeyToFillRatioMinValue ()</code> - Set/Get the key-to-fill ratio. This ratio controls how bright the fill light is compared to the key light: larger values correspond to a dimmer fill light. The purpose of the fill light is to light parts of the object not lit by the key light, while still maintaining constrast. This type of lighting may correspond to indirect illumination from the key light, bounced off a wall, floor, or other object. The fill light should never be brighter than the key light: a good range for the key-to-fill ratio is between 2 and 10. </li>
<li>
<code>double = obj.GetKeyToFillRatioMaxValue ()</code> - Set/Get the key-to-fill ratio. This ratio controls how bright the fill light is compared to the key light: larger values correspond to a dimmer fill light. The purpose of the fill light is to light parts of the object not lit by the key light, while still maintaining constrast. This type of lighting may correspond to indirect illumination from the key light, bounced off a wall, floor, or other object. The fill light should never be brighter than the key light: a good range for the key-to-fill ratio is between 2 and 10. </li>
<li>
<code>double = obj.GetKeyToFillRatio ()</code> - Set/Get the key-to-fill ratio. This ratio controls how bright the fill light is compared to the key light: larger values correspond to a dimmer fill light. The purpose of the fill light is to light parts of the object not lit by the key light, while still maintaining constrast. This type of lighting may correspond to indirect illumination from the key light, bounced off a wall, floor, or other object. The fill light should never be brighter than the key light: a good range for the key-to-fill ratio is between 2 and 10. </li>
<li>
<code>obj.SetKeyToHeadRatio (double )</code> - Set/Get the key-to-headlight ratio. Similar to the key-to-fill ratio, this ratio controls how bright the headlight light is compared to the key light: larger values correspond to a dimmer headlight light. The headlight is special kind of fill light, lighting only the parts of the object that the camera can see. As such, a headlight tends to reduce the contrast of a scene. It can be used to fill in "shadows" of the object missed by the key and fill lights. The headlight should always be significantly dimmer than the key light: ratios of 2 to 15 are typical. </li>
<li>
<code>double = obj.GetKeyToHeadRatioMinValue ()</code> - Set/Get the key-to-headlight ratio. Similar to the key-to-fill ratio, this ratio controls how bright the headlight light is compared to the key light: larger values correspond to a dimmer headlight light. The headlight is special kind of fill light, lighting only the parts of the object that the camera can see. As such, a headlight tends to reduce the contrast of a scene. It can be used to fill in "shadows" of the object missed by the key and fill lights. The headlight should always be significantly dimmer than the key light: ratios of 2 to 15 are typical. </li>
<li>
<code>double = obj.GetKeyToHeadRatioMaxValue ()</code> - Set/Get the key-to-headlight ratio. Similar to the key-to-fill ratio, this ratio controls how bright the headlight light is compared to the key light: larger values correspond to a dimmer headlight light. The headlight is special kind of fill light, lighting only the parts of the object that the camera can see. As such, a headlight tends to reduce the contrast of a scene. It can be used to fill in "shadows" of the object missed by the key and fill lights. The headlight should always be significantly dimmer than the key light: ratios of 2 to 15 are typical. </li>
<li>
<code>double = obj.GetKeyToHeadRatio ()</code> - Set/Get the key-to-headlight ratio. Similar to the key-to-fill ratio, this ratio controls how bright the headlight light is compared to the key light: larger values correspond to a dimmer headlight light. The headlight is special kind of fill light, lighting only the parts of the object that the camera can see. As such, a headlight tends to reduce the contrast of a scene. It can be used to fill in "shadows" of the object missed by the key and fill lights. The headlight should always be significantly dimmer than the key light: ratios of 2 to 15 are typical. </li>
<li>
<code>obj.SetKeyToBackRatio (double )</code> - Set/Get the key-to-back light ratio. This ratio controls how bright the back lights are compared to the key light: larger values correspond to dimmer back lights. The back lights fill in the remaining high-contrast regions behind the object. Values between 2 and 10 are good. </li>
<li>
<code>double = obj.GetKeyToBackRatioMinValue ()</code> - Set/Get the key-to-back light ratio. This ratio controls how bright the back lights are compared to the key light: larger values correspond to dimmer back lights. The back lights fill in the remaining high-contrast regions behind the object. Values between 2 and 10 are good. </li>
<li>
<code>double = obj.GetKeyToBackRatioMaxValue ()</code> - Set/Get the key-to-back light ratio. This ratio controls how bright the back lights are compared to the key light: larger values correspond to dimmer back lights. The back lights fill in the remaining high-contrast regions behind the object. Values between 2 and 10 are good. </li>
<li>
<code>double = obj.GetKeyToBackRatio ()</code> - Set/Get the key-to-back light ratio. This ratio controls how bright the back lights are compared to the key light: larger values correspond to dimmer back lights. The back lights fill in the remaining high-contrast regions behind the object. Values between 2 and 10 are good. </li>
<li>
<code>obj.SetKeyLightWarmth (double )</code> - Set the warmth of each the lights. Warmth is a parameter that varies from 0 to 1, where 0 is "cold" (looks icy or lit by a very blue sky), 1 is "warm" (the red of a very red sunset, or the embers of a campfire), and 0.5 is a neutral white. The warmth scale is non-linear. Warmth values close to 0.5 are subtly "warmer" or "cooler," much like a warmer tungsten incandescent bulb, a cooler halogen, or daylight (cooler still). Moving further away from 0.5, colors become more quickly varying towards blues and reds. With regards to aesthetics, extremes of warmth should be used sparingly. </li>
<li>
<code>double = obj.GetKeyLightWarmth ()</code> - Set the warmth of each the lights. Warmth is a parameter that varies from 0 to 1, where 0 is "cold" (looks icy or lit by a very blue sky), 1 is "warm" (the red of a very red sunset, or the embers of a campfire), and 0.5 is a neutral white. The warmth scale is non-linear. Warmth values close to 0.5 are subtly "warmer" or "cooler," much like a warmer tungsten incandescent bulb, a cooler halogen, or daylight (cooler still). Moving further away from 0.5, colors become more quickly varying towards blues and reds. With regards to aesthetics, extremes of warmth should be used sparingly. </li>
<li>
<code>obj.SetFillLightWarmth (double )</code> </li>
<li>
<code>double = obj.GetFillLightWarmth ()</code> </li>
<li>
<code>obj.SetHeadLightWarmth (double )</code> </li>
<li>
<code>double = obj.GetHeadLightWarmth ()</code> </li>
<li>
<code>obj.SetBackLightWarmth (double )</code> </li>
<li>
<code>double = obj.GetBackLightWarmth ()</code> </li>
<li>
<code>double = obj. GetKeyLightColor ()</code> - Returns the floating-point RGB values of each of the light's color. </li>
<li>
<code>double = obj. GetFillLightColor ()</code> - Returns the floating-point RGB values of each of the light's color. </li>
<li>
<code>double = obj. GetHeadLightColor ()</code> - Returns the floating-point RGB values of each of the light's color. </li>
<li>
<code>double = obj. GetBackLightColor ()</code> - Returns the floating-point RGB values of each of the light's color. </li>
<li>
<code>obj.SetHeadlightWarmth (double v)</code> - To maintain a deprecation API: </li>
<li>
<code>double = obj.GetHeadlightWarmth ()</code> - To maintain a deprecation API: </li>
<li>
<code>obj.GetHeadlightColor (double color)</code> - To maintain a deprecation API: </li>
<li>
<code>obj.MaintainLuminanceOn ()</code> - If MaintainLuminance is set, the LightKit will attempt to maintain the apparent intensity of lights based on their perceptual brightnesses. By default, MaintainLuminance is off. </li>
<li>
<code>obj.MaintainLuminanceOff ()</code> - If MaintainLuminance is set, the LightKit will attempt to maintain the apparent intensity of lights based on their perceptual brightnesses. By default, MaintainLuminance is off. </li>
<li>
<code>int = obj.GetMaintainLuminance ()</code> - If MaintainLuminance is set, the LightKit will attempt to maintain the apparent intensity of lights based on their perceptual brightnesses. By default, MaintainLuminance is off. </li>
<li>
<code>obj.SetMaintainLuminance (int )</code> - If MaintainLuminance is set, the LightKit will attempt to maintain the apparent intensity of lights based on their perceptual brightnesses. By default, MaintainLuminance is off. </li>
<li>
<code>obj.SetKeyLightAngle (double elevation, double azimuth)</code> - Get/Set the position of the key, fill, and back lights using angular methods. Elevation corresponds to latitude, azimuth to longitude. It is recommended that the key light always be on the viewer's side of the object and above the object, while the fill light generally lights the part of the object not lit by the fill light. The headlight, which is always located at the viewer, can then be used to reduce the contrast in the image. There are a pair of back lights. They are located at the same elevation and at opposing azimuths (ie, one to the left, and one to the right). They are generally set at the equator (elevation = 0), and at approximately 120 degrees (lighting from each side and behind). </li>
<li>
<code>obj.SetKeyLightAngle (double angle[2])</code> - Get/Set the position of the key, fill, and back lights using angular methods. Elevation corresponds to latitude, azimuth to longitude. It is recommended that the key light always be on the viewer's side of the object and above the object, while the fill light generally lights the part of the object not lit by the fill light. The headlight, which is always located at the viewer, can then be used to reduce the contrast in the image. There are a pair of back lights. They are located at the same elevation and at opposing azimuths (ie, one to the left, and one to the right). They are generally set at the equator (elevation = 0), and at approximately 120 degrees (lighting from each side and behind). </li>
<li>
<code>obj.SetKeyLightElevation (double x)</code> </li>
<li>
<code>obj.SetKeyLightAzimuth (double x)</code> </li>
<li>
<code>double = obj. GetKeyLightAngle ()</code> </li>
<li>
<code>double = obj.GetKeyLightElevation ()</code> </li>
<li>
<code>double = obj.GetKeyLightAzimuth ()</code> </li>
<li>
<code>obj.SetFillLightAngle (double elevation, double azimuth)</code> </li>
<li>
<code>obj.SetFillLightAngle (double angle[2])</code> </li>
<li>
<code>obj.SetFillLightElevation (double x)</code> </li>
<li>
<code>obj.SetFillLightAzimuth (double x)</code> </li>
<li>
<code>double = obj. GetFillLightAngle ()</code> </li>
<li>
<code>double = obj.GetFillLightElevation ()</code> </li>
<li>
<code>double = obj.GetFillLightAzimuth ()</code> </li>
<li>
<code>obj.SetBackLightAngle (double elevation, double azimuth)</code> </li>
<li>
<code>obj.SetBackLightAngle (double angle[2])</code> </li>
<li>
<code>obj.SetBackLightElevation (double x)</code> </li>
<li>
<code>obj.SetBackLightAzimuth (double x)</code> </li>
<li>
<code>double = obj. GetBackLightAngle ()</code> </li>
<li>
<code>double = obj.GetBackLightElevation ()</code> </li>
<li>
<code>double = obj.GetBackLightAzimuth ()</code> </li>
<li>
<code>obj.AddLightsToRenderer (vtkRenderer renderer)</code> - Add lights to, or remove lights from, a renderer. Lights may be added to more than one renderer, if desired. </li>
<li>
<code>obj.RemoveLightsFromRenderer (vtkRenderer renderer)</code> - Add lights to, or remove lights from, a renderer. Lights may be added to more than one renderer, if desired. </li>
<li>
<code>obj.DeepCopy (vtkLightKit kit)</code> </li>
<li>
<code>obj.Modified ()</code> </li>
<li>
<code>obj.Update ()</code> </li>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">FreeMat Documentation</a></li><li class="navelem"><a class="el" href="sec_vtkrendering.html">Visualization Toolkit Rendering Classes</a></li>
<li class="footer">Generated on Thu Jul 25 2013 17:18:35 for FreeMat by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.1.1 </li>
</ul>
</div>
</body>
</html>
|
