Editing Vtk/SimpleCubeTutorial (section)

==Constructing a More Sophisticated Cube==
Now comes the fun part.  Let's add some more information to the input model data file and, in addition, activate some more methods associated with the various VisTrails modules in order to generate more sophisticated cubes.

===Default Color Table===

====Specifying Colors of Cell Faces Using a Default Color Table====
Tutorial Task:  Assign a separate scalar value to each of the six faces of the cube, then color the faces differently, in accordance with their assigned scalar values.  Continuing to adhere to the ''Simple Legacy Format'', this can be accomplished by adding nine lines of ASCII text to the text file that was created, above, to draw a minimalistic cube.  Each column of the following table presents (top of the column) an example of this additional ASCII text, along with (bottom of the column) the resulting cube image, as rendered by VisTrails.
<div align="center">
<table border="1">
<tr>
  <td align="center">
Example A
  </td>
  <td align="center">
Example B
  </td>
  <td align="center">
Example C
  </td>
</tr>
<tr>
  <td align="left">
<pre style="color:maroon;font-size:100%">
# vtk DataFile Version 2.0
Cube example
ASCII
DATASET POLYDATA
POINTS 8 float
0.0 0.0 0.0
1.0 0.0 0.0
1.0 1.0 0.0
0.0 1.0 0.0
0.0 0.0 1.0
1.0 0.0 1.0
1.0 1.0 1.0
0.0 1.0 1.0
POLYGONS 6 30
4 0 1 2 3
4 4 5 6 7
4 0 1 5 4
4 2 3 7 6
4 0 4 7 3
4 1 2 6 5

CELL_DATA 6
SCALARS cell_scalars float 1
LOOKUP_TABLE default
0.0
0.2
0.4
0.6
0.8
1.0
</pre>
  </td>
  <td align="left">
<pre style="color:maroon;font-size:100%">
(same first 20 lines of text)
.
.
.



.
.
.



.
.
.





CELL_DATA 6
SCALARS cell_scalars float 1
LOOKUP_TABLE default
0.0
0.1
0.2
0.3
0.4
0.5
</pre>
  </td>
  <td align="left">
<pre style="color:maroon;font-size:100%">
(same first 20 lines of text)
.
.
.



.
.
.



.
.
.





CELL_DATA 6
SCALARS cell_scalars int 1
LOOKUP_TABLE default
0
1
2
3
4
5
</pre>
  </td>
</tr>
<tr>
  <th align="center" colspan="3">
Corresponding Rendering of Cube by VisTrails
  </th>
</tr>
<tr>
  <td align="center">
[[Image:Screenshot02.jpg|200px|Screenshot_A]]
  </td>
  <td align="center" valign="bottom">
[[Image:Screenshot03.png|200px|Screenshot_B]]
  </td>
  <td align="center">
[[Image:Screenshot04.png|200px|Screenshot_C]]
  </td>
