IDatamanager.hpp

#ifndef DM_IDATAMANAGER_HPP_INCLUDED
#define DM_IDATAMANAGER_HPP_INCLUDED

#ifdef _MSC_VER
  #pragma once
#endif

#include "DM/config.hpp"
#include "DM/Handle.hpp"
#include "DM/IGeometry.hpp"
#include "DM/IPoint.hpp"
#include "DM/IPolyline.hpp"
#include "DM/IWindow.hpp"
#include "DM/IBox.hpp"
#include "DM/IPolygon.hpp"
#include "DM/IFile.hpp"
#include "DM/Iterator.hpp"
#include "DM/IPointIndex.hpp"
#include "DM/IPolylineIndex.hpp"
#include "DM/IRaster.hpp"
#include "DM/IParameterSet.hpp"
#include "DM/IAddInfoStatistics.hpp"
#include "DM/BoundaryOption.hpp"
#include "DM/IDatamanagerHeader.hpp"
#include "DM/IHistogramSet.hpp"
#include "DM/IFilter.hpp"
#include "DM/IOverview.hpp"
#include "DM/IText.hpp"

#include "DM/IControlObject.hpp"

#include "DM/AutoLink.hpp" //enable autolink

DM_NAMESPACE_BEGIN

class IImport;
class IExport;

/// \brief Interface to an Datamanager (ODM) object
/**
  Datamanager objects are the central objects that can be managed by the DMlib. It allows managing
  huge geometry data sets with fast spatial access. For efficiency reasons points and other geometry 
  objects (lines, polygons, etc.) are managed by different spatial indices. The interface gives access
  to the point index (see getPointIndex) and the other spatial index (see getPolylineIndex stores
  line and polygon data) separately or via the datamanager interface itself in a wrapped manner.

  When create a datamanger instance, the datamanager uses a set of standard parameter which are appropriate
  for most data sets. However, it is possible to change these values using a ParameterSets object. The following
  parameters are supported:
  
  Name                  | type    |  default  |  Comment
  ----------------------|---------|-----------|-------------------------------------------
  StoreOrder            | bool    |  false    |  Flag if the order should be stored
  PointsInMemory        | int     | 8*200000  | Number of points that are kept in memory
  AverageTilePointCount |  int    |  200000   | Average point count per tile
  TileSize              |  double |   auto    | Tile size for tiling mode

*/
class DM_API IDatamanager : public ObjectBase
{
public:
  /// Create a new datamanager instance from an existing ODM file or by creating an ODM file
  /// \param[in] filename       odm filename (incl. extension) 
  /// \param[in] openIfExists   if true the existing ODM is opened, otherwise a new ODM file is created (which overrides a possible exisitng ODM file)
  /// \param[in] readOnly       if true the ODM is opened in read only mode, which never stores any modification made to the ODM object in memory
  /// \param[in] threadSafety   if true a thread safe instance of the ODM is created. Otherwise a standard instance is created which may provide a bit better performance
  static IDatamanager* New(const char *filename, bool openIfExists = true, bool readOnly = false, bool threadSafety = true);
  static IDatamanager* New(const char *filename, const IParameterSet &, bool openIfExists = true, bool readOnly = false, bool threadSafety = true);

  /// Create a new datamanager instance from an existing ODM file or by creating an ODM file
  /** Don't use this function outside OPALS, since it requires a pointer to an OPALS module instance as a first parameter
  */
  static IDatamanager* New(void *instance, const char *filename, bool openIfExists = true, bool readOnly = false, bool threadSafety = true);
  static IDatamanager* New(void *instance, const char *filename, const IParameterSet &, bool openIfExists = true, bool readOnly = false, bool threadSafety = true);

  /// Load an existing datamanager file (Convenient wrapper for IDatamanager::New)
  /// \param[in] filename       odm filename (incl. extension) 
  /// \param[in] readOnly       if true the ODM is opened in read only mode, which never stores any modification made to the ODM object in memory
  /// \param[in] threadSafety   if true a thread safe instance of the ODM is created. Otherwise a standard instance is created which may provide a bit better performance
  static IDatamanager* load(const char *filename, bool readOnly = false, bool threadSafety = true);
  /// Create a new datamanager file (Convenient wrapper for IDatamanager::New)
  /// \param[in] filename       odm filename (incl. extension) 
  /// \param[in] threadSafety   if true a thread safe instance of the ODM is created. Otherwise a standard instance is created which may provide a bit better performance
  static IDatamanager* create(const char *filename, bool threadSafety = true);


