Difference between revisions of "User:Tohline/vtk/SimpleCubeTutorial/CubeDetails"

From VistrailsWiki
Jump to navigation Jump to search
(→‎Cube Definition Details: Explain the contents of the input data file)
Line 6: Line 6:


<div align="center">
<div align="center">
<table border="1">
<table border="1" cellpadding="5">
<tr>
<tr>
   <th align="center" colspan="1">
   <th align="center" colspan="2">
Defining the POINTS (vertices) &amp; POLYGONS of a cube in ''Simple Legacy Format''
Defining the POINTS (vertices) &amp; POLYGONS of a cube in ''Simple Legacy Format''
   </th>
   </th>
</tr>
</tr>
<tr>
<tr>
   <td align="center">
   <td align="center" colspan="2">
[[Image:CubeDetails.png|700px|Cube Details]]
[[Image:CubeDetails.png|700px|Cube Details]]
   </td>
   </td>
Line 20: Line 20:
   <td align="left">
   <td align="left">
<pre style="color:maroon;font-size:100%">
<pre style="color:maroon;font-size:100%">
# vtk DataFile Version 2.0  
# vtk DataFile Version 2.0
Cube example  
Cube example  
ASCII  
ASCII  
DATASET POLYDATA  
DATASET POLYDATA  
POINTS 8 float  
POINTS 8 float  
0.0 0.0 0.0  <== (x,y,z) coordinates of POINT "0"
0.0 0.0 0.0
1.0 0.0 0.0  <== ... of POINT "1"
1.0 0.0 0.0
1.0 1.0 0.0  <== ... of POINT "2"  
1.0 1.0 0.0 
0.0 1.0 0.0  <== ... of POINT "3"  
0.0 1.0 0.0
0.0 0.0 1.0  <== ... of POINT "4"  
0.0 0.0 1.0
1.0 0.0 1.0  <== ... of POINT "5"
1.0 0.0 1.0
1.0 1.0 1.0  <== ... of POINT "6"
1.0 1.0 1.0
0.0 1.0 1.0  <== ... of POINT "7"
0.0 1.0 1.0
POLYGONS 6 30  <== (see explanation in the accompanying text)
POLYGONS 6 30
4 0 1 2 3  <== POLYGON "0": A four-sided polygon formed by connecting POINTS 0, 1, 2, & 3, in that order.
4 0 1 2 3
4 4 5 6 7  <== POLYGON "1": A four-sided polygon formed by connecting POINTS 4, 5, 6, & 7, in that order.
4 4 5 6 7
4 0 1 5 4  <== POLYGON "2": A four-sided polygon ... POINTS 0, 1, 5, & 4, in that order.
4 0 1 5 4
4 2 3 7 6  <== POLYGON "3": A four-sided polygon ... POINTS 2, 3, 7, & 6, in that order.
4 2 3 7 6
4 0 4 7 3  <== POLYGON "4": A four-sided polygon ... POINTS 0, 4, 7, & 3, in that order.
4 0 4 7 3
4 1 2 6 5  <== POLYGON "5": A four-sided polygon ... POINTS 1, 2, 6, & 5, in that order.
4 1 2 6 5
</pre>
  </td>
   <td align="left">
<pre style="color:maroon;font-size:100%">
 
<== (x,y,z) coordinates of POINT "0"
<== ... of POINT "1"
<== ... of POINT "2"  
<== ... of POINT "3"  
<== ... of POINT "4"  
<== ... of POINT "5"
<== ... of POINT "6"
<== ... of POINT "7"
<== (see explanation in the accompanying text)
<== POLYGON "0": A four-sided polygon formed by connecting POINTS 0, 1, 2, & 3, in that order.
<== POLYGON "1": A four-sided polygon formed by connecting POINTS 4, 5, 6, & 7, in that order.
<== POLYGON "2": A four-sided polygon ... POINTS 0, 1, 5, & 4, in that order.
<== POLYGON "3": A four-sided polygon ... POINTS 2, 3, 7, & 6, in that order.
<== POLYGON "4": A four-sided polygon ... POINTS 0, 4, 7, & 3, in that order.
<== POLYGON "5": A four-sided polygon ... POINTS 1, 2, 6, & 5, in that order.
</pre>
</pre>
  </td>
</tr>
<tr>
  <td align="center">
Input Data File in<br>
''Simple Legacy Format''
  </td>
  <td align="center">
Annotation to aid in interpretation of individual lines of text/data from the input data file.
   </td>
   </td>
</tr>
</tr>
Line 46: Line 79:
</div>
</div>


