[Developers] DataPointSet: create and use

[Bert Bril]

Hi again,

Some more info about the DataPointSet (see include/General/datapointset.h).

DataPointSets are ideal for holding vectors of data and their position  
in space. The positions can be unrelated (user picks, random points),  
or within bodies or between horizons in a polygon – and so forth. The  
relation between the points is not stored in the set, but you can do  
that yourself:
* The grouping mechanism allows 16k different groups. If you put 3  
separate bodies in the DPS, you can give them 3 group numbers. Note  
that negative and 0 are not available, so use 1, 2, ....
* You can add your own columns. For example to store a distance to a  
well, or a node number of an EarthModel object.

DataPointSet has quite a few constructors, amongst which an 'empty'  
constructor:
DataPointSet(bool is2d,bool minimal=false);
You can designate a DPS to be 'minimal', that saves 12 or 16 (when 2D)  
bytes per data vector. You will not have precise positioning, and no  
selection/grouping tools. Otherwise, the overhead per data vector is  
on average: crl + Z +  offsx/y + sel/grp + trcnr(2D) = 20 or 24 bytes.  
For every inline a TypeSet of crosslines is allocated, too.

Thus, the DataPointSet is a BinIDValueSet with a couple of 'fixed'  
columns, which are not counted if you ask for the nrCols(). The  
initPVDS() adds the columns; it is called in every constructor:

if ( !minimal_ )
{
     data_.add( new DataColDef("X Offset") );
     data_.add( new DataColDef("Y Offset") );
     data_.add( new DataColDef("Selection status") );
}
if ( is2d_ )
     data_.add( new DataColDef("Trace number") );

X and Y offset store only the the offset between the mathematical  
BinID center and the actual horizontal position, the selection status  
is a combination of:
* selection flag
* 'removed' flag
* group number (must be > 0)

An empty or initially filled DPS can be changed. To add a new column,  
you have to make sure all already existing vectors are resized, so use  
the PosVecDataSet::add(DataColDef*):
dps.dataSet().add( new DataColDef("My col") );

Adding rows (vectors) is also possible (e.g. DataPointSet::addRow()),  
as long as you remember to call 'dataChanged()' before trying to use  
it. The main reason for this dataChanged() is that we want to have  
indexed access into the DataPointSet. This is not available in the  
BinIDValueSet, which only has an iterator. dataChanged iterates  
through the rows and makes a linear table of the positions in the  
BinIDValuesSet. That gives us the best of both sorted sets with quick  
searching and the ease of use of a simple array-like data structure.

There are many access and set functions for parts of a vector/row. All  
data for a row can be obtained in the form of a DataPointSet::DataRow.  
When going through a set, and when you need to do more than just look  
at the position or one data value, this can be very convenient to use.


/Bert

-- 
-- Bert Bril / OpendTect developer at dGB
-- Nijverheidstraat 11-2, 7511 JM Enschede, The Netherlands
-- mailto:Bert.Bril at opendtect.org , http://opendtect.org
-- Tel: +31 534315155 , Fax: +31 534315104