Editing Vtk/SimpleCubeTutorial (section)

===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]].