I386LINUX/util/I386LINUX/include/vtk/vtkLocator.h

   1 /*=========================================================================
   2
   3   Program:   Visualization Toolkit
   4   Module:    $RCSfile: vtkLocator.h,v $
   5   Language:  C++
   6   Date:      $Date: 2003/01/06 20:36:14 $
   7   Version:   $Revision: 1.49 $
   8
   9   Copyright (c) 1993-2002 Ken Martin, Will Schroeder, Bill Lorensen
  10   All rights reserved.
  11   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
  12
  13      This software is distributed WITHOUT ANY WARRANTY; without even
  14      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15      PURPOSE.  See the above copyright notice for more information.
  16
  17 =========================================================================*/
  18 // .NAME vtkLocator - abstract base class for objects that accelerate spatial searches
  19 // .SECTION Description
  20 // vtkLocator is an abstract base class for spatial search objects, or
  21 // locators. The principle behind locators is that they divide 3-space into
  22 // small pieces (or "buckets") that can be quickly found in response to
  23 // queries like point location, line intersection, or object-object
  24 // intersection.
  25 //
  26 // The purpose of this base class is to provide ivars and methods shared by
  27 // all locators. The GenerateRepresentation() is one such interesting method.
  28 // This method works in conjunction with vtkLocatorFilter to create polygonal
  29 // representations for the locator. For example, if the locator is an OBB tree
  30 // (i.e., vtkOBBTree.h), then the representation is a set of one or more
  31 // oriented bounding boxes, depending upon the specified level.
  32 //
  33 // Locators typically work as follows. One or more "entities", such as
  34 // points or cells, are inserted into the tree. These entities are associated
  35 // with one or more buckets. Then, when performing geometric operations, the
  36 // operations are performed first on the buckets, and then if the operation
  37 // tests positive, then on the entities in the bucket. For example, during
  38 // collision tests, the locators are collided first to identify intersecting
  39 // buckets. If an intersection is found, more expensive operations are then
  40 // carried out on the entities in the bucket.
  41 //
  42 // To obtain good performance, locators are often organized in a tree
  43 // structure.  In such a structure, there are frequently multiple "levels"
  44 // corresponding to different nodes in the tree. So the word level (in the
  45 // context of the locator) can be used to specify a particular representation
  46 // in the tree.  For example, in an octree (which is a tree with 8 children),
  47 // level 0 is the bounding box, or root octant, and level 1 consists of its
  48 // eight children.
  49
  50 // .SECTION See Also
  51 // vtkPointLocator vtkCellLocator vtkOBBTree vtkLocatorFilter
  52
  53 #ifndef __vtkLocator_h
  54 #define __vtkLocator_h
  55
  56 #include "vtkObject.h"
  57
  58 class vtkDataSet;
  59 class vtkPolyData;
  60
  61 class VTK_COMMON_EXPORT vtkLocator : public vtkObject
  62 {
  63 public:
  64   vtkTypeRevisionMacro(vtkLocator,vtkObject);
  65   void PrintSelf(ostream& os, vtkIndent indent);
  66
  67   // Description:
  68   // Build the locator from the points/cells defining this dataset.
  69   virtual void SetDataSet(vtkDataSet*);
  70   vtkGetObjectMacro(DataSet,vtkDataSet);
  71
  72   // Description:
  73   // Set the maximum allowable level for the tree. If the Automatic ivar is
  74   // off, this will be the target depth of the locator.
  75   vtkSetClampMacro(MaxLevel,int,0,VTK_LARGE_INTEGER);
  76   vtkGetMacro(MaxLevel,int);
  77
  78   // Description:
  79   // Get the level of the locator (determined automatically if Automatic is
  80   // true). The value of this ivar may change each time the locator is built.
  81   vtkGetMacro(Level,int);
  82
  83   // Description:
  84   // Boolean controls whether locator depth/resolution of locator is computed
  85   // automatically from average number of entities in bucket. If not set,
  86   // there will be an explicit method to control the construction of the
  87   // locator (found in the subclass).
  88   vtkSetMacro(Automatic,int);
  89   vtkGetMacro(Automatic,int);
  90   vtkBooleanMacro(Automatic,int);
  91
  92   // Description:
  93   // Specify absolute tolerance (in world coordinates) for performing
  94   // geometric operations.
  95   vtkSetClampMacro(Tolerance,float,0.0f,VTK_LARGE_FLOAT);
  96   vtkGetMacro(Tolerance,float);
  97
  98   // Description:
  99   // Boolean controls whether to maintain list of entities in each bucket.
 100   // Normally the lists are maintained, but if the locator is being used
 101   // as a geometry simplification technique, there is no need to keep them.
 102   vtkSetMacro(RetainCellLists,int);
 103   vtkGetMacro(RetainCellLists,int);
 104   vtkBooleanMacro(RetainCellLists,int);
 105
 106   // Description:
 107   // Cause the locator to rebuild itself if it or its input dataset has
 108   // changed.
 109   virtual void Update();
 110
 111   // Description:
 112   // Initialize locator. Frees memory and resets object as appropriate.
 113   virtual void Initialize();
 114
 115   // Description:
 116   // Build the locator from the input dataset.
 117   virtual void BuildLocator() = 0;
 118
 119   // Description:
 120   // Free the memory required for the spatial data structure.
 121   virtual void FreeSearchStructure() = 0;
 122
 123   // Description:
 124   // Method to build a representation at a particular level. Note that the
 125   // method GetLevel() returns the maximum number of levels available for
 126   // the tree. You must provide a vtkPolyData object into which to place the
 127   // data.
 128   virtual void GenerateRepresentation(int level, vtkPolyData *pd) = 0;
 129
 130   // Description:
 131   // Return the time of the last data structure build.
 132   vtkGetMacro(BuildTime, unsigned long);
 133
 134 protected:
 135   vtkLocator();
 136   ~vtkLocator();
 137
 138   vtkDataSet *DataSet;
 139   int Automatic; // boolean controls automatic subdivision (or uses user spec.)
 140   float Tolerance; // for performing merging
 141   int MaxLevel;
 142   int Level;
 143   int RetainCellLists;
 144
 145   vtkTimeStamp BuildTime;  // time at which locator was built
 146
 147 private:
 148   vtkLocator(const vtkLocator&);  // Not implemented.
 149   void operator=(const vtkLocator&);  // Not implemented.
 150 };
 151
 152 #endif
 153
 154