VTK  9.0.1
vtkKdTree.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Program: Visualization Toolkit
4  Module: vtkKdTree.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  Copyright (c) Sandia Corporation
17  See Copyright.txt or http://www.paraview.org/HTML/Copyright.html for details.
18 ----------------------------------------------------------------------------*/
19 
62 #ifndef vtkKdTree_h
63 #define vtkKdTree_h
64 
65 #include "vtkCommonDataModelModule.h" // For export macro
66 #include "vtkLocator.h"
67 
68 class vtkTimerLog;
69 class vtkIdList;
70 class vtkIdTypeArray;
71 class vtkIntArray;
72 class vtkPointSet;
73 class vtkPoints;
74 class vtkCellArray;
75 class vtkCell;
76 class vtkKdNode;
77 class vtkBSPCuts;
80 
81 class VTKCOMMONDATAMODEL_EXPORT vtkKdTree : public vtkLocator
82 {
83 public:
84  vtkTypeMacro(vtkKdTree, vtkLocator);
85  void PrintSelf(ostream& os, vtkIndent indent) override;
86 
87  static vtkKdTree* New();
88 
90 
93  vtkBooleanMacro(Timing, vtkTypeBool);
94  vtkSetMacro(Timing, vtkTypeBool);
95  vtkGetMacro(Timing, vtkTypeBool);
97 
99 
102  vtkSetMacro(MinCells, int);
103  vtkGetMacro(MinCells, int);
105 
113  vtkGetMacro(NumberOfRegionsOrLess, int);
114  vtkSetMacro(NumberOfRegionsOrLess, int);
115 
123  vtkGetMacro(NumberOfRegionsOrMore, int);
124  vtkSetMacro(NumberOfRegionsOrMore, int);
125 
133  vtkGetMacro(FudgeFactor, double);
134  vtkSetMacro(FudgeFactor, double);
135 
141  vtkGetObjectMacro(Cuts, vtkBSPCuts);
142 
149  void SetCuts(vtkBSPCuts* cuts);
150 
154  void OmitXPartitioning();
155 
159  void OmitYPartitioning();
160 
164  void OmitZPartitioning();
165 
169  void OmitXYPartitioning();
170 
174  void OmitYZPartitioning();
175 
179  void OmitZXPartitioning();
180 
184  void OmitNoPartitioning();
185 
200  void SetDataSet(vtkDataSet* set) override;
201 
206  virtual void AddDataSet(vtkDataSet* set);
207 
209 
212  virtual void RemoveDataSet(int index);
213  virtual void RemoveDataSet(vtkDataSet* set);
214  virtual void RemoveAllDataSets();
216 
220  int GetNumberOfDataSets();
221 
231  vtkDataSet* GetDataSet(int n);
232 
237  vtkDataSet* GetDataSet() override { return this->GetDataSet(0); }
238 
240 
243  vtkGetObjectMacro(DataSets, vtkDataSetCollection);
245 
250  int GetDataSetIndex(vtkDataSet* set);
251 
256  void GetBounds(double* bounds);
257 
266  void SetNewBounds(double* bounds);
267 
269 
272  vtkGetMacro(NumberOfRegions, int);
274 
278  void GetRegionBounds(int regionID, double bounds[6]);
279 
283  void GetRegionDataBounds(int regionID, double bounds[6]);
284 
286 
289  void PrintTree();
290  void PrintVerboseTree();
292 
296  void PrintRegion(int id);
297 
310  void CreateCellLists(int dataSetIndex, int* regionReqList, int reqListSize);
311  void CreateCellLists(vtkDataSet* set, int* regionReqList, int reqListSize);
312  void CreateCellLists(int* regionReqList, int listSize);
313  void CreateCellLists();
314 
316 
323  vtkSetMacro(IncludeRegionBoundaryCells, vtkTypeBool);
324  vtkGetMacro(IncludeRegionBoundaryCells, vtkTypeBool);
325  vtkBooleanMacro(IncludeRegionBoundaryCells, vtkTypeBool);
327 
331  void DeleteCellLists();
332 
337  vtkIdList* GetCellList(int regionID);
338 
349  vtkIdList* GetBoundaryCellList(int regionID);
350 
352 
372  vtkIdType GetCellLists(
373  vtkIntArray* regions, int set, vtkIdList* inRegionCells, vtkIdList* onBoundaryCells);
374  vtkIdType GetCellLists(
375  vtkIntArray* regions, vtkDataSet* set, vtkIdList* inRegionCells, vtkIdList* onBoundaryCells);
376  vtkIdType GetCellLists(
377  vtkIntArray* regions, vtkIdList* inRegionCells, vtkIdList* onBoundaryCells);
379 
381 
387  int GetRegionContainingCell(vtkDataSet* set, vtkIdType cellID);
388  int GetRegionContainingCell(int set, vtkIdType cellID);
389  int GetRegionContainingCell(vtkIdType cellID);
391 
400  int* AllGetRegionContainingCell();
401 
405  int GetRegionContainingPoint(double x, double y, double z);
406 
412  void BuildLocator() override;
413 
428  int MinimalNumberOfConvexSubRegions(vtkIntArray* regionIdList, double** convexRegionBounds);
429 
437  int ViewOrderAllRegionsInDirection(
438  const double directionOfProjection[3], vtkIntArray* orderedList);
439 
447  int ViewOrderRegionsInDirection(
448  vtkIntArray* regionIds, const double directionOfProjection[3], vtkIntArray* orderedList);
449 
457  int ViewOrderAllRegionsFromPosition(
458  const double directionOfProjection[3], vtkIntArray* orderedList);
459 
467  int ViewOrderRegionsFromPosition(
468  vtkIntArray* regionIds, const double directionOfProjection[3], vtkIntArray* orderedList);
469 
471 
484  void BuildLocatorFromPoints(vtkPointSet* pointset);
485  void BuildLocatorFromPoints(vtkPoints* ptArray);
486  void BuildLocatorFromPoints(vtkPoints** ptArray, int numPtArrays);
488 
503  vtkIdTypeArray* BuildMapForDuplicatePoints(float tolerance);
504 
506 
511  vtkIdType FindPoint(double* x);
512  vtkIdType FindPoint(double x, double y, double z);
514 
516 
521  vtkIdType FindClosestPoint(double* x, double& dist2);
522  vtkIdType FindClosestPoint(double x, double y, double z, double& dist2);
524 
530  vtkIdType FindClosestPointWithinRadius(double radius, const double x[3], double& dist2);
531 
533 
538  vtkIdType FindClosestPointInRegion(int regionId, double* x, double& dist2);
539  vtkIdType FindClosestPointInRegion(int regionId, double x, double y, double z, double& dist2);
541 
548  void FindPointsWithinRadius(double R, const double x[3], vtkIdList* result);
549 
558  void FindClosestNPoints(int N, const double x[3], vtkIdList* result);
559 
564  vtkIdTypeArray* GetPointsInRegion(int regionId);
565 
570  void FreeSearchStructure() override;
571 
577  void GenerateRepresentation(int level, vtkPolyData* pd) override;
578 
583  void GenerateRepresentation(int* regionList, int len, vtkPolyData* pd);
584 
586 
592  vtkBooleanMacro(GenerateRepresentationUsingDataBounds, vtkTypeBool);
593  vtkSetMacro(GenerateRepresentationUsingDataBounds, vtkTypeBool);
594  vtkGetMacro(GenerateRepresentationUsingDataBounds, vtkTypeBool);
596 
600  virtual void PrintTiming(ostream& os, vtkIndent indent);
601 
606  virtual int NewGeometry();
607 
613  virtual int NewGeometry(vtkDataSet** sets, int numDataSets);
614 
620  virtual void InvalidateGeometry();
621 
627  static vtkKdNode* CopyTree(vtkKdNode* kd);
628 
635  void FindPointsInArea(double* area, vtkIdTypeArray* ids, bool clearArray = true);
636 
637 protected:
638  vtkKdTree();
639  ~vtkKdTree() override;
640 
643 
644  void SetCalculator(vtkKdNode* kd);
645 
646  int ProcessUserDefinedCuts(double* bounds);
647 
648  void SetCuts(vtkBSPCuts* cuts, int userDefined);
649 
655  void UpdateBuildTime();
656 
664  int DivideTest(int numberOfPoints, int level);
665 
666  enum
667  {
668  XDIM = 0, // don't change these values
669  YDIM = 1,
670  ZDIM = 2
671  };
672 
674 
676  vtkKdNode** RegionList; // indexed by region ID
677 
679 
680  static void DeleteAllDescendants(vtkKdNode* nd);
681 
682  void BuildRegionList();
683  virtual int SelectCutDirection(vtkKdNode* kd);
684  void SetActualLevel() { this->Level = vtkKdTree::ComputeLevel(this->Top); }
685 
691  void GetRegionsAtLevel(int level, vtkKdNode** nodes);
692 
698  static void GetLeafNodeIds(vtkKdNode* node, vtkIntArray* ids);
699 
704  int GetNumberOfCells();
705 
711  int GetDataSetsNumberOfCells(int set1, int set2);
712 
719  void ComputeCellCenter(vtkDataSet* set, int cellId, float* center);
720  void ComputeCellCenter(vtkDataSet* set, int cellId, double* center);
721 
731  float* ComputeCellCenters();
732  float* ComputeCellCenters(int set);
733  float* ComputeCellCenters(vtkDataSet* set);
734 
736 
742  void UpdateProgress(double amount);
743 
745 
748  vtkSetClampMacro(Progress, double, 0.0, 1.0);
749  vtkGetMacro(Progress, double);
751 
752 protected:
753  // So that each suboperation can report progress
754  // in [0,1], yet we will be able to report a global
755  // progress. Sub-operations must use UpdateSubOperationProgress()
756  // for this to work.
757  double ProgressScale;
759 
760  // Update progress for a sub-operation. \c amount goes from 0.0 to 1.0.
761  // Actual progress is given by
762  // (this->ProgressOffset + this->ProgressScale* amount).
763  void UpdateSubOperationProgress(double amount);
764 
765  static void _SetNewBounds(vtkKdNode* kd, double* b, int* fixDim);
766  static void CopyChildNodes(vtkKdNode* to, vtkKdNode* from);
767  static void CopyKdNode(vtkKdNode* to, vtkKdNode* from);
768  static void SetDataBoundsToSpatialBounds(vtkKdNode* kd);
769  static void ZeroNumberOfPoints(vtkKdNode* kd);
770 
771  // Recursive helper for public FindPointsWithinRadius
772  void FindPointsWithinRadius(vtkKdNode* node, double R2, const double x[3], vtkIdList* ids);
773 
774  // Recursive helper for public FindPointsWithinRadius
775  void AddAllPointsInRegion(vtkKdNode* node, vtkIdList* ids);
776 
777  // Recursive helper for public FindPointsInArea
778  void FindPointsInArea(vtkKdNode* node, double* area, vtkIdTypeArray* ids);
779 
780  // Recursive helper for public FindPointsInArea
781  void AddAllPointsInRegion(vtkKdNode* node, vtkIdTypeArray* ids);
782 
783  int DivideRegion(vtkKdNode* kd, float* c1, int* ids, int nlevels);
784 
785  void DoMedianFind(vtkKdNode* kd, float* c1, int* ids, int d1, int d2, int d3);
786 
787  void SelfRegister(vtkKdNode* kd);
788 
789  struct _cellList
790  {
791  vtkDataSet* dataSet; // cell lists for which data set
792  int* regionIds; // nullptr if listing all regions
793  int nRegions;
797  };
798 
799  void InitializeCellLists();
800  vtkIdList* GetList(int regionId, vtkIdList** which);
801 
802  void ComputeCellCenter(vtkCell* cell, double* center, double* weights);
803 
804  void GenerateRepresentationDataBounds(int level, vtkPolyData* pd);
805  void _generateRepresentationDataBounds(
806  vtkKdNode* kd, vtkPoints* pts, vtkCellArray* polys, int level);
807 
808  void GenerateRepresentationWholeSpace(int level, vtkPolyData* pd);
809  void _generateRepresentationWholeSpace(
810  vtkKdNode* kd, vtkPoints* pts, vtkCellArray* polys, int level);
811 
812  void AddPolys(vtkKdNode* kd, vtkPoints* pts, vtkCellArray* polys);
813 
814  void _printTree(int verbose);
815 
816  int SearchNeighborsForDuplicate(
817  int regionId, float* point, int** pointsSoFar, int* len, float tolerance, float tolerance2);
818 
819  int SearchRegionForDuplicate(float* point, int* pointsSoFar, int len, float tolerance2);
820 
821  int _FindClosestPointInRegion(int regionId, double x, double y, double z, double& dist2);
822 
823  int FindClosestPointInSphere(
824  double x, double y, double z, double radius, int skipRegion, double& dist2);
825 
826  int _ViewOrderRegionsInDirection(
827  vtkIntArray* IdsOfInterest, const double dop[3], vtkIntArray* orderedList);
828 
829  static int __ViewOrderRegionsInDirection(vtkKdNode* node, vtkIntArray* list,
830  vtkIntArray* IdsOfInterest, const double dir[3], int nextId);
831 
832  int _ViewOrderRegionsFromPosition(
833  vtkIntArray* IdsOfInterest, const double pos[3], vtkIntArray* orderedList);
834 
835  static int __ViewOrderRegionsFromPosition(vtkKdNode* node, vtkIntArray* list,
836  vtkIntArray* IdsOfInterest, const double pos[3], int nextId);
837 
838  static int __ConvexSubRegions(int* ids, int len, vtkKdNode* tree, vtkKdNode** nodes);
839  static int FoundId(vtkIntArray* idArray, int id);
840 
841  void SetInputDataInfo(int i, int dims[3], double origin[3], double spacing[3]);
842  int CheckInputDataInfo(int i, int dims[3], double origin[3], double spacing[3]);
843  void ClearLastBuildCache();
844 
845  static void __printTree(vtkKdNode* kd, int depth, int verbose);
846 
847  static int MidValue(int dim, float* c1, int nvals, double& coord);
848 
849  static int Select(int dim, float* c1, int* ids, int nvals, double& coord);
850  static float FindMaxLeftHalf(int dim, float* c1, int K);
851  static void _Select(int dim, float* X, int* ids, int L, int R, int K);
852 
853  static int ComputeLevel(vtkKdNode* kd);
854  static int SelfOrder(int id, vtkKdNode* kd);
855  static int findRegion(vtkKdNode* node, float x, float y, float z);
856  static int findRegion(vtkKdNode* node, double x, double y, double z);
857 
858  static vtkKdNode** _GetRegionsAtLevel(int level, vtkKdNode** nodes, vtkKdNode* kd);
859 
860  static void AddNewRegions(vtkKdNode* kd, float* c1, int midpt, int dim, double coord);
861 
862  void NewPartitioningRequest(int req);
863 
866 
868  double CellBoundsCache[6]; // to optimize IntersectsCell()
869 
871 
872  struct _cellList CellList;
873 
874  // Region Ids, by data set by cell id - this list is large (one
875  // int per cell) but accelerates creation of cell lists
876 
878 
879  int MinCells;
880  int NumberOfRegions; // number of leaf nodes
881 
883  double FudgeFactor; // a very small distance, relative to the dataset's size
884 
885  // These instance variables are used by the special locator created
886  // to find duplicate points. (BuildLocatorFromPoints)
887 
892 
893  float MaxWidth;
894 
895  // These Last* values are here to save state so we can
896  // determine later if k-d tree must be rebuilt.
897 
901  unsigned long* LastDataSetObserverTags;
904  double* LastBounds;
907 
909  double Progress;
910 
911  vtkKdTree(const vtkKdTree&) = delete;
912  void operator=(const vtkKdTree&) = delete;
913 };
914 #endif
vtkPoints
represent and manipulate 3D points
Definition: vtkPoints.h:33
vtkKdTree::TimerLog
vtkTimerLog * TimerLog
Definition: vtkKdTree.h:678
vtkKdNode
This class represents a single spatial region in an 3D axis aligned binary spatial partitioning....
Definition: vtkKdNode.h:42
vtkLocator::SetDataSet
virtual void SetDataSet(vtkDataSet *)
Build the locator from the points/cells defining this dataset.
vtkKdTree::_cellList::nRegions
int nRegions
Definition: vtkKdTree.h:793
vtkKdTree::FudgeFactor
double FudgeFactor
Definition: vtkKdTree.h:883
vtkKdTree::LocatorIds
int * LocatorIds
Definition: vtkKdTree.h:890
vtkKdTree::_cellList::emptyList
vtkIdList * emptyList
Definition: vtkKdTree.h:796
vtkLocator::GetDataSet
virtual vtkDataSet * GetDataSet()
vtkIdType
int vtkIdType
Definition: vtkType.h:338
vtkObject::New
static vtkObject * New()
Create an object with Debug turned off, modified time initialized to zero, and reference counting on.
vtkKdTree::_cellList::dataSet
vtkDataSet * dataSet
Definition: vtkKdTree.h:791
vtkKdTree::SetActualLevel
void SetActualLevel()
Definition: vtkKdTree.h:684
vtkKdTree::_cellList::cells
vtkIdList ** cells
Definition: vtkKdTree.h:794
vtkLocator.h
vtkX3D::dir
@ dir
Definition: vtkX3D.h:330
vtkKdTree::LastInputDataInfo
double * LastInputDataInfo
Definition: vtkKdTree.h:903
vtkKdTree::LastNumPoints
vtkIdType * LastNumPoints
Definition: vtkKdTree.h:905
vtkX3D::center
@ center
Definition: vtkX3D.h:236
vtkKdTree::CellRegionList
int * CellRegionList
Definition: vtkKdTree.h:877
vtkKdTree::LastBounds
double * LastBounds
Definition: vtkKdTree.h:904
vtkKdTree::ProgressOffset
double ProgressOffset
Definition: vtkKdTree.h:758
vtkKdTree::_cellList::regionIds
int * regionIds
Definition: vtkKdTree.h:792
vtkLocator
abstract base class for objects that accelerate spatial searches
Definition: vtkLocator.h:69
vtkX3D::level
@ level
Definition: vtkX3D.h:401
vtkX3D::point
@ point
Definition: vtkX3D.h:242
vtkBSPIntersections
Perform calculations (mostly intersection calculations) on regions of a 3D binary spatial partitionin...
Definition: vtkBSPIntersections.h:45
vtkKdTree::NumberOfRegionsOrMore
int NumberOfRegionsOrMore
Definition: vtkKdTree.h:865
vtkKdTree::Top
vtkKdNode * Top
Definition: vtkKdTree.h:675
vtkLocator::GenerateRepresentation
virtual void GenerateRepresentation(int level, vtkPolyData *pd)=0
Method to build a representation at a particular level.
vtkKdTree::LocatorPoints
float * LocatorPoints
Definition: vtkKdTree.h:889
vtkKdTree::_cellList::boundaryCells
vtkIdList ** boundaryCells
Definition: vtkKdTree.h:795
vtkKdTree::Timing
vtkTypeBool Timing
Definition: vtkKdTree.h:882
vtkKdTree::BSPCalculator
vtkBSPIntersections * BSPCalculator
Definition: vtkKdTree.h:641
vtkCell
abstract class to specify cell behavior
Definition: vtkCell.h:56
vtkKdTree::ValidDirections
int ValidDirections
Definition: vtkKdTree.h:673
vtkIndent
a simple class to control print indentation
Definition: vtkIndent.h:33
vtkKdTree::ComputeLevel
static int ComputeLevel(vtkKdNode *kd)
vtkCellArray
object to represent cell connectivity
Definition: vtkCellArray.h:179
vtkIntArray
dynamic, self-adjusting array of int
Definition: vtkIntArray.h:39
vtkKdTree::LastDataSetObserverTags
unsigned long * LastDataSetObserverTags
Definition: vtkKdTree.h:901
vtkKdTree::MinCells
int MinCells
Definition: vtkKdTree.h:879
vtkKdTree::NumberOfRegions
int NumberOfRegions
Definition: vtkKdTree.h:880
vtkKdTree::GenerateRepresentationUsingDataBounds
vtkTypeBool GenerateRepresentationUsingDataBounds
Definition: vtkKdTree.h:870
vtkBSPCuts
This class represents an axis-aligned Binary Spatial Partitioning of a 3D space.
Definition: vtkBSPCuts.h:44
vtkIdList
list of point or cell ids
Definition: vtkIdList.h:30
vtkKdTree::Progress
double Progress
Definition: vtkKdTree.h:909
vtkKdTree::_cellList
Definition: vtkKdTree.h:789
vtkKdTree::GetDataSet
vtkDataSet * GetDataSet() override
Return the 0'th data set.
Definition: vtkKdTree.h:237
vtkLocator::BuildLocator
virtual void BuildLocator()=0
Build the locator from the input dataset.
vtkKdTree::LastInputDataSets
vtkDataSet ** LastInputDataSets
Definition: vtkKdTree.h:900
vtkKdTree::LocatorRegionLocation
int * LocatorRegionLocation
Definition: vtkKdTree.h:891
vtkKdTree::LastNumDataSets
int LastNumDataSets
Definition: vtkKdTree.h:898
vtkKdTree::ProgressScale
double ProgressScale
Definition: vtkKdTree.h:749
vtkKdTree::DataSets
vtkDataSetCollection * DataSets
Definition: vtkKdTree.h:735
vtkX3D::spacing
@ spacing
Definition: vtkX3D.h:487
vtkDataSet
abstract class to specify dataset behavior
Definition: vtkDataSet.h:56
vtkKdTree::MaxWidth
float MaxWidth
Definition: vtkKdTree.h:893
vtkKdTree::LastDataSetType
int * LastDataSetType
Definition: vtkKdTree.h:902
vtkTimerLog
Timer support and logging.
Definition: vtkTimerLog.h:90
vtkIdTypeArray
dynamic, self-adjusting array of vtkIdType
Definition: vtkIdTypeArray.h:35
vtkKdTree::LastNumCells
vtkIdType * LastNumCells
Definition: vtkKdTree.h:906
vtkKdTree::IncludeRegionBoundaryCells
vtkTypeBool IncludeRegionBoundaryCells
Definition: vtkKdTree.h:867
vtkPointSet
abstract class for specifying dataset behavior
Definition: vtkPointSet.h:62
vtkKdTree::NumberOfLocatorPoints
int NumberOfLocatorPoints
Definition: vtkKdTree.h:888
vtkLocator::PrintSelf
void PrintSelf(ostream &os, vtkIndent indent) override
Methods invoked by print to print information about the object including superclasses.
vtkPolyData
concrete dataset represents vertices, lines, polygons, and triangle strips
Definition: vtkPolyData.h:84
vtkKdTree
a Kd-tree spatial decomposition of a set of points
Definition: vtkKdTree.h:81
vtkKdTree::NumberOfRegionsOrLess
int NumberOfRegionsOrLess
Definition: vtkKdTree.h:864
vtkDataSetCollection
maintain an unordered list of dataset objects
Definition: vtkDataSetCollection.h:31
vtkKdTree::Cuts
vtkBSPCuts * Cuts
Definition: vtkKdTree.h:908
vtkKdTree::LastDataCacheSize
int LastDataCacheSize
Definition: vtkKdTree.h:899
vtkKdTree::RegionList
vtkKdNode ** RegionList
Definition: vtkKdTree.h:676
vtkLocator::FreeSearchStructure
virtual void FreeSearchStructure()=0
Free the memory required for the spatial data structure.
vtkX3D::radius
@ radius
Definition: vtkX3D.h:258
vtkX3D::index
@ index
Definition: vtkX3D.h:252
vtkTypeBool
int vtkTypeBool
Definition: vtkABI.h:69
vtkKdTree::UserDefinedCuts
int UserDefinedCuts
Definition: vtkKdTree.h:642