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