</tr>
</table>
</div>
<font color="blue">'''General Explanation:''' </font>
* "CELL_DATA 6" means that the subsequent numerical values should be assigned, in sequence, to each of the 6 polygonal (square) faces of the cube.
* "SCALARS cell_scalars float 1" (see Examples A &amp; B) means that, in each case, the assigned numerical value will be a floating-point number; "SCALARS cell_scalars int 1" (see Example C) means that the assigned numerical value will be an integer number.  As necessary, the name "cell_scalars" will be used to reference this assigned set of scalar values.  In principle, up to four separate sets of scalar values can be assigned to the faces of the cube (see the discussion associated with the parameter ''numComp'' on p. 329 of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide'']); the "1" at the end of this line of text indicates that the values associated with the name "cell_scalars" will be referenced as the ''first'' scalar component; it is optional if there is only one scalar component.
* "LOOKUP_TABLE default" means that the color that is assigned to each face will be determined by correlating the scalar value assigned to each face with the scalar values assigned to the standard rainbow of colors as defined by [[vtk/SimpleCubeTutorial#Deciphering_VTK.27s_default_Lookup_Table|VTK's ''default'' lookup color table]]. 

<font color="blue">Example A:</font>
* The six assigned floating-point numbers range from 0.0 to 1.0, in increments of 0.2.  By inspection, it appears as though [[vtk/SimpleCubeTutorial#Deciphering_VTK.27s_default_Lookup_Table|VTK's default color table]] spreads the rainbow of (RGB) colors across this same interval, with 0.0 being assigned to red and 1.0 being assigned to blue.  It is therefore not surprising that the three initially visible faces of the rendered cube are red, green, and blue.  The colors of the other three faces of the cube are revealed by using the computer mouse to spin the VisTrails spreadsheet rendering of the cube.

<font color="blue">Example B:</font>
* The six assigned floating-point numbers range from 0.0 to 0.5, in increments of 0.1.  Because three of the assigned scalar values (0.0, 0.2, and 0.4) match values assigned in Example A, three of the faces of this cube should have the same colors as three of the faces of the Example A cube, but not necessarily the same cube face in both examples.  Also, none of the faces is blue because the assigned scalar values all lie well below 1.0.

<font color="blue">Example C:</font>
* The six assigned integer numbers range from 0 to 5, in increments of 1.  One face &#8212; the one whose assigned scalar value is zero &#8212; is colored red; all five other faces are colored blue because the color table does not extend beyond 1.0 and VTK's default coloring rule (see [[vtk/SimpleCubeTutorial#mapping|further elaboration, below]]) is to peg scalar values at one (i.e., blue) if their assigned values are greater than unity.

<font color="red">'''Comment#1 (by J. E. Tohline):'''</font>  Notice that, once a set of scalar values has been assigned to cell faces, the colors provided by the default LOOKUP_TABLE override the "tomato" color that is specified by the "vtkProperty" module of the VisTrails pipeline.  The default "tomato" color can be retrieved without modifying the new input datafile by clicking on (i.e., selecting) the "vtkPolyDataMapper" module in the VisTrails pipeline, dragging the "ScalarVisibilityOff" method into the "Set Methods" segment of the VisTrials Builder Window, then reexecuting the pipeline.

<font color="red">'''Comment#2 (by J. E. Tohline):'''</font>  Example C, shown here, adopts the same CELL_DATA scalar values that appear in the simple "cube example" presented in &sect;15.3 (see the top of p. 332) of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide''].  In my opinion, this was a very odd choice to make if its purpose was to help students understand how the VTK and/or VisTrails machinery works.  I, for one, was pretty sure I was still doing something wrong when I was finally able to read the "cube example" file into the VisTrails "vtkPolyDataReader," because most of the faces of the cube were painted the same color (blue) whereas I was expecting them all to have different, illustrative colors.

====Deciphering VTK's ''default'' Lookup Table====
While color values that are prescribed by VTK's ''default'' lookup table have been used in the three example ASCII files just discussed &#8212; Examples A, B, and C &#8212; the code that VTK uses to map scalar values to specific colors has not been explicitly provided.  When I began trying to understand, for myself, how color specification is handled in VTK, I was unable to locate a reference that spells out what the properties are of the ''default'' lookup table.  By experimentation I discovered that a simple lookup table that comes close to mimicking the default one is as follows:
<div align="center">
<pre>
LOOKUP_TABLE my_table 6
1.0 0.0 0.0 1.0
1.0 1.0 0.0 1.0
0.0 1.0 0.0 1.0
0.0 1.0 0.0 1.0
0.0 1.0 1.0 1.0
0.0 0.0 1.0 1.0
</pre>
</div>

Eventually I discovered documentation that defines the default settings for VTK's color maps.  In &sect;6.6 of [http://www.amazon.com/Visualization-Toolkit-Object-Oriented-Approach-Graphics/dp/193093419X/ref=pd_sim_sbs_b_1?ie=UTF8&refRID=0EFGPTSBP5E136WEK4V7 Schroeder, Martin, &amp; Lorensen (2006)] (see specifically the subsection titled '''Color Maps''' on p. 196), we are told the default settings are established via a specification of HSV (Hue-Saturation-Value) rather than via an <font face="Courier">rgb</font> specification.  The default settings are:  HueRange (0, 2/3); SaturationRange (1,1); and ValueRange (1,1).  This terminology is explained in an [[vtk/ColorLookupTablea#Color_Lookup_Tables|accompanying presentation]].

===Specifying Colors of Cell Faces via a User-defined Color Table===
Now, suppose you don't like the colors that are assigned to each of the six faces of the cube by [[vtk/SimpleCubeTutorial#Deciphering_VTK.27s_default_Lookup_Table|VTK's ''default'' color table]].  You can assign a different set of colors by explicitly defining your own "LOOKUP_TABLE."  To illustrate how this is done, we have added nine additional lines of ASCII text to the input data files shown in ''Example D'' and ''Example E'', below.  In both cases, we have inserted the LOOKUP_TABLE that has been provided as part of the "simple cube" example that is provided on pp. 331-332 of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide''].  

<div align="center">
<table border="1">
<tr>
  <th align="center" colspan="4">
LOOKUP_TABLE Example in ''Simple Legacy Format''
  </th>
</tr>
<tr>
  <td align="center">
Example A
  </td>
  <td align="center">
Example D
  </td>
  <td align="center">
Example E
  </td>
  <td align="center">
Color Code
  </td>
</tr>
<tr>
  <td align="left">
<pre style="color:maroon;font-size:100%">
# vtk DataFile Version 2.0
Cube example
ASCII
DATASET POLYDATA
POINTS 8 float
0.0 0.0 0.0
1.0 0.0 0.0
1.0 1.0 0.0
0.0 1.0 0.0
0.0 0.0 1.0
1.0 0.0 1.0
1.0 1.0 1.0
0.0 1.0 1.0
POLYGONS 6 30
4 0 1 2 3
4 4 5 6 7
4 0 1 5 4
4 2 3 7 6
4 0 4 7 3
4 1 2 6 5

CELL_DATA 6
SCALARS cell_scalars float 1
LOOKUP_TABLE default
0.0
0.2
0.4
0.6
0.8
1.0
</pre>
  </td>
  <td align="left">
<pre style="color:maroon;font-size:100%">
(same first 20 lines of text)
.
.
.



.
.
.


CELL_DATA 6
SCALARS cell_scalars float 1
LOOKUP_TABLE my_table
0.0
0.1
0.2
0.3
0.4
0.5
LOOKUP_TABLE my_table 8
0.0 0.0 0.0 1.0
1.0 0.0 0.0 1.0
0.0 1.0 0.0 1.0
1.0 1.0 0.0 1.0
0.0 0.0 1.0 1.0
1.0 0.0 1.0 1.0
0.0 1.0 1.0 1.0
1.0 1.0 1.0 1.0
</pre>
  </td>
  <td align="left">
<pre style="color:maroon;font-size:100%">
(same first 20 lines of text)
.
.
.



.
.
.


CELL_DATA 6
SCALARS cell_scalars float 1
LOOKUP_TABLE my_table
0.14286
0.28571
0.42857
0.57143
0.71429
0.85714
LOOKUP_TABLE my_table 8
0.0 0.0 0.0 1.0
1.0 0.0 0.0 1.0
0.0 1.0 0.0 1.0
1.0 1.0 0.0 1.0
0.0 0.0 1.0 1.0
1.0 0.0 1.0 1.0
0.0 1.0 1.0 1.0
1.0 1.0 1.0 1.0
</pre>
  </td>
  <td align="left" rowspan="3">

<table border="1" cellpadding="5" align="center">
<tr>
  <th align="center">
R
  </th>
  <th align="center">
G
  </th>
  <th align="center">
B
  </th>
  <th align="center">
Result
  </th>
  <th align="center">
HEX
  </th>
</tr>

<tr>
  <td align="center">
0.0
  </td>
  <td align="center">
0.0
  </td>
  <td align="center">
0.0
  </td>
  <td align="center" bgcolor="#000000">
<font color="white">black</font>
  </td>
  <td align="center">
000000
  </td>
</tr>

<tr>
  <td align="center">
1.0
  </td>
  <td align="center">
0.0
  </td>
  <td align="center">
0.0
  </td>
  <td align="center" bgcolor="#FF0000">
<font color="white">red</font>
  </td>
  <td align="center">
FF0000
  </td>
</tr>

<tr>
  <td align="center">
0.0
  </td>
  <td align="center">
1.0
  </td>
  <td align="center">
0.0
  </td>
  <td align="center" bgcolor="#00FF00">
<font color="white">green</font>
  </td>
  <td align="center">
00FF00
  </td>
</tr>

<tr>
  <td align="center">
1.0
  </td>
  <td align="center">
1.0
  </td>
  <td align="center">
0.0
  </td>
  <td align="center" bgcolor="#FFFF00">
<font color="black">yellow</font>
  </td>
  <td align="center">
FFFF00
  </td>
</tr>

<tr>
  <td align="center">
0.0
  </td>
  <td align="center">
0.0
  </td>
  <td align="center">
1.0
  </td>
  <td align="center" bgcolor="#0000FF">
<font color="white">blue</font>
  </td>
  <td align="center">
0000FF
  </td>
</tr>

<tr>
  <td align="center">
1.0
  </td>
  <td align="center">
0.0
  </td>
  <td align="center">
1.0
  </td>
  <td align="center" bgcolor="#FF00FF">
<font color="white">magenta</font>
  </td>
  <td align="center">
FF00FF
  </td>
</tr>

<tr>
  <td align="center">
0.0
  </td>
  <td align="center">
1.0
  </td>
  <td align="center">
1.0
  </td>
  <td align="center" bgcolor="#00FFFF">
<font color="white">cyan</font>
  </td>
  <td align="center">
00FFFF
  </td>
</tr>
<tr>
  <td align="center">
1.0
  </td>
  <td align="center">
1.0
  </td>
  <td align="center">
1.0
  </td>
  <td align="center" bgcolor="#FFFFFF">
white
  </td>
  <td align="center">
FFFFFF
  </td>
</tr>
</table>
See also &hellip; 
* Figure 3-4 (p. 38) of <br><font size="-2">[http://www.amazon.com/Visualization-Toolkit-Object-Oriented-Approach-Graphics/dp/193093419X/ref=pd_sim_sbs_b_1?ie=UTF8&refRID=0EFGPTSBP5E136WEK4V7 Schroeder, Martin, &amp; Lorensen (2006)]</font>
and details regarding the community's Color-by-Name conventions &hellip;
* [http://www.vtk.org/Wiki/VTK/Examples/Python/Visualization/VTKNamedColorPatches_html vtk's official website]
* [http://www.w3.org/TR/css3-color/#svg-color w3 specification]
* [http://en.wikipedia.org/wiki/Web_colors Wikipedia discussion]
&nbsp;
<br>
&nbsp;
<br>
&nbsp;
<br>
  </td>
</tr>
<tr>
  <th align="center" colspan="3">
Corresponding Rendering of Cube by VisTrails
  </th>
</tr>
<tr>
  <td align="center">
[[Image:Screenshot02.jpg|200px|Screenshot_A]]
  </td>
  <td align="center" valign="bottom">
[[Image:Screenshot05.png|200px|Screenshot_D]]
  </td>
  <td align="center">
[[Image:Screenshot06.png|200px|Screenshot_E]]
  </td>
</tr>
</table>
</div>

<font color="blue">'''General Explanation:''' </font>
* The [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide''] (see bottom of p. 329), explains the construction of the ''Simple Legacy Format'' LOOKUP_TABLE as follows:
<div align="center">
<table border="0" cellpadding="5" width="75%">
<tr><td align="center">
  <table border="0" cellpadding="5">
<tr><td align="left">
<font face="Courier">
LOOKUP_TABLE ''tableName'' ''size''<br>
</font>
<math>r_0 ~g_0 ~b_0 ~\alpha_0</math>

<math>r_1 ~g_1 ~b_1 ~\alpha_1</math>

&hellip;

<math>r_{size-1} ~g_{size-1} ~b_{size-1} ~\alpha_{size-1}</math>
</td></tr>
  
  </table>
</td></tr>
<tr><td align="left">
The ''tableName'' field is a character string (without imbedded white space) used to identify the lookup table.  This label is used by the VTK reader to extract a specific table.

Each entry in the lookup table is a <font face="Courier">rgba</font> (''red-green-blue-alpha'') array (''alpha'' is opacity where ''alpha = 0'' is transparent).  If the file format is ASCII, the lookup table values must be <font face="Courier">float</font> values between (0,1).
</td></tr>
</table>
</div>
* Notice that the LOOKUP_TABLE that has been added to the ASCII input data file in Examples D and E has ''tableName = my_table'' and has ''size = 8'', that is, it contains eight distinct <font face="Courier''>rgba</font> colors &#8212; each row of numbers specifies a distinct color and, in this case, they all have the same transparency, <math>~\alpha=1.0</math> (''i.e.,'' completely opaque).  The "color code" table that has been provided to the right of Example E shows what color results from each of the eight assigned RGB triplets; the equivalent hexadecimal representation is provided for each color as well. 
* <span id="mapping">As is explained</span> in &sect;6.2 of [http://www.amazon.com/Visualization-Toolkit-Object-Oriented-Approach-Graphics/dp/193093419X/ref=pd_sim_sbs_b_1?ie=UTF8&refRID=0EFGPTSBP5E136WEK4V7 Schroeder, Martin, &amp; Lorensen (2006)], the mapping of scalar values to the color table proceeds as follows:
<div align="center">
<table border="1" cellpadding="5" width="75%">
<tr>
  <td align="center">
Mapping Scalar Values to the Color Lookup Table<br>
[copied from [http://www.amazon.com/Visualization-Toolkit-Object-Oriented-Approach-Graphics/dp/193093419X/ref=pd_sim_sbs_b_1?ie=UTF8&refRID=0EFGPTSBP5E136WEK4V7 Schroeder, Martin, &amp; Lorensen (2006)]]
  </td>
</tr>
<tr>
  <td align="center">
[[Image:VTKfigure6-1.png|450px|Mapping Scalars to Colors]]
  </td>
</tr>
<tr>
  <td align="left">
As illustrated above, in the first bulleted comment under ''General Explanation,'' "the lookup table holds an array of colors (e.g., red, green, blue components or other comparable representations).  Associated with the table is a minimum and maximum ''scalar range (min, max)'' into which the scalar values are  mapped.  Scalar values greater than the maximum range are clamped to the maximum color, scalar values less than the minimum range are clamped to the minimum color value.  Then, for each scalar value <math>~s_i</math>, the index <math>~i</math> into the color table with <math>~n</math> entries (and 0-offset) is given by" the figure shown here.
  </td>
</tr>
</table>
</div>

<font color="blue">Example A:</font> (Identical to ''Example A'' shown earlier)
* The six scalar (floating-point) values that have been assigned to the six faces of the cube range from 0.0 to 1.0, in increments of 0.2.  Presumably, VTK's default color table spreads the rainbow of (RGB) colors across this same interval, with 0.0 being assigned to red and 1.0 being assigned to blue.  

<font color="blue">Example D:</font>
* As in ''Example B'' shown earlier, the six assigned floating-point scalars range from 0.0 to 0.5, in increments of 0.1.  But now the second line of text following <font face="Courier">CELL_DATA 6</font> explicitly tells the VTK reader to refer to the user-provided "LOOKUP_TABLE" called ''my_table'' when assigning a color to each of the six scalar values.
* As I understand it, VTK will assign the first of the eight colors (black) to a scalar value of 0.0 and it will assign the last of the eight colors (white) to a scalar value of 1.0; the other six colors get mapped in linear proportion to scalar values that fall between 0.0 and 1.0.  
* (This comment will make more sense after studying Example E.)  It appears as though the scalar values are rounded down before a color assignment is made &#8212; and it looks like there is no interpolation between colors:  A complete examination of the cube that is generated by VisTrails from the Example D input file reveals that the two sides labeled as polygons #0 and #1 are painted <font face="Courier">black</font>, presumably because they both have been assigned scalar values < 1/7 = 0.14286; polygon #2 is painted <font face="Courier">red</font>, presumably because it has been assigned a scalar value lying between 1/7 and 2/7; polygon #3 is painted <font face="Courier">green</font>, presumably because its scalar value lies between 2/7 and 3/7; etc.  None of the faces of the cube have been colored <font face="Courier">magenta</font>, <font face="Courier">cyan</font>, or <font face="Courier">white</font>, presumably because their assigned scalar values are all less than 5/7 = 0.57143.

<font color="blue">Example E:</font>
* This is the same as Example D, except that six new scalar values have been assigned to the six polygons that define the faces of the cube.  
* With the intent of avoiding the first and last colors (<font face="Courier">black</font> and <font face="Courier">white</font>) in the lookup table but assigning one each of the other six colors to each of the six cube faces, we have assigned scalar values that are an integer number times 1/7, that is, the values:  1/7, 2/7, 3/7, 4/7, 5/7, and 6/7.  This was done based on the assumption, as stated earlier in connection with Example D, that <font face="Courier">black</font> gets mapped to a scalar value of 0.0 (or less), <font face="Courier">white</font> gets mapped to a scalar value of 1.0 (or greater), while "the other six colors get mapped in linear proportion to scalar values that fall between 0.0 and 1.0."
* Success!  The rendered cube that initially appears in the VisTrails spreadsheet (see the image at the bottom of the "Example E" figure column, above) shows three sides of the cube colored <font face="Courier">red</font>, <font face="Courier">blue</font>, and <font face="Courier">cyan</font> corresponding to, respectively, polygons #0, #3, and #5.  Spinning the cube will allow you to view all three of the other lookup table colors:  <font face="Courier">green</font> (polygon #1), <font face="Courier">yellow</font> (polygon #2), and <font face="Courier">magenta</font> (polygon #4).

As part of this tutorial, you are now encouraged to explore how the coloring of the faces of this "simple cube" are altered when different scalar values are assigned or when different  triplets of RGB colors are specified in the user-provided LOOKUP_TABLE.  For example:  try assigning scalar values that are greater than unity or less than zero; try using fractional values (that is, not just 1.0 or 0.0) for the R, G, and/or B table specifications; and try designing a larger color table, say, one that contains a dozen or more different colors (don't forget to change the value of the ''size'' parameter in the header of the LOOKUP_TABLE).

===Other Knobs to Twist===
<table border="0" width="40%" align="right" cellpadding="12">
<tr><td align="center">

<table border="1" cellpadding="4">
<tr>
  <td align="center" colspan="3">
'''<font color="darkblue">Cheetsheet</font>'''
  </td>
</tr>
<tr>
  <td align="center">
Module:
  </td>
  <td align="center">
Method Action:
  </td>
  <td align="center">
Result
  </td>
</tr>
<tr>
  <td align="left">
vtkPolyDataReader
  </td>
  <td align="left">
SetLookupTableName = my_table
  </td>
  <td align="left">
'''my_table'''<sup>&dagger;</sup> 
  </td>
</tr>
<tr>
  <td align="left" rowspan="2">
vtkPolyDataReader
  </td>
  <td align="left" rowspan="2">
SetLookupTableName = default
  </td>
  <td align="left">
<font size="-1">VTK's default hue-based color table </font>
  </td>
</tr>
<tr>
  <td align="left">
<font size="-1">Color table provided by ''vtkLookupTable'' module, if one hooked into ''vtkPolyDataMapper'' </font>
  </td>
</tr>
<tr>
  <td align="left">
vtkPolyDataMapper
  </td>
  <td align="left">
ScalarVisibilityOff
  </td>
  <td align="left">
Color defined by vtkProperty module 
  </td>
</tr>
<tr>
  <td align="left">
vtkProperty
  </td>
  <td align="left">
SetRepresentationToWireframe
  </td>
  <td align="left">
Rendered as wireframe only 
  </td>
</tr>
<tr>
  <td align="left" colspan="3">
<font size="-1"><sup>&dagger;</sup>Table obtained from ''Simple Legacy Formatted'' input file</font>
  </td>
</tr>
</table>

</td></tr></table>
<font color="blue">Switch Between Different Color Tables:</font>
* When using the input data file associated with Example E, the six faces of the cube will be colored according to the values assigned by the user to the "my_table" LOOKUP_TABLE.  You can straightforwardly switch to VTK's "default" color table without further modifying the input data file by clicking on (i.e., selecting) the "vtkPolyDataReader" module in the VisTrails pipeline, dragging the "SetLookupTableName" method into the "Set Methods" segment of the VisTrails Builder Window, typing the string "default" into the provided window, then reexecuting the pipeline.  (You can switch back to the user-provided color table by typing in the string "my_table", then reexecuting the pipeline.)
* You can also revert back to the tomato-colored cube (or whatever color is specified inside the "vtkProperty" module) by clicking on the "vtkPolyDataMapper" module in the VisTrails pipeline, dragging the "ScalarVisibilityOff" method into the "Set Methods" segment of the BisTrails Builder Window, then reexecuting the pipeline.

<font color="blue">Transparency:</font>
* The fourth floating-point number <math>~(\alpha)</math> that appears in each row of the color LOOKUP_TABLE allows you to assign a transparency (as well as a specific color) to each polygon that has the relevant scalar value.  Experiment with changing this number from 1.0 (opaque) to 0.0 (fully transparent, or any fractional value in between (partial transparency).

<font color="blue">Use vtkLookupTable Module:</font>
* You can construct a wide range of different color Lookup Tables by adding the "vtkLookupTable" module to the VisTrails pipeline.  In an [[vtk/ColorLookupTablea#Color_Lookup_Tables|accompanying presentation]], we explain and illustrate how this is done.

<font color="blue">Wireframe:</font>
* If, at any time, you want to render only the underlying ''wireframe'' structure of your three-dimensional configuration, simply activate the '"SetRepresentationToWireframe" method inside the "vtkProperty" module.

===Assigning NORMALS to POLYGONS===

[[Image:CubeDetails.png|right|thumb|250px|caption|Annotated Cube]] In [[vtk/SimpleCubeTutorial/CubeDetails#Cube_Definition_Details|an accompanying presentation]] (which includes a larger image of the ''Annotated Cube'' shown here, on the right), we explain how VTK's ''Simple Legacy Format'' reader identifies (and internally catalogs) the unit vector that points perpendicular to &#8212; and, hence, that defines the normal of &#8212; each POLYGON.  Here, after highlighting the key points of this [[vtk/SimpleCubeTutorial/CubeDetails#Cube_Definition_Details|more detailed presentation]], we illustrate how different definitions of the polygon NORMALS can be specified by inserting additional lines of data into the input data file.

<font color="blue">Default Assignment:</font>
* Take POLYGON "1" as an example, for which the defining line of input data is "4 4 5 6 7."  Adhering to the [http://en.wikipedia.org/wiki/Right-hand_rule right-hand rule], VTK understands that, as POINTS 4, 5, 6, &amp; 7 are connected ''in that order,'' the perimeter of the four-sided polygon is being traversed in a counter-clockwise direction.  Accordingly, by default, VTK records (internally) that the unit vector that is normal to POLYGON "1"  points in the <math>~(x,y,z) = (0,0,1)</math> direction.
* In the spirit of a tutorial, we recommend that the reader carefully examine the sets of integers that appear immediately following the heading "POLYGONS 6 30" in the above example input data file(s) and answer the following question:  In what default direction will VTK determine that the normal to each of the cube's other five POLYGONS points?  In other words, fill in the blank spaces in the following table.
<div align="center">
<table border="1" cellpadding="3">
<tr>
  <th align="center" rowspan="2">
POLYGON<br>Number
  </th>
  <th align="center" colspan="3">
Direction that unit normal points
  </th>
</tr>
<tr>
  <td align="center">
<math>~x</math>
  </td>
  <td align="center">
<math>~y</math>
  </td>
  <td align="center">
<math>~z</math>
  </td>
</tr>

<tr>
  <td align="center">
0
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
</tr>

<tr>
  <td align="center">
1
  </td>
  <td align="center">
0
  </td>
  <td align="center">
0
  </td>
  <td align="center">
+1
  </td>
</tr>

<tr>
  <td align="center">
2
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
</tr>

<tr>
  <td align="center">
3
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
</tr>

<tr>
  <td align="center">
4
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
</tr>

<tr>
  <td align="center">
5
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
  <td align="center">
&nbsp;
  </td>
</tr>
</table>
</div>

Continuing to adhere to the ''Simple Legacy Format'', the user can specify what unit vector ''normal'' gets assigned to each POLYGON.  If <math>~N_\mathrm{poly}</math> POLYGONS have been defined, then this can be accomplished by inserting an additional <math>~(N_\mathrm{poly} + 1)</math> lines of text to the input data file immediately after scalar values have been assigned to each POLYGON.  The top segment of each column of the following table presents an input data file that is identical to Example E, shown above, except 7 additional lines of text have been inserted, beginning with a header line of text that reads, "NORMALS cell_normals float."  Only the specified NORMALS change across these three examples, F, G, &amp; H; as before, the image of the cube that is rendered by VisTrails in each case is shown at the bottom of the respective table column.

<div align="center">
<table border="1">
<tr>
  <td align="center">
Example F
  </td>
  <td align="center">
Example G
  </td>
  <td align="center">
Example H
  </td>
</tr>
<tr>
  <td align="left">
<pre style="color:maroon;font-size:100%">
(same first 20 lines of text)
.
.
.

CELL_DATA 6
SCALARS cell_scalars float 1
LOOKUP_TABLE my_table
0.14286
0.28571
0.42857
0.57143
0.71429
0.85714
NORMALS cell_normals float
0 0 -1
0 0 1
0 -1 0
0 1 0
-1 0 0
1 0 0
LOOKUP_TABLE my_table 8
0.0 0.0 0.0 1.0
1.0 0.0 0.0 1.0
0.0 1.0 0.0 1.0
1.0 1.0 0.0 1.0
0.0 0.0 1.0 1.0
1.0 0.0 1.0 1.0
0.0 1.0 1.0 1.0
1.0 1.0 1.0 1.0
</pre>
  </td>
  <td align="left">
<pre style="color:maroon;font-size:100%">
(same first 20 lines of text)
.
.
.

CELL_DATA 6
SCALARS cell_scalars float 1
LOOKUP_TABLE my_table
0.14286
0.28571
0.42857
0.57143
0.71429
0.85714
NORMALS cell_normals float
0 0 1
0 0 1
0 -1 0
0 1 0
-1 0 0
1 0 0
LOOKUP_TABLE my_table 8
0.0 0.0 0.0 1.0
1.0 0.0 0.0 1.0
0.0 1.0 0.0 1.0
1.0 1.0 0.0 1.0
0.0 0.0 1.0 1.0
1.0 0.0 1.0 1.0
0.0 1.0 1.0 1.0
1.0 1.0 1.0 1.0
</pre>
  </td>
  <td align="left">
<pre style="color:maroon;font-size:100%">
(same first 20 lines of text)
.
.
.

CELL_DATA 6
SCALARS cell_scalars float 1
LOOKUP_TABLE my_table
0.14286
0.28571
0.42857
0.57143
0.71429
0.85714
NORMALS cell_normals float
0 0 1
0 0 -1
0 1 0
0 -1 0
1 0 0
-1 0 0
LOOKUP_TABLE my_table 8
0.0 0.0 0.0 1.0
1.0 0.0 0.0 1.0
0.0 1.0 0.0 1.0
1.0 1.0 0.0 1.0
0.0 0.0 1.0 1.0
1.0 0.0 1.0 1.0
0.0 1.0 1.0 1.0
1.0 1.0 1.0 1.0
</pre>
  </td>
</tr>
<tr>
  <th align="center" colspan="3">
Corresponding Rendering of Cube by VisTrails
  </th>
</tr>
<tr>
  <td align="center">
[[Image:Screenshot07.png|200px|Screenshot_F]]
  </td>
  <td align="center" valign="bottom">
[[Image:Screenshot08.png|200px|Screenshot_G]]
  </td>
  <td align="center">
[[Image:Screenshot09.png|200px|Screenshot_H]]
  </td>
</tr>
</table>
</div>

<font color="blue">'''General Explanation:''' </font>
* "NORMALS cell_normals float" means that the subsequent six lines of data should be assigned, in sequence, to each of the 6 polygonal (square) faces of the cube; the name "cell_normals" should be assigned to this set of data; and the VTK reader should expect the data to be provided as a set of space-delimited floating point numbers.
* Each line of data should contain three numbers to specify the orientation of the unit vector that is normal to the associated POLYGON.  In order to determine the unit vector's orientation, the VTK reader assumes that the base of the unit vector is located at the origin of the coordinate system and it will interpret the numbers as identifying the ''x, y, z'' coordinates of the other end &#8212; that is, the pointed tip &#8212; of the unit vector.  Hence <math>~(x,y,z) = (0,0,1)</math>, as has been specified for POLYGON "1" in Examples F &amp; G, means that the NORMAL vector assigned to POLYGON "1" points in the plus ''z'' direction.

<font color="blue">Example F:</font>
* The six lines of coordinate triplets that have been specified in this example contain precisely the same values as the simple "Cube example" that is presented in &sect;15.3 (see the top of p. 332) of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide''].  The rendered image is identical to the image that was rendered, above, in Example E &#8212; in which the NORMALS were not explicitly specified &#8212; except that POLYGON "0" is colored black instead of red.  (Spinning the cube around will show that the other five cube faces have the same colors as in Example E.)

<font color="blue">More Complete Understanding:</font>
(''Disclaimer'' &hellip;  Because I am not an expert in the design of VTK, I am not sure that the following statements are precisely correct.  But they give a pretty good idea of what is accomplished via the specification of NORMALS.)  
* Especially when a group of POLYGONS is assembled to construct the surface of a 3D structure, VTK needs to know which side of each POLYGON "faces out" and which side "faces in" before it can provide a proper visual rendering of the configuration.  
* Upon inspection, it is clear that the six sets of coordinate triplets that have been specified in Example F (copied directly from the simple "Cube example" in the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide'']) ''all'' define NORMALS that are pointing "out" of the cube.
* My initial assumption was that VTK routines would paint all of the "outward facing" sides of the POLYGONS the color corresponding to their scalar values, but that it may leave uncolored any sides that are "inward facing."  I was therefore surprised to discover that the VisTrails rendering that resulted from Example F has one uncolored side &#8212; in the rendered image, POLYGON "0" (''i.e.,'' the polygon lying in the ''x-y'' plane) is black instead of red.
* After carefully reanalyzing the information contained in the input data file I realized that, given the definitions of the six POLYGONS provided by the input data file (as copied from the simple "Cube example" in the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide'']), VTK's default assignment of unit vector normals should be as follows:
<div align="center">
<pre>
VTK's Default Assignment of Unit Vector Normals:
 0  0 +1
 0  0 +1
 0 -1  0
 0 +1  0
-1  0  0
+1  0  0
</pre>
</div>
* This is the set of six triplet values that should be entered into the above table to answer the tutorial quiz question:  ''In what default direction will VTK determine that the normal to each of the cube's other five POLYGONS points?''  It differs from the set of cell_normals that we have explicitly inserted into Example F, above, in one very important way:  The cell normal that has been assigned to POLYGON "0" in Example F is <math>~(x,y,z) = (0,0,-1)</math> whereas, given the order in which the POINTS are specified when POLYGON "0" is defined in the input data file (<font face="Courier">4 0 1 2 3</font>) and an adherence to the [http://en.wikipedia.org/wiki/Right-hand_rule right-hand rule], the default direction that would be assigned by VTK is <math>~(x,y,z) = (0,0,+1)</math>.  

<font color="red">'''Comment#3 (by J. E. Tohline):'''</font>  Initially, it wasn't obvious to me why POLYGON "0" was black.  Because all of the "cell_normals" NORMALS that are explicitly specified in the Example F input data file point "out," I expected all six faces of the cube to be colored as shown in Example E.  It took me a while to deduce that the default normal that VTK assigned to POLYGON "0" was <math>~(0,0,+1)</math> and pointed "into," rather than "out of," the cube.  POLYGON "0" was painted black because the explicitly specified NORMAL in Example F pointed in the opposite direction to this default normal.  In my opinion, this was an odd set of numbers for the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide''] to provide in order to illustrate how to specify NORMALS in the simple "Cube example."  

<font color="blue">Example G:</font>
* If I was correct in explaining why POLYGON "0" was rendered black in Example F, then it should be possible to return POLYGON "0" to a red color by doing one of two things:  (1) Flip the explicitly specified NORMAL to <math>~(0,0,+1)</math>, putting it in alignment with the normal's default specification; or (2) redefine POLYGON "0" by reversing the order in which its four POINTS are connected so that, according to the right-hand rule convention, the default normal would point "out of" rather than "into" the cube.  The first of these two adjustments was made in Example G.  Only one line of data in the Example G input file is different from the Example F input file:  the NORMAL specified for POLYGON "0" is <math>~(0,0,1)</math> instead of <math>~(0,0,-1)</math>.  As predicted, the VisTrails pipeline colored POLYGON "0" red instead of black.

<font color="blue">Example H:</font>
* Example H differs from Example F in that the direction of ''all six'' of the specified normals is reversed; that is, in Example H, all of the explicitly specified normals point "into" rather than "out of" the cube.  As expected, the resulting rendered image has one red side (POLYGON "0"), while the other five cell faces are black &#8212; indicating that, for each face, the explicitly specified NORMAL and the default normal point in opposite directions.