Section: Visualization Toolkit Filtering Classes
.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
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.
\post 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.
\post 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).
\pre valid_range: internalId>=0 && 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.
\pre valid_range: internalId>=0 && 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.
\pre locator_exists: locator!=0
\pre outConnectivity: outConnectivity!=0
\pre inPD_exists: inPD!=0
\pre outPD_exists: outPD!=0
\pre inCD_exists: inCD!=0
\pre 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.
\pre tet_exists: tet!=0
\pre cellScalars_exists: cellScalars!=0
\pre tetScalars_exists: tetScalars!=0
\pre tetScalars_valid_size: tetScalars->GetNumberOfTuples()==4