FreeMat: vtkIncrementalOctreePointLocator

FreeMat

- Main Page
- Related Pages

vtkIncrementalOctreePointLocator

Section: Visualization Toolkit Filtering Classes

# Usage

As opposed to the uniform bin-based search structure (adopted in class vtkPointLocator) with a fixed spatial resolution, an octree mechanism employs a hierarchy of tree-like sub-division of the 3D data domain. Thus it enables data-aware multi-resolution and accordingly accelerated point location as well as insertion, particularly when handling a radically imbalanced layout of points as not uncommon in datasets defined on adaptive meshes. Compared to a static point locator supporting pure location functionalities through some search structure established from a fixed set of points, an incremental point locator allows for, in addition, point insertion capabilities, with the search structure maintaining a dynamically increasing number of points. Class vtkIncrementalOctreePointLocator is an octree-based accelerated implementation of the functionalities of the uniform bin-based incremental point locator vtkPointLocator. For point location, an octree is built by accessing a vtkDataSet, specifically a vtkPointSet. For point insertion, an empty octree is inited and then incrementally populated as points are inserted. Three increasingly complex point insertion modes, i.e., direct check-free insertion, zero tolerance insertion, and non-zero tolerance insertion, are supported. In fact, the octree used in the point location mode is actually constructed via direct check-free point insertion. This class also provides a polygonal representation of the octree boundary.

To create an instance of class vtkIncrementalOctreePointLocator, simply invoke its constructor as follows

      obj = vtkIncrementalOctreePointLocator

# Methods

The class vtkIncrementalOctreePointLocator has several methods that can be used. They are listed below. Note that the documentation is translated automatically from the VTK sources, and may not be completely intelligible. When in doubt, consult the VTK website. In the methods listed below, `obj` is an instance of the vtkIncrementalOctreePointLocator class.

