Editing Vtk/SimpleCubeTutorial (section)

==Minimalistic Cube==
In the above example, the vertices and polygons that were used to describe the underlying wireframe model of the cylinder were defined inside the "vtkCylinderSource" method in a manner that is hidden from the user.  (Although, see [[vtk/Understanding#Understanding_vtk_Tools_Inside_VisTrails|our more detailed accompanying discussion]].)  Similarly, the VisTrails library contains methods that can be used to draw a cube (vtkCubeSource), a sphere (vtkSphereSource), or a Cone (vtkConeSource).  (As further practice, you may want to insert these other standard building block models into the VisTrails pipeline in place of, or in addition to, the CylinderSource.)  In general, however, a user of VisTrails will want to supply her/his own data model.  Here, we use the structure of a simple cube to illustrate one straightforward method of providing model data in the ''Simple Legacy Format'', which VisTrails &#8212; and, more generally, all of the vtk library modules &#8212; will understand.

===Reading Cube Model from a Web Site===
1.  Start from scratch:  Generate the "tomato-colored" cylinder depicted in Figure "Cylinder01" by following the first two steps of the "Getting Started" example presented above.

[[Image:ModifiedPipeline.jpg|right|thumb|250px|Pipeline01]]2.  Disconnect the "vtkCylinderSource" module from the pipeline, then add (and connect) the following two modules to the pipeline:  "HTTPFile" and "vtkPolyDataReader".  This is done by finding the names of these modules in the library list shown in the "Modules" segment of the VisTrails Builder Window, then highlighting, and dragging and dropping the modules into VisTrail's Pipeline widget.  After doing this, the VisTrails pipeline should look like the one depicted here as Figure "Pipeline01".  (If desired, the "vtkCylinderSource" module can actually be deleted from the Builder Window.)

3.  Go to the following website:  
<div align="center">
[http://www.phys.lsu.edu/~tohline/vistrails/datafiles/SimpleCube_step01.vtk http://www.phys.lsu.edu/~tohline/vistrails/datafiles/SimpleCube_step01.vtk]
</div>
The information provided in this 20-line ASCII file &#8212; also displayed in the left-hand panel of the "Minimalistic Cube" figure, below &#8212; supplies the POINTS (vertices) and POLYGONS that are sufficient to define the wireframe model of a simple cube.  The information in this file is identical to the first 20 lines of the example cube description shown in &sect;15.3 (specifically, starting at the bottom of p. 331) of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide''].

4.  Click on the "HTTPFile" module in the newly modified pipeline; drag the "url" method into the "Set Methods" segment of the VisTrails Builder Window; then, type (or cut and paste) into the blank window allocated for the url "String," the full "SimpleCube_step01" web address, including the "http://" prefix, as identified in step #3 above.

5.  Executing this modified pipeline should generate the tomato-colored cube as shown here in the right-hand panel of the "Minimalistic Cube" figure.

<div align="center">
<table border="1">
<tr>
  <td align="center" colspan="2">
'''Minimalistic Cube: ASCII File &amp; Rendered Image'''
  </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
</pre>
  </td>
  <td align="center">
[[Image:MinimalisticCube.jpg|center|thumb|250px|Minimalistic Cube]]
  </td>
</tr>
<tr>
  <td align="left" colspan="2">
The sets of numbers used to define the POINTS &amp; POLYGONS of this simple cube are [[vtk/SimpleCubeTutorial/CubeDetails|explained here]].
  </td>
</tr>
</table>
</div>

6.  In an [[vtk/SimpleCubeTutorial/CubeDetails|accompanying discussion]], we explain how to interpret &#8212; and, therefore, also how to modify as desired &#8212; the rows and columns of numbers that have been used here to define the POINTS (vertices) and POLYGONS of a simple cube.

7.  For fun, use VisTrails' "HTTPFile" module to load each of the following files that provide ASCII data written in VTK's Simple Legacy Format to specify a more intricate multi-polygonal structure.  I found these posted on [http://people.sc.fsu.edu/~jburkardt/data/vtk/vtk.html J. Burkardt's FSU website]:
* [http://people.sc.fsu.edu/~jburkardt/data/vtk/polyex.vtk Simple Cube]
* [http://people.sc.fsu.edu/~jburkardt/data/vtk/vtk.vtk vtk.vtk] = (Simple lines spelling out "vtk")
* [http://people.sc.fsu.edu/~jburkardt/data/vtk/t.vtk v.vtk] = (A 3D version of the letter "v")
* [http://people.sc.fsu.edu/~jburkardt/data/vtk/t.vtk t.vtk] = (A 3D version of the letter "t")
* [http://people.sc.fsu.edu/~jburkardt/data/vtk/k.vtk k.vtk] = (A 3D version of the letter "k")

===Reading Cube Model from a Local File===
You will be afforded a much greater degree of design flexibility if, rather than asking VisTrails to download the file from a web site, you create a local file (on the same computer that you are using to run VisTrails) that contains the POINTS and POLYGONS defining the cube and instruct VisTrails to read the information from that local file.  Initially, the file need only contain the 20 lines of ASCII text that are displayed in the left-hand panel of the above "Minimalistic Cube" figure.  

1.  Create a new file on your computer and either (a) type the 20 lines of ASCII text into the file by hand, or (b) copy the ASCII text from the "SimpleCube_Step01.vtk" file provided at the above-referenced web site and paste that information into your new file.  
* Be very careful doing this because the "vtkPolyDataReader" module in VisTrails is very picky.  In order to guarantee success, the file should be formatted in precisely the manner used here, that is, using the ''Simple Legacy Format'' described in &sect;15.3 (pp. 324-336) of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide''].  
* For the purposes of this tutorial exercise, when you save the file, name it <font color="darkgreen">''TestCube01.txt''</font>; to comply with the ''Simple Legacy Format'' standards, be sure to save it as a "text only" file.

2.  Point the "vtkPolyDataReader" module to this new file:
* Disconnect (and, if desired, delete) the "HTTPFile" module from the VisTrails pipeline.
* Click on (''i.e.'', highlight) the "vtkPolyDataReader" module in the pipeline, then drag the "SetFile" method into the "Set Methods" segment of the VisTrails Builder Window.
* A small folder icon will appear immediately to the right of the newly created "File" text window; click on this icon, then march through your computer's file folders to find your newly created <font color="darkgreen">''TestCube01.txt''</font> file.

3.  Executing this modified pipeline should, once again, generate the tomato-colored cube as shown in the right-hand panel of the above "Minimalistic Cube" figure.

<div align="center">
<table border="1" cellpadding="8" width="95%">
<tr>
  <td align="left">
<font color="red">'''CAUTION (from J. E. Tohline):'''</font> This simple step caused me considerable grief when I was first trying to understand how to enlist VisTrails in my research activities.  I already understood how to numerically define the vertices and polygons of a desired wireframe model for, say, a three-dimensional isodensity contour of one of my group's astrophysical fluid flow simulations.  But I had difficulty figuring out how to write that information to a file in a format that VisTrails could understand.  

In an effort to minimize typing mistakes, I searched for a web site from which I could copy-and-paste the entire "Cube example" provided on pp. 331-332 of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide''].  I discovered that the entire "VTK File Formats" discussion from the VTK User's Guide was posted on a [http://www.cacr.caltech.edu/~slombey/asci/vtk/vtk_formats.simple.html Caltech website], but my copy-and-paste operation introduced quite a few additional white spaces &#8212; and deleted others &#8212; at locations within the text file that violated rules established within the context of the ''Simple Legacy Format.''  As a result, the "vtkPolyDataReader" module misinterpreted the information and, as a consequence, the VisTrails pipeline failed to generate an image.  This was difficult to debug because I had no idea whether the data file was corrupted or whether I had screwed up the design of the VisTrails pipeline.

If you are able to successfully generate the tomato-colored cube by using the "HTTPFile" module to download the "SimpleCube_step01.vtk" file from the above-referenced web site but you are not immediately able to generate the same tomato-colored cube by calling upon the "vtkPolyDataReader" module to directly access your newly created text file, it is very likely that your file does not strictly conform to the ''Simple Legacy Format''.  Check to make sure that the file you have created does not have hidden formatting instructions, such as unwanted forced line feeds.
  </td>
</tr>
</table>
</div>

4.  After you have successfully generated the tomato-colored cube by reading the cube model in from a local file, you should change the extension of the file name from ".txt" to ".vtk".  This should be done because (see the opening paragraph of the "Dataset Format" discussion on p. 326 of the [http://www.kitware.com/products/books/vtkguide.html ''VTK User's Guide'']), by convention VTK files written in ''Simple Legacy Format'' use the .vtk file extension regardless of the dataset type contained in the file.  After making this change, repeat steps #2 and #3 to make sure you can still generate the minimalistic cube.