
 Usage

This class is used to generate unique triangulations of
points. The uniqueness of the triangulation is controlled by
the id of the inserted points in combination with a Delaunay
criterion. The class is designed to be as fast as possible
(since the algorithm can be slow) and uses block memory
allocations to support rapid triangulation generation. Also,
the assumption behind the class is that a maximum of
hundreds of points are to be triangulated. If you desire
more robust triangulation methods use vtkPolygon::
Triangulate(), vtkDelaunay2D, or vtkDelaunay3D.
.SECTION Background This work is documented in the technical
paper: W.J. Schroeder, B. Geveci, M. Malaterre. Compatible
Triangulations of Spatial Decompositions. In Proceedings of
Visualization 2004, IEEE Press October 2004.
Delaunay triangulations are unique assuming a random
distribution of input points. The 3D Delaunay criterion is
as follows: the circumsphere of each tetrahedron contains no
other points of the triangulation except for the four points
defining the tetrahedron. In application this property is
hard to satisfy because objects like cubes are defined by
eight points all sharing the same circumsphere (center and
radius); hence the Delaunay triangulation is not unique.
These so-called degenerate situations are typically resolved
by arbitrary selecting a triangulation. This code does
something different: it resolves degenerate triangulations
by modifying the "InCircumsphere" method to use a slightly
smaller radius. Hence, degenerate points are always
considered "out" of the circumsphere. This, in combination
with an ordering (based on id) of the input points,
guarantees a unique triangulation.
There is another related characteristic of Delaunay
triangulations. Given a N-dimensional Delaunay
triangulation, points lying on a (N-1) dimensional plane
also form a (N-1) Delaunay triangulation. This means for
example, that if a 3D cell is defined by a set of (2D)
planar faces, then the face triangulations are Delaunay.
Combining this with the method to generate unique
triangulations described previously, the triangulations on
the face are guaranteed unique. This fact can be used to
triangulate 3D objects in such a way to guarantee compatible
face triangulations. This is a very useful fact for parallel
processing, or performing operations like clipping that
require compatible triangulations across 3D cell faces. (See
vtkClipVolume for an example.)
A special feature of this class is that it can generate
triangulation templates on the fly. If template
triangulation is enabled, then the ordered triangulator will
first triangulate the cell using the slower ordered Delaunay
approach, and then store the result as a template. Later, if
the same cell type and cell configuration is encountered,
then the template is reused which greatly speeds the
triangulation.
To create an instance of class vtkOrderedTriangulator,
simply invoke its constructor as follows

    obj = vtkOrderedTriangulator



 Methods

The class vtkOrderedTriangulator has several methods that
can be used. They are listed below. Note that the
documentation is translated automatically from the VTK
sources, and may not be completely intelligible. When in
doubt, consult the VTK website. In the methods listed below,
obj is an instance of the vtkOrderedTriangulator class.

* string = obj.GetClassName ()
* int = obj.IsA (string name)
* vtkOrderedTriangulator = obj.NewInstance ()
* vtkOrderedTriangulator = obj.SafeDownCast (vtkObject o)
* obj.InitTriangulation (double xmin, double xmax, double
  ymin, double ymax, double zmin, double zmax, int numPts) -
  Initialize the triangulation process. Provide a bounding
  box and the maximum number of points to be inserted. Note
  that since the triangulation is performed using parametric
  coordinates (see InsertPoint()) the bounds should be
  represent the range of the parametric coordinates
  inserted.


    Postcondition:
        no_point_inserted: GetNumberOfPoints()==0

* obj.InitTriangulation (double bounds[6], int numPts) -
  Initialize the triangulation process. Provide a bounding
  box and the maximum number of points to be inserted. Note
  that since the triangulation is performed using parametric
  coordinates (see InsertPoint()) the bounds should be
  represent the range of the parametric coordinates
  inserted.


    Postcondition:
        no_point_inserted: GetNumberOfPoints()==0

* vtkIdType = obj.InsertPoint (vtkIdType id, double x[3],
  double p[3], int type) - For each point to be inserted,
  provide an id, a position x, parametric coordinate p, and
  whether the point is inside (type=0), outside (type=1), or
  on the boundary (type=2). You must call InitTriangulation
  () prior to invoking this method. Make sure that the
  number of points inserted does not exceed the numPts
  specified in InitTriangulation(). Also note that the "id"
  can be any integer and can be greater than numPts. It is
  used to create tetras (in AddTetras()) with the
  appropriate connectivity ids. The method returns an
  internal id that can be used prior to the Triangulate()
  method to update the type of the point with
  UpdatePointType(). (Note: the algorithm triangulated with
  the parametric coordinate p[3] and creates tetras with the
  global coordinate x[3]. The parametric coordinates and
  global coordinates may be the same.)
