Open CASCADE Technology
7.3.1.dev

#include <NCollection_CellFilter.hxx>
Data Structures  
struct  Cell 
struct  ListNode 
Public Types  
typedef TYPENAME Inspector::Target  Target 
typedef TYPENAME Inspector::Point  Point 
Public Member Functions  
NCollection_CellFilter (const Standard_Integer theDim, const Standard_Real theCellSize=0, const Handle< NCollection_IncAllocator > &theAlloc=0)  
Constructor; initialized by dimension count and cell size. More...  
NCollection_CellFilter (const Standard_Real theCellSize=0, const Handle< NCollection_IncAllocator > &theAlloc=0)  
Constructor when dimenstion count is known at compilation time. More...  
void  Reset (Standard_Real theCellSize, const Handle< NCollection_IncAllocator > &theAlloc=0) 
Clear the data structures, set new cell size and allocator. More...  
void  Reset (NCollection_Array1< Standard_Real > &theCellSize, const Handle< NCollection_IncAllocator > &theAlloc=0) 
Clear the data structures and set new cell sizes and allocator. More...  
void  Add (const Target &theTarget, const Point &thePnt) 
Adds a target object for further search at a point (into only one cell) More...  
void  Add (const Target &theTarget, const Point &thePntMin, const Point &thePntMax) 
Adds a target object for further search in the range of cells defined by two points (the first point must have all coordinates equal or less than the same coordinate of the second point) More...  
void  Remove (const Target &theTarget, const Point &thePnt) 
Find a target object at a point and remove it from the structures. For usage of this method "operator ==" should be defined for Target. More...  
void  Remove (const Target &theTarget, const Point &thePntMin, const Point &thePntMax) 
Find a target object in the range of cells defined by two points and remove it from the structures (the first point must have all coordinates equal or less than the same coordinate of the second point). For usage of this method "operator ==" should be defined for Target. More...  
void  Inspect (const Point &thePnt, Inspector &theInspector) 
Inspect all targets in the cell corresponding to the given point. More...  
void  Inspect (const Point &thePntMin, const Point &thePntMax, Inspector &theInspector) 
Inspect all targets in the cells range limited by two given points (the first point must have all coordinates equal or less than the same coordinate of the second point) More...  
Protected Member Functions  
void  resetAllocator (const Handle< NCollection_IncAllocator > &theAlloc) 
Reset allocator to the new one. More...  
void  add (const Cell &theCell, const Target &theTarget) 
Add a new target object into the specified cell. More...  
void  iterateAdd (int idim, Cell &theCell, const Cell &theCellMin, const Cell &theCellMax, const Target &theTarget) 
Internal addition function, performing iteration for adjacent cells by one dimension; called recursively to cover all dimensions. More...  
void  remove (const Cell &theCell, const Target &theTarget) 
Remove the target object from the specified cell. More...  
void  iterateRemove (int idim, Cell &theCell, const Cell &theCellMin, const Cell &theCellMax, const Target &theTarget) 
Internal removal function, performing iteration for adjacent cells by one dimension; called recursively to cover all dimensions. More...  
void  inspect (const Cell &theCell, Inspector &theInspector) 
Inspect the target objects in the specified cell. More...  
void  iterateInspect (int idim, Cell &theCell, const Cell &theCellMin, const Cell &theCellMax, Inspector &theInspector) 
Inspect the target objects in the specified range of the cells. More...  
Protected Attributes  
Standard_Integer  myDim 
Handle< NCollection_BaseAllocator >  myAllocator 
NCollection_Map< Cell >  myCells 
NCollection_Array1< Standard_Real >  myCellSize 
Friends  
Standard_Integer  HashCode (const Cell &theCell, const Standard_Integer theUpperBound) 
Returns hash code for the given cell, in the range [1, theUpperBound]. More...  
Standard_Boolean  IsEqual (const Cell &aCell1, const Cell &aCell2) 
A data structure for sorting geometric objects (called targets) in ndimensional space into cells, with associated algorithm for fast checking of coincidence (overlapping, intersection, etc.) with other objects (called here bullets).
Description
The algorithm is based on hash map, thus it has linear time of initialization (O(N) where N is number of cells covered by added targets) and constanttime search for one bullet (more precisely, O(M) where M is number of cells covered by the bullet).
The idea behind the algorithm is to separate each coordinate of the space into equalsize cells. Note that this works well when cell size is approximately equal to the characteristic size of the involved objects (targets and bullets; including tolerance eventually used for coincidence check).
Usage
The target objects to be searched are added to the tool by methods Add(); each target is classified as belonging to some cell(s). The data on cells (list of targets found in each one) are stored in the hash map with key being cumulative index of the cell by all coordinates. Thus the time needed to find targets in some cell is O(1) * O(number of targets in the cell).
As soon as all the targets are added, the algorithm is ready to check for coincidence. To find the targets coincident with any given bullet, it checks all the candidate targets in the cell(s) covered by the bullet object (methods Inspect()).
The methods Add() and Inspect() have two flavours each: one accepts single point identifying one cell, another accept two points specifying the range of cells. It should be noted that normally at least one of these methods is called as for range of cells: either due to objects having non zero size, or in order to account for the tolerance when objects are points.
The set of targets can be modified during the process: new targets can be added by Add(), existing targets can be removed by Remove().
Implementation
The algorithm is implemented as template class, thus it is capable to work with objects of any type. The only argument of the template should be the specific class providing all necessary features required by the algorithm:
method Coord() returning value of the ith coordinate of the point:
static Standard_Real Coord (int i, const Point& thePnt);
Note that index i is from 0 to Dimension1.
method IsEqual() used by Remove() to identify objects to be removed:
Standard_Boolean IsEqual (const Target& theT1, const Target& theT2);
method Inspect() performing necessary actions on the candidate target object (usially comparison with the currently checked bullet object):
NCollection_CellFilter_Action Inspect (const Target& theObject);
The returned value can be used to command CellFilter to remove the inspected item from the current cell; this allows to exclude the items that has been processed and are not needed any more in further search (for better performance).
Note that method Inspect() can be const and/or virtual.
typedef TYPENAME Inspector::Point NCollection_CellFilter< Inspector >::Point 
typedef TYPENAME Inspector::Target NCollection_CellFilter< Inspector >::Target 