  /// checks if the odm file exists
  /// \param[in] filename  valid names are <name>.odm, <name>.odm.dat and <name>.odm.idx
  /// \return true if odm files exists, otherwise false
  static bool existsODM(const char *filename); 
  /// checks if the specified file is a valid odm file (requires read access)
  /// \param[in] filename  valid names are <name>.odm, <name>.odm.dat and <name>.odm.idx
  /// \return true if valid odm file. otherwise false
  static bool isValidODM(const char *filename); 
  static bool isValidODM(const char *filename, TextHandle &errorMsg); 

  /// get the full header information of an odm, without actually openning the odm (much faster)
  static DatamanagerHeaderHandle getHeaderODM(const char *filename); 
  /// get the limits of an odm, without actually openning the odm (internally uses getHeaderODM)
  static BoxHandle getLimitODM(const char *filename); 
  /// get the overview object of an odm, without actually openning the odm
  static OverviewHandle getOverviewODM(const char *filename); 

  static void SetPointInMemoryLimit(unsigned limit);


  // Iterator typedefs ============================================================================
  typedef ConstIterator<IGeometry> const_iterator_geometry;  ///< Geometry iterator
  typedef ConstIterator<IPoint>    const_iterator_point;     ///< Point iterator
  typedef ConstIterator<IPolyline> const_iterator_line;      ///< Polyline iterator
  typedef ConstIterator<IFile>     const_iterator_file;      ///< File iterator

  typedef InsertIterator<IGeometry> insert_iterator_geometry;  ///< Geometry insert iterator (used in searchGeometry function)
  typedef InsertIterator<IPoint>    insert_iterator_point;     ///< Point insert iterator (used in searchPoint functions)
  typedef InsertIterator<IPolyline> insert_iterator_line;      ///< Polyline insert iterator (used in searchPolyline functions)


protected:
  virtual ~IDatamanager() {}

public:
  // General memeber functions ====================================================================
  virtual BoxHandle getLimit() const = 0;

  virtual int64_t sizeGeometry()  const = 0;
  virtual int64_t sizePoint()     const = 0;
  virtual int64_t sizePolyline()      const = 0;
  virtual int64_t sizePolylinePoint() const = 0;
  virtual int64_t sizePolygon()       const = 0;
  virtual int64_t sizePolygonPoint()  const = 0;

  /*virtual void clear()=0;*/

  virtual DatamanagerHeaderHandle getHeader()  const = 0;

  virtual bool storesOrder() const = 0;
  virtual bool threadSafe() const = 0;
  virtual int  indexDim() const = 0;

  virtual PointIndexHandle    getPointIndex() = 0;
  virtual PolylineIndexHandle getPolylineIndex()  = 0;

  /// Get the boundary polygon of the data set
  /// \param[in] type         type of boundary output polygon (\see BoundaryOption::Type)
  /// \param[in] alphaRadius  in case of alpha shapes a radius can be specified (if radius is zero, the smalles possible radius is select to result as sinlge part alpha shape)
  /// The approximative boundaries are computed on the fly, whereas the exact outlines needed to be computed using opalsBounds
  virtual PolygonHandle getBoundary(BoundaryOption::Type type, double alphaRadius = 0.) const = 0;
  virtual bool          getBoundaryFlag(BoundaryOption::Type type) const = 0;


  /// access object by its id
  virtual GeometryHandle getGeometry(int64_t id) const = 0;

  // Overview matrix function =====================================================================
  /// Get a matrix of point counts in native resolution
  virtual UnsignedRasterHandle getDensityOverview(double &xLowerLeftCellCenter, double &yLowerLeftCellCenter, double &cellSize) = 0;
  virtual DoubleRasterHandle   getZMatrixOverview(double &xLowerLeftCellCenter, double &yLowerLeftCellCenter, double &cellSize, const double &nullValue = 0) = 0;
  /*virtual void getDensityMatrix(const GdxLimit2d &limit, unsigned int rows, unsigned int cols, int *mat) const=0; 
  virtual void getPointPolylinesMatrix(const GdxLimit2d &limit, unsigned int rows, unsigned int cols, int *mat) const=0; 
  virtual void getFileMatrix(const GdxLimit2d &limit, unsigned int rows, unsigned int cols, int *mat) const=0; 
  */

