vtkPointLocator - quickly locate points in 3-space

Super Class: vtkLocator

Description:

vtkPointLocator is a spatial search object to quickly locate points in 3D. vtkPointLocator works by dividing a specified region of space into a regular array of "rectangular" buckets, and then keeping a list of points that lie in each bucket. Typical operation involves giving a position in 3D and finding the closest point. vtkPointLocator has two distinct methods of interaction. In the first method, you supply it with a dataset, and it operates on the points in the dataset. In the second method, you supply it with an array of points, and the object operates on the array.

Caveats:

Many other types of spatial locators have been developed such as octrees and kd-trees. These are often more efficient for the operations described here.

See Also:

vtkCellPicker vtkPointPicker

Methods:

• ~vtkPointLocator ();
• vtkPointLocator *New ();
• char *GetClassName ();
• void PrintSelf (ostream &os, vtkIndent indent);
• vtkPointLocator ();
• void SetDivisions (int , int , int );
• void SetDivisions (int a[3]);
• int *GetDivisions ();
• void SetNumberOfPointsPerBucket (int );
• int GetNumberOfPointsPerBucket ();
• virtual int FindClosestPoint (float x[3]);
• int FindClosestPoint (float x, float y, float z);
• virtual int InitPointInsertion (vtkPoints *newPts, float bounds[6]);
• virtual int InitPointInsertion (vtkPoints *newPts, float bounds[6], int estSize);
• virtual void InsertPoint (int ptId, float x[3]);
• virtual int InsertNextPoint (float x[3]);
• int IsInsertedPoint (float x, float y, float z);
• virtual int IsInsertedPoint (float x[3]);
• virtual int InsertUniquePoint (float x[3], int &ptId);
• virtual int FindClosestInsertedPoint (float x[3]);
• virtual void FindClosestNPoints (int N, float x[3], vtkIdList *result);
• virtual void FindClosestNPoints (int N, float x, float y, float z, vtkIdList *result);
• virtual void FindDistributedPoints (int N, float x[3], vtkIdList *result, int M);
• virtual void FindDistributedPoints (int N, float x, float y, float z, vtkIdList *result, int M);
• virtual void FindPointsWithinRadius (float R, float x[3], vtkIdList *result);
• virtual void FindPointsWithinRadius (float R, float x, float y, float z, vtkIdList *result);
• void Initialize ();
• void FreeSearchStructure ();
• void BuildLocator ();
• void GenerateRepresentation (int level, vtkPolyData *pd);
• void GetBucketNeighbors (int ijk[3], int ndivs[3], int level);
• void GetOverlappingBuckets (float x[3], int ijk[3], float dist, int level);
• void GenerateFace (int face, int i, int j, int k, vtkPoints *pts, vtkCellArray *polys);

Detailed Method Descriptions:

• vtkPointLocator ();

Construct with automatic computation of divisions, averaging 25 points per bucket.

• void SetDivisions (int , int , int );
• void SetDivisions (int a[3]);
• int *GetDivisions ();

Set the number of divisions in x-y-z directions.

• void SetNumberOfPointsPerBucket (int );
• int GetNumberOfPointsPerBucket ();

Specify the average number of points in each bucket.

• virtual int FindClosestPoint (float x[3]);
• int FindClosestPoint (float x, float y, float z);

Given a position x, return the id of the point closest to it. Alternative method requires separate x-y-z values.

• virtual int InitPointInsertion (vtkPoints *newPts, float bounds[6]);
• virtual int InitPointInsertion (vtkPoints *newPts, float bounds[6], int estSize);

Initialize the point insertion process. The newPts is an object representing point coordinates into which incremental insertion methods place their data. Bounds are the box that the points lie in.

• virtual void InsertPoint (int ptId, float x[3]);

Incrementally insert a point into search structure with a particular index value. You should use the method IsInsertedPoint() to see whether this point has already been inserted (that is, if you desire to prevent dulicate points). Before using this method you must make sure that newPts have been supplied, the bounds has been set properly, and that divs are properly set. (See InitPointInsertion().)

• virtual int InsertNextPoint (float x[3]);

Incrementally insert a point into search structure. The method returns the insertion location (i.e., point id). You should use the method IsInsertedPoint() to see whether this point has already been inserted (that is, if you desire to prevent dulicate points). Before using this method you must make sure that newPts have been supplied, the bounds has been set properly, and that divs are properly set. (See InitPointInsertion().)

• int IsInsertedPoint (float x, float y, float z);
• virtual int IsInsertedPoint (float x[3]);

Determine whether point given by x[3] has been inserted into points list. Return id of previously inserted point if this is true, otherwise return -1.

• virtual int InsertUniquePoint (float x[3], int &ptId);

Determine whether point given by x[3] has been inserted into points list. Return 0 if point was already in the list, otherwise return 1. If the point was not in the list, it will be ADDED. In either case, the id of the point (newly inserted or not) is returned in the ptId argument. Note this combines the functionality of IsInsertedPoint() followed by a call to InsertNextPoint().

• virtual int FindClosestInsertedPoint (float x[3]);

Given a position x, return the id of the point closest to it. This method is used when performing incremental point insertion.

• virtual void FindClosestNPoints (int N, float x[3], vtkIdList *result);
• virtual void FindClosestNPoints (int N, float x, float y, float z, vtkIdList *result);

Find the closest N points to a position. This returns the closest N points to a position. A faster method could be created that returned N close points to a position, but neccesarily the exact N closest. The returned points are sorted from closest to farthest.

• virtual void FindDistributedPoints (int N, float x[3], vtkIdList *result, int M);
• virtual void FindDistributedPoints (int N, float x, float y, float z, vtkIdList *result, int M);

Find the closest points to a position such that each octent of space around the position contains at least N points. Loosely limit the search to a maximum number of points evalualted, M.

• virtual void FindPointsWithinRadius (float R, float x[3], vtkIdList *result);
• virtual void FindPointsWithinRadius (float R, float x, float y, float z, vtkIdList *result);

Find all points within a specified radius R of position x. The result is not sorted in any specific manner.

• void Initialize ();
• void FreeSearchStructure ();
• void BuildLocator ();
• void GenerateRepresentation (int level, vtkPolyData *pd);

See vtkLocator interface documentation.