New features: New collection types

There are 4 new collection types provided as template classes:

• NCollection_Vector

• NCollection_UBTree

• NCollection_SparseArray

• NCollection_CellFilter

Type Vector:

Implemented internally as a list of arrays of the same size. Its properties:

- Direct (constant-time) access to members like in Array1 type; data are allocated in compact blocks, this provides faster iteration.

- Can grow without limits, like List, Stack or Queue types.

- Once having the size LEN, it cannot be reduced to any size less than LEN – there is no operation of removal of items.

Insertion in a Vector-type class is made by two methods:

- SetValue(ind, theValue) – array-type insertion

where ind is the index of the inserted item, can be any non-negative number. If it is greater than or equal to Length(), then the vector is enlarged (its Length() grows).

- Append(theValue) – list-type insertion

equivalent to myVec.SetValue(myVec.Length(), theValue) – incrementing the size of the collection.

Other essential properties coming from List and Array1 type collections:

- Like in List, the method Clear() destroys all contained objects and releases the allocated memory.

- Like in Array1, the methods Value() and ChangeValue() return a contained object by index. Also, these methods have the form of overloaded operator ().

Type UBTree:

The name of this type stands for “Unbalanced Binary Tree”. It stores the members in a binary tree of overlapped bounding objects (boxes or else).

Once the tree of boxes of geometric objects is constructed, the algorithm is capable of fast geometric selection of objects. The tree can be easily updated by adding to it a new object with bounding box.

The time of adding to the tree of one object is O(log(N)), where N is the total number of objects, so the time of building a tree of N objects is O(N(log(N)). The search time of one object is O(log(N)).

Defining various classes inheriting NCollection_UBTree::Selector we can perform various kinds of selection over the same b-tree object

The object may be of any type allowing copying. Among the best suitable solutions there can be a pointer to an object, handled object or integer index of object inside some collection. The bounding object may have any dimension and geometry. The minimal interface of TheBndType (besides public empty and copy constructor and operator =) used in UBTree algorithm is as the following:

class MyBndType

{

public:

inline void Add (const MyBndType& other);

// Updates me with other bounding type instance

inline Standard_Boolean IsOut (const MyBndType& other) const;

// Classifies other bounding type instance relatively me

inline Standard_Real SquareExtent() const;

// Computes the squared maximal linear extent of me.

// (For box it is the squared diagonal of box)

};

This interface is implemented in types of Bnd package: Bnd_Box, Bnd_Box2d, Bnd_B2x, Bnd_B3x.

To select objects you need to define a class derived from UBTree::Selector that should redefine the necessary virtual methods to maintain the selection condition. Usually this class instance is also used to retrieve selected objects after search.

The class UBTreeFiller is used to randomly populate an UBTree instance. The quality of a tree is better (considering the speed of searches) if objects are added to it in a random order trying to avoid the addition of a chain of nearby objects one following another.

Instantiation of UBTreeFiller collects objects to be added, and then adds them at once to the given UBTree instance in a random order using the Fisher-Yates algorithm.

Below is the sample code that creates an instance of NCollection_UBTree indexed by 2D boxes (Bnd_B2f), then a selection is performed returning the objects whose bounding boxes contain the given 2D point.

typedef NCollection_UBTree<MyData, Bnd_B2f> UBTree;

typedef NCollection_List<MyData> ListOfSelected;

//! Tree Selector type

class MyTreeSelector : public UBTree::Selector

{

public:

/**

* Constructor. Initializes the selection criterion (e.g., a point)

*/

MyTreeSelector (const gp_XY& thePnt) : myPnt(thePnt) {}

/**

* Get the list of selected objects.

*/

const ListOfSelected& ListAccepted () const

{ return myList; }

/**

* Bounding box rejection - definition of virtual method.

* @return True if theBox is outside the selection criterion

*/

Standard_Boolean Reject (const Bnd_B2f& theBox) const

{ return theBox.IsOut(myPnt); }

/**

* Redefined from the base class. Called when the bounding of theData

* conforms to the selection criterion. This method updates myList.

*/

Standard_Boolean Accept (const MyData& theData)

{ myList.Append(theData); }

private:

gp_XY myPnt;

ListOfSelected myList;

};

. . .

// Create a UBTree instance and fill it with data, each data item having

// the corresponding 2D box.

UBTree aTree;

NCollection_UBTreeFiller <MyData, Bnd_B2f> aTreeFiller(aTree);

for(;;) {

const MyData& aData = …;

const Bnd_B2d& aBox = aData.GetBox();

aTreeFiller.Add(aData, aBox);

}

aTreeFiller.Fill();

. . .

// Perform selection based on ‘aPoint2d’

MyTreeSelector aSel(aPoint2d);

aTree.Select(aSel);

const ListOfSelected = aSel.ListAccepted();

Type SparseArray:

This type has almost the same features as Vector but it allows to store items having scattered indices. In Vector, if you set an item with index 1000000, the container will allocate memory for all items with indices in the range 0-1000000. In SparseArray, only one small block of items will be reserved that contains the item with index 1000000.

This class can be also seen as equivalence of DataMap<int,TheItemType> with the only one practical difference: it can be much less memory-expensive if items are small (e.g. Integer or Handle).

This type has both interfaces of DataMap and Vector to access items.

Type CellFilter:

This class represents a data structure for sorting geometric objects in n-dimensional space into cells, with associated algorithm for fast checking of coincidence (overlapping, intersection, etc.) with other objects. It can be considered as a functional alternative to UBTree, as in the best case it provides the direct access to an object like in an n-dimensional array, while search with UBTree provides logarithmic law access time.