IPointIndex.hpp

#pragma once
 
#include "DM/config.hpp"
#include "DM/Handle.hpp"
#include "DM/Iterator.hpp"
#include "DM/IPoint.hpp"
#include "DM/IPointIndexLeaf.hpp"
#include "DM/IAddInfoStatistics.hpp"
#include "DM/IIndexStats.hpp"
#include "DM/IControlObject.hpp"
 
DM_NAMESPACE_BEGIN
 
/// \brief Interface to a point index object managing the point objects within the datamanager
class DM_API IPointIndex : public ObjectBase
{
 public:
  // Iterator typedefs ============================================================================
  typedef ConstIterator<IPoint>       const_iterator_point;     ///< Point iterator
  typedef InsertIterator<IPoint>      insert_iterator_point;    ///< Point insert iterator (used in searchPoint functions)
 
  typedef ConstIterator<IPointIndexLeaf>     const_iterator_leaf;     ///< Leaf iterator
  typedef Iterator<IPointIndexLeaf>          iterator_leaf;           ///< Leaf iterator
  typedef InsertIterator<IPointIndexLeaf>    insert_iterator_leaf;    ///< Leaf insert iterator (used in searchPoint functions)
 
protected:
  virtual ~IPointIndex() {}
 
public:
  // General memeber functions ====================================================================
  virtual BoxHandle getLimit() const = 0;       ///< get points based bounding box
  virtual BoxHandle getIndexLimit() const = 0;  ///< get index based bounding box (if no index bounding available the points based bounding box is returned)
 
  virtual int64_t sizePoint()   const=0;
  
  virtual int64_t sizeLeaf()    const=0;
 
  virtual double  estimatePointDensity(bool fastEstimation = true) const = 0;
 
  // Iterator function ============================================================================
  virtual const_iterator_point beginPoint(IteratorOrder order = IteratorOrder::internal) const = 0;
  virtual const_iterator_point endPoint(IteratorOrder order = IteratorOrder::internal) const = 0;
  
  virtual const_iterator_leaf beginLeaf(IteratorOrder order = IteratorOrder::internal)  const = 0;
  virtual const_iterator_leaf endLeaf(IteratorOrder order = IteratorOrder::internal)    const = 0;
  virtual iterator_leaf       beginLeaf(IteratorOrder order = IteratorOrder::internal)        = 0;
  virtual iterator_leaf       endLeaf(IteratorOrder order = IteratorOrder::internal)          = 0;
 
  virtual const_iterator_leaf beginLeaf(FilterHandle filter, WindowHandle limits = WindowHandle())  const = 0;
  virtual const_iterator_leaf endLeaf(FilterHandle filter, WindowHandle limits = WindowHandle())    const = 0;
 
  virtual PointIndexLeafHandle getLeaf(const_iterator_point &it) = 0;
  virtual PointIndexLeafHandle getLeaf(int64_t leafId) = 0;
 
  // access functions ============================================================================
  virtual PointHandle getPoint(int64_t id) const = 0; ///< get point by id (if the id doesn't exist an empty handle is returned)
 
  // Spatial access functions =====================================================================
  virtual void searchPoint(const IWindow &win, insert_iterator_point &insIt,        bool includeRightBoundary = true, ControlObjectHandle control = ControlObjectHandle()) = 0;
  virtual void searchPoint(const IBox &box,    insert_iterator_point &insIt,        bool includeRightBoundary = true, ControlObjectHandle control = ControlObjectHandle()) = 0;
  virtual void searchPoint(const IPolygon &p,  insert_iterator_point &insIt) = 0;
  virtual void searchPoint(const ICircle &c,   insert_iterator_point &instIt) = 0;
  virtual void searchPoint(const ISphere &s,   insert_iterator_point &instIt) = 0;
  virtual void searchPoint(const ICylinder &c, insert_iterator_point &instIt) = 0;
 
