Editing Vtk/SimpleCubeTutorial (section)

==XML-Formatted Input==
===Overview===
As is explained in &sect;15.3 (see the bottom of p. 336) of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide,'' authored and published by Kitware, Inc.], VTK (and VisTrails) also supplies ''Readers'' that accept XML-formatted input data.  An example XML-formatted data file is shown immediately following this paragraph; it also can be obtained at the following website: 
<div align="center"> [http://www.phys.lsu.edu/~tohline/vistrails/datafiles/XMLformattedSimpleCube.vtp http://www.phys.lsu.edu/~tohline/vistrails/datafiles/XMLformattedSimpleCube.vtp]</div>  
The information provided in this 34-line ASCII file describes exactly the same "Simple Cube" model that was presented above in ''Simple Legacy Format'' as Example G.  It is also similar &#8212; but not identical &#8212; to the example XML-formatted data file presented on p. 346 of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide'']. 
<div align="left">
<pre>
<?xml version="1.0"?>
<VTKFile type="PolyData" version="0.1" byte_order="LittleEndian">
  <PolyData>
    <Piece NumberOfPoints="8" NumberOfPolys="6">
      <CellData Scalars="cell_scalars" Normals="cell_normals">
        <DataArray type="Float32" Name="cell_scalars" format="ascii">
          0.14286 0.28571 0.42857
          0.57143 0.71429 0.85714
        </DataArray>
        <DataArray type="Float32" Name="cell_normals" NumberOfComponents="3" format="ascii">
          0 0 1 0 0 1 0 -1 0 0 1 0 -1 0 0 1 0 0
        </DataArray>
      </CellData>
      <Points>
        <DataArray type="Float32" NumberOfComponents="3" format="ascii">
          0 0 0 1 0 0
          1 1 0 0 1 0
          0 0 1 1 0 1
          1 1 1 0 1 1
        </DataArray>
      </Points>
      <Polys>
        <DataArray type="Int32" Name="connectivity" format="ascii">
          0 1 2 3  4 5 6 7
          0 1 5 4  2 3 7 6
          0 4 7 3  1 2 6 5
        </DataArray>
        <DataArray type="Int32" Name="offsets" format="ascii">
          4 8 12 16 20 24
        </DataArray>
      </Polys>
    </Piece>
  </PolyData>
</VTKFile>
</pre>
</div>

<font color="blue">'''General Explanation:''' </font>
* The "Piece" of the "PolyData" being described in this file contains 8 points and 6 polygons (polys).   The substantive information is provided by "Data Arrays" located within three subsections of the file:  ''CellData,'' ''Points,'' and ''Polys.''
* Points:  This ''DataArray'' provides the same information as [[vtk/SimpleCubeTutorial/CubeDetails#Specifying_the_location_of_the_cube.27s_corners.2Fvertices|the ''POINTS'' subsection of a ''Simple Legacy Formatted'' data file]], that is, it specifies the <math>~(x, y, z)</math> coordinates of the eight points (vertices) of our simple cube.  The header of this ''DataArray'' tells the VTK Reader that it should read 3 numbers (the coordinates) at a time, and that the (space-delimited) data should be read as 32-bit floating-point numbers.  The Reader will expect this ''DataArray'' to contain <font face="Courier">(NumberOfPoints x NumberOfComponents =) 24</font> separate floating-point numbers.
* Polys:  In combination with one another, the two ''DataArrays'' found between the ''Polys'' metatags provide the same information as [[vtk/SimpleCubeTutorial/CubeDetails#Defining_the_cube.27s_six_quadrilateral_faces|the ''POLYGONS'' subsection of a ''Simple Legacy Formatted'' data file]].  The first ''DataArray,'' whose Name is "connectivity," identifies the group of POINTS that should be connected to define the complete perimeter of each face of the cube; the second ''DataArray,'' whose Name is "offsets," tells the Reader how many integers in the "connectivity" array should be skipped in order to begin defining each subsequent polygon.  In other words, the number of POINTS that define the perimeter of each polygon &#8212; in this case, 4 for every polygon &#8212; is given by the ''difference'' between successive ''offsets.''
* CellData:  The first ''DataArray,'' whose name is "cell_scalars," assigns a scalar value to each polygon, i.e., to each face of the cube; the Reader will expect this ''DataArray'' to contain <font face="Courier">(NumberOfPolys =) 6</font> separate 32-bit floating-point numbers.  The second ''DataArray,'' whose name is "cell_normals," specifies the <math>~(x, y, z)</math> coordinates of the tip of the unit vector that defines the NORMAL to the surface of each polygon, as [[vtk/SimpleCubeTutorial#Assigning_NORMALS_to_POLYGONS|explained in the discussion, above]]; the Reader will expect this ''DataArray'' to contain <font face="Courier">(NumberOfPolys x NumberOfComponents =) 18</font> separate 32-bit floating-point numbers.


[[Image:XMLreaderPipeline.png|right|thumb|250px|Pipeline02]]<font color="blue">'''XMLPolyDataReader:''' </font>
The figure labeled [[vtk/SimpleCubeTutorial#Reading_Cube_Model_from_a_Web_Site|"Pipeline01" near the top of this page]], shows the VisTrails pipeline that we used to construct and render a ''simple cube'' based on a web-accessible input file that provides data in a ''Simple Legacy Format.''  That input data was fed into the VisTrails pipeline using the ''vtkPolyDataReader'' module.  As is illustrated by the "Pipeline02" figure, shown here on the right, the equivalent XML-formatted data file &#8212; which, as noted immediately above, is accessible on the web as a file named ''XMLformattedSimpleCube.vtp'' &#8212; can be fed into the VisTrails pipeline using the ''vtkXMLPolyDataReader'' module.

<font color="blue">'''No Color Table:''' </font>
As far as I have been able to ascertain, XML-formatted data files cannot be used to define LOOKUP_TABLEs &#8212; that is, color tables.  Hence, as illustrated in the "Pipeline02" figure shown here on the right, a ''vtkLookupTable'' module must be inserted into the VisTrails pipeline if the user wants to define the color table.

===Comment Lines and Deleting XML Pieces===
Two major advantages of XML-formatted input data files is the ability to segment the data &#8212; and rendered elements of a scene &#8212; into separate ''Pieces'' and, then, the ability to "comment out" one or more of these pieces when you want to simplify the scene.  The following ASCII data file illustrates how the ''Simple Cube'' can be subdivided into a pair of 3-sided figures and how, by simply inserting or deleting a comment line, the two ''Pieces'' can be rendered together or separately. 

<div align="left">
<pre>
<?xml version="1.0"?>
<VTKFile type="PolyData" version="0.1" byte_order="LittleEndian" compressor="vtkZLibDataCompressor">
  <PolyData>
<!-- This is three of the sides of the cube -->
    <Piece NumberOfPoints="8" NumberOfPolys="3">
      <CellData Scalars="temperature" Normals="cell_normals">
        <DataArray type="Float32" Name="temperature" format="ascii">
          0.14286 0.28571 0.42857
        </DataArray>
        <DataArray type="Int32" Name="cell_normals" NumberOfComponents="3" format="ascii">
          0 0 1  0 0 1  0 -1 0
        </DataArray>
      </CellData>
      <Points>
        <DataArray type="Float32" NumberOfComponents="3" format="ascii">
          0 0 0 1 0 0
          1 1 0 0 1 0
          0 0 1 1 0 1
          1 1 1 0 1 1
        </DataArray>
      </Points>
      <Polys>
        <DataArray type="Int32" Name="connectivity" format="ascii">
          0 1 2 3   4 5 6 7   0 1 5 4
        </DataArray>
        <DataArray type="Int32" Name="offsets" format="ascii">
          4 8 12
        </DataArray>
      </Polys>
    </Piece>
<!-- This is the other three sides of the cube
    <Piece NumberOfPoints="8" NumberOfPolys="3">
      <CellData Scalars="temperature" Normals="cell_normals">
        <DataArray type="Float32" Name="temperature" format="ascii">
          0.57143 0.71429 0.85714
        </DataArray>
        <DataArray type="Int32" Name="cell_normals" NumberOfComponents="3" format="ascii">
          0 1 0  -1 0 0  1 0 0
        </DataArray>
      </CellData>
      <Points>
        <DataArray type="Float32" NumberOfComponents="3" format="ascii">
          0 0 0 1 0 0
          1 1 0 0 1 0
          0 0 1 1 0 1
          1 1 1 0 1 1
        </DataArray>
      </Points>
      <Polys>
        <DataArray type="Int32" Name="connectivity" format="ascii">
          2 3 7 6    0 4 7 3   1 2 6 5
        </DataArray>
        <DataArray type="Int32" Name="offsets" format="ascii">
          4 8 12
        </DataArray>
      </Polys>
    </Piece>
-->
  </PolyData>
</VTKFile>
</pre>
</div>

<font color="blue">'''General Explanation:''' </font>
* The fourth line of the above ASCII data file is a single, standard XML-formatted comment line &#8212; see the explanation provided, for example, on the [http://en.wikipedia.org/wiki/XML#Comments Wikipedia page that explains XML comment tags].  By XML convention, it begins with the string "<math>~< !--</math>" and ends with the string "<math>~--></math>".  The same beginning and ending strings also appear, respectively, as lines 31 and 58 in the data file.  In the first case, because the two strings appear on the same line of the file, they simply serve to encapsulate a short comment.  In the second case, all of the ASCII text that falls between lines 31 and 58 are considered part of the "comment" and therefore the second ''Piece'' of the cube is ignored by the ''XMLPolyDataReader''.  As presented here, this input data file will generate only three sides of the cube.  The entire cube will be rendered if line 58 is deleted and the string "<math>~--></math>" is added to the end of line 31.