  // IO functions =================================================================================
  virtual void save() = 0;

  // Import / Export functions ====================================================================
  virtual bool doImport( IImport &impObj, DM::ControlObjectHandle control = ControlObjectHandle() ) = 0;
  virtual bool doExport( IExport &expObj, bool restoreOrder = false, DM::ControlObjectHandle control = ControlObjectHandle() ) = 0;
  virtual bool doExport( IExport &expObj, BoxHandle box, DM::ControlObjectHandle control = ControlObjectHandle() ) = 0;
  

  // Iterator function ============================================================================
  virtual const_iterator_geometry beginGeometry(E_IteratorOrder order = eORDER_INTERNAL) const = 0;
  virtual const_iterator_geometry endGeometry(E_IteratorOrder order = eORDER_INTERNAL) const = 0;

  virtual const_iterator_point beginPoint(E_IteratorOrder order = eORDER_INTERNAL) const = 0;
  virtual const_iterator_point endPoint(E_IteratorOrder order = eORDER_INTERNAL) const = 0;

  virtual const_iterator_line beginPolyline(E_IteratorOrder order = eORDER_INTERNAL) const = 0;
  virtual const_iterator_line endPolyline(E_IteratorOrder order = eORDER_INTERNAL) const = 0;

  virtual const_iterator_file beginFile() const=0;
  virtual const_iterator_file endFile() const=0;

  virtual PointIndexLeafHandle getPointIndexLeaf(const_iterator_geometry &it) = 0;

  // Spatial access functions =====================================================================
  virtual void searchGeometry(const IWindow &win, insert_iterator_geometry &instIt, bool includeRightBoundary = true) = 0;
  virtual void searchGeometry(const IBox &box,    insert_iterator_geometry &instIt, bool includeRightBoundary = true) = 0;
  virtual void searchGeometry(const IPolygon &p,  insert_iterator_geometry &instIt) = 0;

  virtual void searchPoint(const IWindow &win,  insert_iterator_point &instIt, bool includeRightBoundary = true) = 0;
  virtual void searchPoint(const IBox &box,     insert_iterator_point &instIt, bool includeRightBoundary = true) = 0;
  virtual void searchPoint(const IPolygon &p,   insert_iterator_point &instIt) = 0;
  
  virtual void searchPolyline (const IWindow &win, insert_iterator_line  &instIt, bool includeRightBoundary = true) = 0;
  virtual void searchPolyline (const IBox   &box,  insert_iterator_line  &instIt, bool includeRightBoundary = true) = 0;
  virtual void searchPolyline (const IPolygon &p,  insert_iterator_line  &instIt) = 0;

  // Edit function ================================================================================
  /// adds point to the datamanager (secure that addinfo of the point is NOT linked to another datamanager or
  /// set the cloneAddInfo flag)
  /// \param[in]  p             point object
  /// \param[in]  cloneAddInfo  flag if the addinfo object should be cloned, before adapting 
  ///                           file and layer id in addinfo object
  /// \param[in]  fileId        the point is inserted into the given file (it is assumed that the given file exists) or 
  ///                           to the default file in case of -1 
  /// \param[in]  layerId       the point is inserted into the given layer of the given file (layer and file entry must exist) or 
  ///                           to the default layer in case of -1 
  /// \return point id
  virtual int64_t addPoint(const IPoint &p, bool cloneAddInfo = true, int fileId = -1, int layerId = -1 ) = 0;

  /// replace an existing point within the datamanager (the point is identified by its id)
  /// \param[in]  p              point object
  /// \param[in]  attributeOnly  flag if complete point should be replace (i.e. coordinates have changed) or only the attribute object is updated 
  virtual void replacePoint(const IPoint &p, bool attributeOnly = false) = 0;      

  /// remove a point from from the datamanager by its id
  /// \param[in]  id             point id
  virtual void deletePoint(int64_t id) = 0;         