  virtual void searchPoint(const IWindow &win, insert_iterator_point &insIt,  insert_iterator_leaf &insLeaf, bool includeRightBoundary = true) = 0;
  virtual void searchPoint(const IBox &box,    insert_iterator_point &insIt,  insert_iterator_leaf &insLeaf, bool includeRightBoundary = true) = 0;
  virtual void searchPoint(const IPolygon &p,  insert_iterator_point &insIt,  insert_iterator_leaf &insLeaf) = 0;
  virtual void searchPoint(const ICircle &c,   insert_iterator_point &instIt, insert_iterator_leaf &insLeaf) = 0;
  virtual void searchPoint(const ISphere &s,   insert_iterator_point &instIt, insert_iterator_leaf &insLeaf) = 0;
  virtual void searchPoint(const ICylinder &c, insert_iterator_point &instIt, insert_iterator_leaf &insLeaf) = 0;
 
  /// \brief k nearest neighbour search 
  /// potentially slow for the overall point index object. consider building a local kd tree -> IPointIndexLeaf
  ///
  /// \param[in]  nnCount       number of k neighbour to find
  /// \param[in]  queryPt       base point for the neighbour search
  /// \param[in]  instIt        insert iterator for collecting the found geometry objects
  /// \param[in]  maxDistance   maximum distance (not squared distance) for finding geometry objects (use -1 disabling the distance limit)
  /// \param[in]  selectionMode nearest, quadrant or octant based nn selection
  /// \return distance to the furthest found geometry object or 'maxDistance' in case on object was found
  virtual double searchPoint(int nnCount, const IPoint &queryPt, insert_iterator_point &instIt, 
                        double maxDistance = -1, SelectionMode selectionMode = SelectionMode::nearest) = 0;
  /// \brief k nearest neighbour search 
  /// potentially slow for the overall point index object. consider building a local kd tree -> IPointIndexLeaf
  ///
  /// \param[in]  nnCount       number of k neighbour to find
  /// \param[in]  queryPt       base point for the neighbour search
  /// \param[in]  instIt        insert iterator for collecting the found geometry objects
  /// \param[in]  insLeaf       leaf inster iterator for storing all leafs for which nearest neighbour points where returned
  /// \param[in]  maxDistance   maximum distance (not squared distance) for finding geometry objects (use -1 disabling the distance limit)
  /// \param[in]  selectionMode nearest, quadrant or octant based nn selection
  /// \return distance to the furthest found geometry object or 'maxDistance' in case on object was found
  virtual double searchPoint(int nnCount, const IPoint &queryPt, insert_iterator_point &instIt, insert_iterator_leaf &insLeaf, 
                        double maxDistance = -1, SelectionMode selectionMode = SelectionMode::nearest) = 0;
 
  // Memory consumption functions  ================================================================
  virtual int64_t sizePointCache() const = 0;
  virtual void sizePointCache(int64_t size) = 0;
 
  // efficiency function. access leaf properties without loading point data into memory ===========
  virtual BoxHandle getLimit(const const_iterator_leaf &it) const = 0;
  virtual BoxHandle getIndexLimit(const const_iterator_leaf &it) const = 0;
  virtual int64_t   sizePoint(const const_iterator_leaf &it) const = 0;
  virtual int64_t   id(const const_iterator_leaf &it) const = 0;
 
  virtual AddInfoStatisticsHandle getAddInfoStatistics() const = 0;
  virtual AddInfoStatisticsHandle getLeafAddInfoStatistics(const const_iterator_leaf &it) const = 0;
  virtual IndexStatsHandle        getIndexStatistics() const = 0;
 
  // get all leafs within window ==================================================================
  virtual void searchLeaf(const IWindow &win, insert_iterator_leaf &insLeaf, bool includeRightBoundary = true) = 0;
 
  //drop all freeable memory object
  virtual void freeMemory() const = 0;
 
  //gives the pointindex a hint for a possible tile size
  virtual void tileSizeHint(double tilesize) = 0;
};
 
typedef Handle< IPointIndex > PointIndexHandle;
 
DM_NAMESPACE_END