inline 
Constructor; initialized by dimension count and cell size.
Note: the cell size must be ensured to be greater than maximal coordinate of the involved points divided by INT_MAX, in order to avoid integer overflow of cell index.
By default cell size is 0, which is invalid; thus if default constructor is used, the tool must be initialized later with appropriate cell size by call to Reset() Constructor when dimension count is unknown at compilation time.

inline 
Constructor when dimenstion count is known at compilation time.

inline 
Adds a target object for further search at a point (into only one cell)

inline 
Adds a target object for further search in the range of cells defined by two points (the first point must have all coordinates equal or less than the same coordinate of the second point)

inlineprotected 
Add a new target object into the specified cell.

inline 
Inspect all targets in the cell corresponding to the given point.

inline 
Inspect all targets in the cells range limited by two given points (the first point must have all coordinates equal or less than the same coordinate of the second point)

inlineprotected 
Inspect the target objects in the specified cell.

inlineprotected 
Internal addition function, performing iteration for adjacent cells by one dimension; called recursively to cover all dimensions.

inlineprotected 
Inspect the target objects in the specified range of the cells.

inlineprotected 
Internal removal function, performing iteration for adjacent cells by one dimension; called recursively to cover all dimensions.

inline 
Find a target object at a point and remove it from the structures. For usage of this method "operator ==" should be defined for Target.

inline 
Find a target object in the range of cells defined by two points and remove it from the structures (the first point must have all coordinates equal or less than the same coordinate of the second point). For usage of this method "operator ==" should be defined for Target.

inlineprotected 
Remove the target object from the specified cell.

inline 
Clear the data structures, set new cell size and allocator.

inline 
Clear the data structures and set new cell sizes and allocator.

inlineprotected 
Reset allocator to the new one.

friend 
Returns hash code for the given cell, in the range [1, theUpperBound].
theCell  the cell object which hash code is to be computed 
theUpperBound  the upper bound of the range a computing hash code must be within 

friend 

protected 

protected 

protected 

protected 