  /// adds a polyline to the datamanager (secure that addinfo of the polyline is NOT linked to another datamanager or
  /// set the cloneAddInfo flag)
  /// \param[in]  l             polyline object
  /// \param[in]  cloneAddInfo  flag if the addinfo object should be cloned, before adapting 
  ///                           file and layer id in addinfo object
  /// \param[in]  fileId        the point is inserted into the given file (it is assumed that the given file exists) or 
  ///                           to the default file in case of -1 
  /// \param[in]  layerId       the point is inserted into the given layer of the given file (layer and file entry must exist) or 
  ///                           to the default layer in case of -1 
  /// \return polyline id
  virtual int64_t addPolyline(const IPolyline &l, bool cloneAddInfo = true, int fileId = -1, int layerId = -1 ) = 0;

  /// replace an existing polyline within the datamanager (the object is identified by its id)
  /// \param[in]  l              polyline object
  /// \param[in]  attributeOnly  flag if complete line should be replace (i.e. coordinates have changed) or only the attribute objects is updated 
  virtual void replacePolyline(const IPolyline &l, bool attributeOnly = false) = 0;      

  /// remove a polyline object from from the datamanager by its id
  /// \param[in]  id            polyline id
  virtual void deletePolyline(int64_t id) = 0;         




  /// adds a polygon to the datamanager (secure that addinfo of the polygon is NOT linked to another datamanager or
  /// set the cloneAddInfo flag)
  /// \param[in]  p             polygon object
  /// \param[in]  cloneAddInfo  flag if the addinfo object should be cloned, before adapting 
  ///                           file and layer id in addinfo object
  /// \param[in]  fileId        the point is inserted into the given file (it is assumed that the given file exists) or 
  ///                           to the default file in case of -1 
  /// \param[in]  layerId       the point is inserted into the given layer of the given file (layer and file entry must exist) or 
  ///                           to the default layer in case of -1 
  /// \return polyline id
  virtual int64_t addPolygon(const IPolygon &p, bool cloneAddInfo = true, int fileId = -1, int layerId = -1 ) = 0;

  /// replace an existing polygon within the datamanager (the object is identified by its id)
  /// \param[in]  p              polygon object
  /// \param[in]  attributeOnly  flag if complete polygon should be replace (i.e. coordinates have changed) or only the attribute objects is updated 
  virtual void replacePolygon(const IPolygon &p, bool attributeOnly = false) = 0;      

  /// remove a polygon object from from the datamanager by its id
  /// \param[in]  id            polygon id
  virtual void deletePolygon(int64_t id) = 0;         


  /*virtual void beginUpdate(void)=0;
  virtual void endUpdate(void)=0;

  virtual int addFile (const GdxFile &f)=0;           
  virtual int64_t addPoint(const GdxPoint &p)=0;     
  virtual int64_t addPolyline (const GdxPolyline &l)=0; 

  virtual void deleteFile (unsigned int ngfilid)=0;    
  virtual void deletePoint(int64_t ngpntid)=0;         
  virtual void deletePolyline (int64_t nglinid)=0;         

  virtual void replaceFile (const GdxFile &f, bool attributsOnly)=0;       
  virtual void replacePoint(const GdxPoint &p, bool attributsOnly)=0;      
  virtual void replacePolyline (const GdxPolyline  &l, bool attributsOnly)=0;     */

  ///get the statistics of all addinfo objects
  virtual AddInfoStatisticsHandle getAddInfoStatistics() const = 0;

  /// get filename of manager;
  virtual const char * getFilename() const = 0;
  
  /// output statistics parameter how the data are actually stored on disk
  virtual void outputDiskmanagerStatistics() const = 0;

  /// drop all freeable memory object
  virtual void freeMemory() const = 0;

  /// mark the odm that processing should be interrupted
  virtual void interrupt(bool inter = true) = 0;
  /// check if the interrupt flag was set
  virtual bool isInterrupted() const = 0;

  virtual bool isManagerCorrupt() const = 0;

  /// \brief get histograms of all attributes described by the layout
  virtual HistogramSetHandle getHistogramSet(const IAddInfoLayout &layout, int maxDistinctValues = 1000, FilterHandle filter = FilterHandle()) = 0;

  // Coordinate reference system function ================================================================================
  /// \brief get the coordinate reference system as a WKT string
  virtual const char* getCRS() const = 0;
  /// \brief set the coordinate reference system from a WKT string
  virtual void setCRS(const char *crs) = 0;
};

typedef Handle< IDatamanager > DatamanagerHandle;

DM_NAMESPACE_END

#endif // DM_IDATAMANAGER_HPP_INCLUDED