* vtkIdType = obj.InsertPoint (vtkIdType id, vtkIdType
  sortid, double x[3], double p[3], int type) - For each
  point to be inserted, provide an id, a position x,
  parametric coordinate p, and whether the point is inside
  (type=0), outside (type=1), or on the boundary (type=2).
  You must call InitTriangulation() prior to invoking this
  method. Make sure that the number of points inserted does
  not exceed the numPts specified in InitTriangulation().
  Also note that the "id" can be any integer and can be
  greater than numPts. It is used to create tetras (in
  AddTetras()) with the appropriate connectivity ids. The
  method returns an internal id that can be used prior to
  the Triangulate() method to update the type of the point
  with UpdatePointType(). (Note: the algorithm triangulated
  with the parametric coordinate p[3] and creates tetras
  with the global coordinate x[3]. The parametric
  coordinates and global coordinates may be the same.)
* vtkIdType = obj.InsertPoint (vtkIdType id, vtkIdType
  sortid, vtkIdType sortid2, double x[3], double p[3], int
  type) - For each point to be inserted, provide an id, a
  position x, parametric coordinate p, and whether the point
  is inside (type=0), outside (type=1), or on the boundary
  (type=2). You must call InitTriangulation() prior to
  invoking this method. Make sure that the number of points
  inserted does not exceed the numPts specified in
  InitTriangulation(). Also note that the "id" can be any
  integer and can be greater than numPts. It is used to
  create tetras (in AddTetras()) with the appropriate
  connectivity ids. The method returns an internal id that
  can be used prior to the Triangulate() method to update
  the type of the point with UpdatePointType(). (Note: the
  algorithm triangulated with the parametric coordinate p[3]
  and creates tetras with the global coordinate x[3]. The
  parametric coordinates and global coordinates may be the
  same.)
* obj.Triangulate () - Perform the triangulation. (Complete
  all calls to InsertPoint() prior to invoking this method.)
  A special version is available when templates should be
  used.
* obj.TemplateTriangulate (int cellType, int numPts, int
  numEdges) - Perform the triangulation. (Complete all calls
  to InsertPoint() prior to invoking this method.) A special
  version is available when templates should be used.
* obj.UpdatePointType (vtkIdType internalId, int type) -
  Update the point type. This is useful when the merging of
  nearly coincident points is performed. The id is the
  internal id returned from InsertPoint(). The method should
  be invoked prior to the Triangulate method. The type is
  specified as inside (type=0), outside (type=1), or on the
  boundary (type=2).


    Precondition:
        valid_range: internalId>=0 &amp;&amp;
        internalId<this->GetNumberOfPoints()

