Editing Vtk/SimpleCubeTutorial (section)

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