This is how to interpret the lines of data, presented above, that are intended to define a simple cube.  Start with the appreciation that a cube has 8 corners (vertices or "POINTS") and six faces.  Each face of the cube is a four-sided polygon which, itself, can be defined by properly "connecting" subsets of the 8 POINTS.   
The lines of data presented on the left in the caption to the above figure are sufficient to define a simple cube.  In order to interpret the meaning of each line, start with the appreciation that a cube has 8 corners (also referred to as vertices or "POINTS") and six faces.  Each face of the cube is a four-sided polygon which, itself, can be defined by properly connecting subsets of the 8 POINTS.   
* When any of the "readers" within the visualization toolkit (VTK) library sees a line of text that reads "DATASET POLYDATA," it expects that the subsequent sequence of lines of text/data will define all of the POINTS and POLYGONS that are needed to graphically build the desired object &#8212; in this case, a cube.
* When a ''Simple Legacy Format'' "reader" within the visualization toolkit (VTK) library sees a line of text that reads "DATASET POLYDATA," it expects that the subsequent sequence of lines of text/data will define all of the POINTS and POLYGONS that are needed to graphically build the desired object &#8212; in this case, a cube.
Specifying the location of the cube's corners/vertices:
* The line of text that reads "POINTS 8 float" means that the subsequent 8 lines will, in sequence, provide the <math>~(x,y,z)</math> coordinates of the 8 corners of the cube; for each POINT the coordinate values will be provided as a triplet set of floating point numbers.  As VTK reads in each triplet set of coordinates, it will (internally) assign a number to the POINT, starting with the number zero and incrementing by one so that, for example, the eighth point will be referenced as POINT "7".
* The line of text that reads "POINTS 8 float" means that the subsequent 8 lines will, in sequence, provide the <math>~(x,y,z)</math> coordinates of the 8 corners of the cube; for each POINT the coordinate values will be provided as a triplet set of floating point numbers.  As VTK reads in each triplet set of coordinates, it will (internally) assign a number to the POINT, starting with the number zero and incrementing by one so that, for example, the eighth point will be referenced as POINT "7".
* On the color image of the cube, shown here above the input data file, each corner of the cube is numbered, following this
* On the rendered color image of the cube, shown above, we have labeled each corner of the cube with the number that it will be assigned (internally by VTK), given the order in which the POINT's coordinates appear in the data file. For example, the first coordinate triplet <math>~(x,y,z) = (0,0,0)</math> (''i.e.,'' the origin in Cartesian coordinates) is understood to be POINT "0," and the corner of the cube that is farthest from the origin with <math>~(x,y,z) = (1,1,1)</math> is understood to be POINT "6."
 
* It really doesn't matter in what order the POINTS appear in the data file &#8212; for example, the origin could have been the eighth coordinate triplet entry, in which case the origin would be labeled POINT "7."
The following 30 (= 6 x 5) integers will define 6 polygons; 5 integers are needed for each polygon.
Defining the cube's six quadrilateral faces:
* The line of text that reads "POLYGONS 6 30" means that the subsequent 6 lines will, in sequence, identify the group of POINTS that should be connected to define the complete perimeter of each face of the cube.  For example, POINTS 0, 1, 2, &amp; 3 should be connected in order to create the cube face that lies in the ''x-y'' plane &#8212; shown in the above image as the bottom of the cube.
* Each line of POLYGON-defining data must begin with an integer that tells the VTK reader how many ''additional'' integer numbers will appear on that line in order to define the desired polygon.  In the case being illustrated here, each of the 6 cube faces is being specified as a quadrilateral, so the first integer that appears in all six lines of POLYGON-defining data is "4."
* In total, the VTK reader must read in six lines of data with five integer numbers per line, for a total of <math>~6\times 5 = 30</math> integers, in order to completely understand how the cube is to be drawn.  This is why the integer "30" appears in the instructional heading, "POLYGONS 6 30."
Identifying the normal of each cube face:
* It is important to appreciate that, when identifying the POINTS that will define any individual POLYGON, the ''order in which the POINTS are identified matters.''  VTK will draw the perimeter of the polygon by connecting the points ''in the specified order.''  For example, the top face of the cube, as illustrated above, has been properly drawn because the line of data defining that quadrilateral reads "4 4 5 6 7"; VTK understands that the perimeter of that desired polygon will be traversed by connecting POINT 4 to POINT 5 to POINT 6 to POINT 7, then ''back to POINT 4.''  We could have achieved the desired result, just as well, by providing a line of data that reads "4 6 7 4 5," but the proper polygon would not have been drawn if the line of data read "4 5 7 6 4."
* VTK uses the "right-hand rule" when assigning a NORMAL to each polygon.

Revision as of 17:20, 18 March 2014

Cube Definition Details

Whitworth's (1981) Isothermal Free-Energy Surface
|   Tiled Menu   |   Tables of Content   |  Banner Video   |  Tohline Home Page   |

