1 /*=========================================================================
2 
3   Program:   Visualization Toolkit
4   Module:    vtkIncrementalPointLocator.h
5 
6   Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
7   All rights reserved.
8   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
9 
10      This software is distributed WITHOUT ANY WARRANTY; without even
11      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
12      PURPOSE.  See the above copyright notice for more information.
13 
14 =========================================================================*/
15 // .NAME vtkIncrementalPointLocator - Abstract class in support of both
16 //  point location and point insertion.
17 //
18 // .SECTION Description
19 //  Compared to a static point locator for pure location functionalities
20 //  through some search structure established from a fixed set of points,
21 //  an incremental point locator allows for, in addition, point insertion
22 //  capabilities, with the search structure maintaining a dynamically
23 //  increasing number of points. There are two incremental point locators,
24 //  i.e., vtkPointLocator and vtkIncrementalOctreePointLocator. As opposed
25 //  to the uniform bin-based search structure (adopted in vtkPointLocator)
26 //  with a fixed spatial resolution, an octree mechanism (employed in
27 //  vtkIncrementalOctreePointlocator) resorts to a hierarchy of tree-like
28 //  sub-division of the 3D data domain. Thus it enables data-aware multi-
29 //  resolution and accordingly accelerated point location as well as point
30 //  insertion, particularly when handling a radically imbalanced layout of
31 //  points as not uncommon in datasets defined on adaptive meshes. In other
32 //  words, vtkIncrementalOctreePointLocator is an octree-based accelerated
33 //  implementation of all functionalities of vtkPointLocator.
34 //
35 // .SECTION See Also
36 //  vtkLocator, vtkIncrementalOctreePointLocator, vtkPointLocator,
37 //  vtkMergePoints
38 
39 #ifndef vtkIncrementalPointLocator_h
40 #define vtkIncrementalPointLocator_h
41 
42 #include "vtkCommonDataModelModule.h" // For export macro
43 #include "vtkAbstractPointLocator.h"
44 
45 class vtkPoints;
46 class vtkIdList;
47 
48 class VTKCOMMONDATAMODEL_EXPORT vtkIncrementalPointLocator : public vtkAbstractPointLocator
49 {
50 public:
51 
52   vtkTypeMacro( vtkIncrementalPointLocator, vtkAbstractPointLocator );
53   void PrintSelf( ostream & os, vtkIndent indent );
54 
55   // Description:
56   // Delete the search structure.
57   virtual void Initialize() = 0;
58 
59   // Description:
60   // Given a point x assumed to be covered by the search structure, return the
61   // index of the closest point (already inserted to the search structure)
62   // regardless of the associated minimum squared distance relative to the
63   // squared insertion-tolerance distance. This method is used when performing
64   // incremental point insertion. Note -1 indicates that no point is found.
65   // InitPointInsertion() should have been called in advance.
66   virtual vtkIdType FindClosestInsertedPoint( const double x[3] ) = 0;
67 
68   // -------------------------------------------------------------------------
69   // ---------------------------- Point  Location ----------------------------
70   // ---- All virtual functions related to point location are declared by ----
71   // --------------- the parent class  vtkAbstractPointLocator ---------------
72   // -------------------------------------------------------------------------
73 
74   // -------------------------------------------------------------------------
75   // ---------------------------- Point Insertion ----------------------------
76   // -------------------------------------------------------------------------
77 
78   // Description:
79   // Initialize the point insertion process. newPts is an object, storing 3D
80   // point coordinates, to which incremental point insertion puts coordinates.
81   // It is created and provided by an external VTK class. Argument bounds
82   // represents the spatial bounding box, into which the points fall.
83   virtual int InitPointInsertion( vtkPoints * newPts, const double bounds[6] ) = 0;
84 
85   // Description:
86   // Initialize the point insertion process. newPts is an object, storing 3D
87   // point coordinates, to which incremental point insertion puts coordinates.
88   // It is created and provided by an external VTK class. Argument bounds
89   // represents the spatial bounding box, into which the points fall.
90   virtual int InitPointInsertion( vtkPoints * newPts, const double bounds[6],
91                                   vtkIdType estSize ) = 0;
92 
93   // Description:
94   // Determine whether or not a given point has been inserted. Return the id of
95   // the already inserted point if true, else return -1. InitPointInsertion()
96   // should have been called in advance.
97   virtual vtkIdType IsInsertedPoint( double x, double  y, double z ) = 0;
98 
99   // Description:
100   // Determine whether or not a given point has been inserted. Return the id of
101   // the already inserted point if true, else return -1. InitPointInsertion()
102   // should have been called in advance.
103   virtual vtkIdType IsInsertedPoint( const double x[3] ) = 0;
104 
105   // Description:
106   // Insert a point unless there has been a duplciate in the search structure.
107   // This method is not thread safe.
108   virtual int InsertUniquePoint( const double x[3], vtkIdType & ptId ) = 0;
109 
110   // Description:
111   // Insert a given point with a specified point index ptId. InitPointInsertion()
112   // should have been called prior to this function. Also, IsInsertedPoint()
113   // should have been called in advance to ensure that the given point has not
114   // been inserted unless point duplication is allowed.
115   virtual void InsertPoint( vtkIdType ptId, const double x[3] ) = 0;
116 
117   // Description:
118   // Insert a given point and return the point index. InitPointInsertion()
119   // should have been called prior to this function. Also, IsInsertedPoint()
120   // should have been called in advance to ensure that the given point has not
121   // been inserted unless point duplication is allowed.
122   virtual vtkIdType InsertNextPoint( const double x[3] ) = 0;
123 
124 protected:
125   vtkIncrementalPointLocator();
126   virtual ~vtkIncrementalPointLocator();
127 
128 private:
129   vtkIncrementalPointLocator( const vtkIncrementalPointLocator & );  // Not implemented.
130   void operator = ( const vtkIncrementalPointLocator & );            // Not implemented.
131 };
132 
133 #endif
134