* vtkIdType = obj.GetPointId (vtkIdType internalId) - Return
  the Id of point `internalId'. This id is the one passed in
  argument of InsertPoint. It assumes that the point has
  already been inserted. The method should be invoked prior
  to the Triangulate method.


    Precondition:
        valid_range: internalId>=0 &amp;&amp;
        internalId<this->GetNumberOfPoints()

* int = obj.GetNumberOfPoints () - Return the number of
  inserted points.
* obj.SetUseTemplates (int ) - If this flag is set, then the
  ordered triangulator will create and use templates for the
  triangulation. To use templates, the TemplateTriangulate()
  method should be called when appropriate. (Note: the
  TemplateTriangulate() method works for complete (interior)
  cells without extra points due to intersection, etc.)
* int = obj.GetUseTemplates () - If this flag is set, then
  the ordered triangulator will create and use templates for
  the triangulation. To use templates, the
  TemplateTriangulate() method should be called when
  appropriate. (Note: the TemplateTriangulate() method works
  for complete (interior) cells without extra points due to
  intersection, etc.)
* obj.UseTemplatesOn () - If this flag is set, then the
  ordered triangulator will create and use templates for the
  triangulation. To use templates, the TemplateTriangulate()
  method should be called when appropriate. (Note: the
  TemplateTriangulate() method works for complete (interior)
  cells without extra points due to intersection, etc.)
* obj.UseTemplatesOff () - If this flag is set, then the
  ordered triangulator will create and use templates for the
  triangulation. To use templates, the TemplateTriangulate()
  method should be called when appropriate. (Note: the
  TemplateTriangulate() method works for complete (interior)
  cells without extra points due to intersection, etc.)
* obj.SetPreSorted (int ) - Boolean indicates whether the
  points have been pre-sorted. If pre-sorted is enabled, the
  points are not sorted on point id. By default, presorted
  is off. (The point id is defined in InsertPoint().)
* int = obj.GetPreSorted () - Boolean indicates whether the
  points have been pre-sorted. If pre-sorted is enabled, the
  points are not sorted on point id. By default, presorted
  is off. (The point id is defined in InsertPoint().)
* obj.PreSortedOn () - Boolean indicates whether the points
  have been pre-sorted. If pre-sorted is enabled, the points
  are not sorted on point id. By default, presorted is off.
  (The point id is defined in InsertPoint().)
* obj.PreSortedOff () - Boolean indicates whether the points
  have been pre-sorted. If pre-sorted is enabled, the points
  are not sorted on point id. By default, presorted is off.
  (The point id is defined in InsertPoint().)
* obj.SetUseTwoSortIds (int ) - Tells the triangulator that
  a second sort id is provided for each point and should
  also be considered when sorting.
* int = obj.GetUseTwoSortIds () - Tells the triangulator
  that a second sort id is provided for each point and
  should also be considered when sorting.
* obj.UseTwoSortIdsOn () - Tells the triangulator that a
  second sort id is provided for each point and should also
  be considered when sorting.
* obj.UseTwoSortIdsOff () - Tells the triangulator that a
  second sort id is provided for each point and should also
  be considered when sorting.
* vtkIdType = obj.GetTetras (int classification,
  vtkUnstructuredGrid ugrid) - Initialize and add the tetras
  and points from the triangulation to the unstructured grid
  provided. New points are created and the mesh is
  allocated. (This method differs from AddTetras() in that
  it inserts points and cells; AddTetras only adds the tetra
  cells.) The tetrahdera added are of the type specified
  (0=inside,1=outside,2=all). Inside tetrahedron are those
  whose points are classified "inside" or on the "boundary."
  Outside tetrahedron have at least one point classified
  "outside." The method returns the number of
  tetrahedrahedron of the type requested.
* vtkIdType = obj.AddTetras (int classification,
  vtkUnstructuredGrid ugrid) - Add the tetras to the
  unstructured grid provided. The unstructured grid is
  assumed to have been initialized (with Allocate()) and
  points set (with SetPoints()). The tetrahdera added are of
  the type specified (0=inside,1=outside,2=all). Inside
  tetrahedron are those whose points are classified "inside"
  or on the "boundary." Outside tetrahedron have at least
  one point classified "outside." The method returns the
  number of tetrahedrahedron of the type requested.
* vtkIdType = obj.AddTetras (int classification,
  vtkCellArray connectivity) - Add the tetrahedra classified
  (0=inside,1=outside) to the connectivity list provided.
  Inside tetrahedron are those whose points are all
  classified "inside." Outside tetrahedron have at least one
  point classified "outside." The method returns the number
  of tetrahedron of the type requested.
* vtkIdType = obj.AddTetras (int classification,
  vtkIncrementalPointLocator locator, vtkCellArray
  outConnectivity, vtkPointData inPD, vtkPointData outPD,
  vtkCellData inCD, vtkIdType cellId, vtkCellData outCD) -
  Assuming that all the inserted points come from a cell
  `cellId' to triangulate, get the tetrahedra in
  outConnectivity, the points in locator and copy point data
  and cell data. Return the number of added tetras.


    Precondition:
        locator_exists: locator!=0
        outConnectivity: outConnectivity!=0
        inPD_exists: inPD!=0
        outPD_exists: outPD!=0
        inCD_exists: inCD!=0
        outCD_exists: outCD!=0

* vtkIdType = obj.AddTetras (int classification, vtkIdList
  ptIds, vtkPoints pts) - Add the tetrahedra classified
  (0=inside,1=outside) to the list of ids and coordinates
  provided. These assume that the first four points form a
  tetrahedron, the next four the next, and so on.
* vtkIdType = obj.AddTriangles (vtkCellArray connectivity) -
  Add the triangle faces classified (2=boundary) to the
  connectivity list provided. The method returns the number
  of triangles.
* vtkIdType = obj.AddTriangles (vtkIdType id, vtkCellArray
  connectivity) - Add the triangle faces classified
  (2=boundary) and attached to the specified point id to the
  connectivity list provided. (The id is the same as that
  specified in InsertPoint().)
* obj.InitTetraTraversal () - Methods to get one tetra at a
  time. Start with InitTetraTraversal() and then invoke
  GetNextTetra() until the method returns 0.
* int = obj.GetNextTetra (int classification, vtkTetra tet,
  vtkDataArray cellScalars, vtkDoubleArray tetScalars) -
  Methods to get one tetra at a time. Start with
  InitTetraTraversal() and then invoke GetNextTetra() until
  the method returns 0. cellScalars are point-centered
  scalars on the original cell. tetScalars are point-
  centered scalars on the tetra: the values will be copied
  from cellScalars.


    Precondition:
        tet_exists: tet!=0
        cellScalars_exists: cellScalars!=0
        tetScalars_exists: tetScalars!=0
        tetScalars_valid_size: tetScalars->GetNumberOfTuples
        ()==4



* FreeMat_Documentation
* Visualization_Toolkit_Filtering_Classes
* Generated on Thu Jul 25 2013 17:18:31 for FreeMat by
  doxygen_ 1.8.1.1