A model of virtually any three-dimensional structure can be fed into VisTrails — and understood by the accompanying visualization toolkit (vtk) library of routines — using VTK's Simple Legacy Format. Here we explain how the set of vertices (POINTS) and POLYGONS of a simple cube can be defined using this Simple Legacy Format; this explanation is primarily intended to provide supplemental details for our accompanying Simple Cube Tutorial.


Defining the POINTS (vertices) & POLYGONS of a cube in Simple Legacy Format

Cube Details

# 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
 
 

 
 
<== (x,y,z) coordinates of POINT "0"
<== ... of POINT "1"
<== ... of POINT "2" 
<== ... of POINT "3" 
<== ... of POINT "4" 
<== ... of POINT "5"
<== ... of POINT "6"
<== ... of POINT "7"
<== (see explanation in the accompanying text)
<== POLYGON "0": A four-sided polygon formed by connecting POINTS 0, 1, 2, & 3, in that order.
<== POLYGON "1": A four-sided polygon formed by connecting POINTS 4, 5, 6, & 7, in that order.
<== POLYGON "2": A four-sided polygon ... POINTS 0, 1, 5, & 4, in that order.
<== POLYGON "3": A four-sided polygon ... POINTS 2, 3, 7, & 6, in that order.
<== POLYGON "4": A four-sided polygon ... POINTS 0, 4, 7, & 3, in that order.
<== POLYGON "5": A four-sided polygon ... POINTS 1, 2, 6, & 5, in that order.

Input Data File in
Simple Legacy Format

Annotation to aid in interpretation of individual lines of text/data from the input data file.

The lines of data presented on the left in the caption to the above figure are sufficient to define a simple cube. In order to interpret the meaning of each line, start with the appreciation that a cube has 8 corners (also referred to as vertices or "POINTS") and six faces. Each face of the cube is a four-sided polygon which, itself, can be defined by properly connecting subsets of the 8 POINTS.

  • When a Simple Legacy Format "reader" within the visualization toolkit (VTK) library sees a line of text that reads "DATASET POLYDATA," it expects that the subsequent sequence of lines of text/data will define all of the POINTS and POLYGONS that are needed to graphically build the desired object — in this case, a cube.

Specifying the location of the cube's corners/vertices:

  • The line of text that reads "POINTS 8 float" means that the subsequent 8 lines will, in sequence, provide the <math>~(x,y,z)</math> coordinates of the 8 corners of the cube; for each POINT the coordinate values will be provided as a triplet set of floating point numbers. As VTK reads in each triplet set of coordinates, it will (internally) assign a number to the POINT, starting with the number zero and incrementing by one so that, for example, the eighth point will be referenced as POINT "7".
  • On the rendered color image of the cube, shown above, we have labeled each corner of the cube with the number that it will be assigned (internally by VTK), given the order in which the POINT's coordinates appear in the data file. For example, the first coordinate triplet <math>~(x,y,z) = (0,0,0)</math> (i.e., the origin in Cartesian coordinates) is understood to be POINT "0," and the corner of the cube that is farthest from the origin with <math>~(x,y,z) = (1,1,1)</math> is understood to be POINT "6."
  • It really doesn't matter in what order the POINTS appear in the data file — for example, the origin could have been the eighth coordinate triplet entry, in which case the origin would be labeled POINT "7."

Defining the cube's six quadrilateral faces:

  • The line of text that reads "POLYGONS 6 30" means that the subsequent 6 lines will, in sequence, identify the group of POINTS that should be connected to define the complete perimeter of each face of the cube. For example, POINTS 0, 1, 2, & 3 should be connected in order to create the cube face that lies in the x-y plane — shown in the above image as the bottom of the cube.
  • Each line of POLYGON-defining data must begin with an integer that tells the VTK reader how many additional integer numbers will appear on that line in order to define the desired polygon. In the case being illustrated here, each of the 6 cube faces is being specified as a quadrilateral, so the first integer that appears in all six lines of POLYGON-defining data is "4."
  • In total, the VTK reader must read in six lines of data with five integer numbers per line, for a total of <math>~6\times 5 = 30</math> integers, in order to completely understand how the cube is to be drawn. This is why the integer "30" appears in the instructional heading, "POLYGONS 6 30."

Identifying the normal of each cube face:

  • It is important to appreciate that, when identifying the POINTS that will define any individual POLYGON, the order in which the POINTS are identified matters. VTK will draw the perimeter of the polygon by connecting the points in the specified order. For example, the top face of the cube, as illustrated above, has been properly drawn because the line of data defining that quadrilateral reads "4 4 5 6 7"; VTK understands that the perimeter of that desired polygon will be traversed by connecting POINT 4 to POINT 5 to POINT 6 to POINT 7, then back to POINT 4. We could have achieved the desired result, just as well, by providing a line of data that reads "4 6 7 4 5," but the proper polygon would not have been drawn if the line of data read "4 5 7 6 4."
  • VTK uses the "right-hand rule" when assigning a NORMAL to each polygon.