- `string = obj.GetClassName ()`
- `int = obj.IsA (string name)`
- `vtkIncrementalOctreePointLocator = obj.NewInstance ()`
- `vtkIncrementalOctreePointLocator = obj.SafeDownCast (vtkObject o)`
- `obj.SetMaxPointsPerLeaf (int )` - Set/Get the maximum number of points that a leaf node may maintain. Note that the actual number of points maintained by a leaf node might exceed this threshold if there is a large number (equal to or greater than the threshold) of exactly duplicate points (with zero distance) to be inserted (e.g., to construct an octree for subsequent point location) in extreme cases. Respecting this threshold in such scenarios would cause endless node sub-division. Thus this threshold is broken, but only in case of such situations.
- `int = obj.GetMaxPointsPerLeafMinValue ()` - Set/Get the maximum number of points that a leaf node may maintain. Note that the actual number of points maintained by a leaf node might exceed this threshold if there is a large number (equal to or greater than the threshold) of exactly duplicate points (with zero distance) to be inserted (e.g., to construct an octree for subsequent point location) in extreme cases. Respecting this threshold in such scenarios would cause endless node sub-division. Thus this threshold is broken, but only in case of such situations.
- `int = obj.GetMaxPointsPerLeafMaxValue ()` - Set/Get the maximum number of points that a leaf node may maintain. Note that the actual number of points maintained by a leaf node might exceed this threshold if there is a large number (equal to or greater than the threshold) of exactly duplicate points (with zero distance) to be inserted (e.g., to construct an octree for subsequent point location) in extreme cases. Respecting this threshold in such scenarios would cause endless node sub-division. Thus this threshold is broken, but only in case of such situations.
- `int = obj.GetMaxPointsPerLeaf ()` - Set/Get the maximum number of points that a leaf node may maintain. Note that the actual number of points maintained by a leaf node might exceed this threshold if there is a large number (equal to or greater than the threshold) of exactly duplicate points (with zero distance) to be inserted (e.g., to construct an octree for subsequent point location) in extreme cases. Respecting this threshold in such scenarios would cause endless node sub-division. Thus this threshold is broken, but only in case of such situations.
- `obj.SetBuildCubicOctree (int )` - Set/Get whether the search octree is built as a cubic shape or not.
- `int = obj.GetBuildCubicOctree ()` - Set/Get whether the search octree is built as a cubic shape or not.
- `obj.BuildCubicOctreeOn ()` - Set/Get whether the search octree is built as a cubic shape or not.
- `obj.BuildCubicOctreeOff ()` - Set/Get whether the search octree is built as a cubic shape or not.
- `vtkPoints = obj.GetLocatorPoints ()` - Get access to the vtkPoints object in which point coordinates are stored for either point location or point insertion.
- `obj.Initialize ()` - Delete the octree search structure.
- `obj.FreeSearchStructure ()` - Delete the octree search structure.
- `obj.GetBounds (double bounds)` - Get the spatial bounding box of the octree.
- `int = obj.GetNumberOfPoints ()` - Get the number of points maintained by the octree.
- `vtkIdType = obj.FindClosestInsertedPoint (double x[3])` - Given a point x assumed to be covered by the octree, return the index of the closest in-octree point regardless of the associated minimum squared distance relative to the squared insertion-tolerance distance. This method is used when performing incremental point insertion. Note -1 indicates that no point is found. InitPointInsertion() should have been called in advance.
- `obj.GenerateRepresentation (int nodeLevel, vtkPolyData polysData)` - Create a polygonal representation of the octree boundary (from the root node to a specified level).
- `obj.BuildLocator ()` - Load points from a dataset to construct an octree for point location. This function resorts to InitPointInsertion() to fulfill some of the work.
- `vtkIdType = obj.FindClosestPoint (double x[3])` - Given a point x, return the id of the closest point. BuildLocator() should have been called prior to this function. This method is thread safe if BuildLocator() is directly or indirectly called from a single thread first.
- `vtkIdType = obj.FindClosestPoint (double x, double y, double z)` - Given a point (x, y, z), return the id of the closest point. Note that BuildLocator() should have been called prior to this function. This method is thread safe if BuildLocator() is directly or indirectly called from a single thread first.
- `vtkIdType = obj.FindClosestPoint (double x[3], double miniDist2)` - Given a point x, return the id of the closest point and the associated minimum squared distance (via miniDist2). Note BuildLocator() should have been called prior to this function. This method is thread safe if BuildLocator() is directly or indirectly called from a single thread first.
- `vtkIdType = obj.FindClosestPoint (double x, double y, double z, double miniDist2)` - Given a point (x, y, z), return the id of the closest point and the associated minimum squared distance (via miniDist2). BuildLocator() should have been called prior to this function. This method is thread safe if BuildLocator() is directly or indirectly called from a single thread first.
- `obj.FindPointsWithinRadius (double R, double x[3], vtkIdList result)` - Find all points within a radius R relative to a given point x. The returned point ids (stored in result) are not sorted in any way. BuildLocator() should have been called prior to this function. This method is thread safe if BuildLocator() is directly or indirectly called from a single thread first.
- `obj.FindPointsWithinSquaredRadius (double R2, double x[3], vtkIdList result)` - Find all points within a squared radius R2 relative to a given point x. The returned point ids (stored in result) are not sorted in any way. BuildLocator() should have been called prior to this function. This method is thread safe if BuildLocator() is directly or indirectly called from a single thread first.
- `obj.FindClosestNPoints (int N, double x[3], vtkIdList result)` - Find the closest N points to a given point. The returned point ids (via result) are sorted from closest to farthest. BuildLocator() should have been called prior to this function. This method is thread safe if BuildLocator() is directly or indirectly called from a single thread first.
- `int = obj.InitPointInsertion (vtkPoints points, double bounds[6])` - Initialize the point insertion process. points is an object, storing 3D point coordinates, to which incremental point insertion put coordinates. It is created and provided by an external VTK class. Argument bounds represents the spatial bounding box, into which the points fall. In fact, an adjusted version of the bounding box is used to build the octree to make sure no any point (to be inserted) falls outside the octree. This function is not thread safe.
- `int = obj.InitPointInsertion (vtkPoints points, double bounds[6], vtkIdType estSize)` - Initialize the point insertion process. points is an object, storing 3D point coordinates, to which incremental point insertion put coordinates. It is created and provided by an external VTK class. Argument bounds represents the spatial bounding box, into which the points fall. In fact, an adjusted version of the bounding box is used to build the octree to make sure no any point (to be inserted) falls outside the octree. Argument estSize specifies the initial estimated size of the vtkPoints object. This function is not thread safe.
- `vtkIdType = obj.IsInsertedPoint (double x[3])` - Determine whether or not a given point has been inserted into the octree. Return the id of the already inserted point if true, otherwise return -1. InitPointInsertion() should have been called in advance.
- `vtkIdType = obj.IsInsertedPoint (double x, double y, double z)` - Determine whether or not a given point has been inserted into the octree. Return the id of the already inserted point if true, otherwise return -1. InitPointInsertion() should have been called in advance.
- `obj.InsertPoint (vtkIdType ptId, double x[3])` - Insert a given point into the octree with a specified point index ptId. InitPointInsertion() should have been called prior to this function. In addition, IsInsertedPoint() should have been called in advance to ensure that the given point has not been inserted unless point duplication is allowed (Note that in this case, this function involves a repeated leaf container location). vtkPoints::InsertPoint() is invoked.
- `vtkIdType = obj.InsertNextPoint (double x[3])` - Insert a given point into the octree and return the point index. Note that InitPointInsertion() should have been called prior to this function. In addition, IsInsertedPoint() should have been called in advance to ensure that the given point has not been inserted unless point duplication is allowed (in this case, this function invovles a repeated leaf container location). vtkPoints::InsertNextPoint() is invoked.