IDatamanager.hpp
1 #pragma once
2 
3 #include "DM/config.hpp"
4 #include "DM/Handle.hpp"
5 #include "DM/IGeometry.hpp"
6 #include "DM/IPoint.hpp"
7 #include "DM/IPolyline.hpp"
8 #include "DM/IWindow.hpp"
9 #include "DM/IBox.hpp"
10 #include "DM/IPolygon.hpp"
11 #include "DM/IFile.hpp"
12 #include "DM/Iterator.hpp"
13 #include "DM/IPointIndex.hpp"
14 #include "DM/IPolylineIndex.hpp"
15 #include "DM/IRaster.hpp"
16 #include "DM/IParameterSet.hpp"
17 #include "DM/IAddInfoStatistics.hpp"
18 #include "DM/BoundaryOption.hpp"
19 #include "DM/IDatamanagerHeader.hpp"
20 #include "DM/IHistogramSet.hpp"
21 #include "DM/IFilter.hpp"
22 #include "DM/IOverview.hpp"
23 #include "DM/IText.hpp"
24 #include "DM/ICalculator.hpp"
25 
26 #include "DM/IControlObject.hpp"
27 
28 #include "DM/AutoLink.hpp" //enable autolink
29 
30 DM_NAMESPACE_BEGIN
31 
32 class IImport;
33 class IExport;
34 enum struct ExportError;
35 enum struct ImportError;
36 
37 /// \brief Interface to an Datamanager (ODM) object
38 /**
39  Datamanager objects are the central objects that can be managed by the DMlib. It allows managing
40  huge geometry data sets with fast spatial access. For efficiency reasons points and other geometry
41  objects (lines, polygons, etc.) are managed by different spatial indices. The interface gives access
42  to the point index (see getPointIndex) and the other spatial index (see getPolylineIndex stores
43  line and polygon data) separately or via the datamanager interface itself in a wrapped manner.
44 
45  When create a datamanger instance, the datamanager uses a set of standard parameter which are appropriate
46  for most data sets. However, it is possible to change these values using a ParameterSets object. The following
47  parameters are supported:
48 
49  Name | type | default | Comment
50  ----------------------|---------|-----------|-------------------------------------------
51  StoreOrder | bool | false | Flag if the order should be stored
52  PointsInMemory | int | 8*200000 | Number of points that are kept in memory
53  AverageTilePointCount | int | 200000 | Average point count per tile
54  TileSize | double | auto | Tile size for tiling mode
55 
56 */
57 class DM_API IDatamanager : public ObjectBase
58 {
59 public:
60  /// Create a new datamanager instance from an existing ODM file or by creating an ODM file
61  /// \param[in] filename odm filename (incl. extension)
62  /// \param[in] openIfExists if true the existing ODM is opened, otherwise a new ODM file is created (which overrides a possible exisitng ODM file)
63  /// \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
64  /// \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
65  static IDatamanager* New(const char *filename, bool openIfExists = true, bool readOnly = false, bool threadSafety = true);
66  static IDatamanager* New(const char *filename, const IParameterSet &, bool openIfExists = true, bool readOnly = false, bool threadSafety = true);
67 
68  /// Create a new datamanager instance from an existing ODM file or by creating an ODM file
69  /** Don't use this function outside OPALS, since it requires a pointer to an OPALS module instance as a first parameter
70  */
71  static IDatamanager* New(void *instance, const char *filename, bool openIfExists = true, bool readOnly = false, bool threadSafety = true);
72  static IDatamanager* New(void *instance, const char *filename, const IParameterSet &, bool openIfExists = true, bool readOnly = false, bool threadSafety = true);
73 
74  /// Load an existing datamanager file (Convenient wrapper for IDatamanager::New)
75  /// \param[in] filename odm filename (incl. extension)
76  /// \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
77  /// \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
78  static IDatamanager* load(const char *filename, bool readOnly = false, bool threadSafety = true);
79  /// Create a new datamanager file (Convenient wrapper for IDatamanager::New)
80  /// \param[in] filename odm filename (incl. extension)
81  /// \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
82  static IDatamanager* create(const char *filename, bool threadSafety = true);
83 
84 
85  /// checks if the odm file exists
86  /// \param[in] filename valid names are <name>.odm, <name>.odm.dat and <name>.odm.idx
87  /// \return true if odm files exists, otherwise false
88  static bool existsODM(const char *filename);
89  /// checks if the specified file is a valid odm file (requires read access)
90  /// \param[in] filename valid names are <name>.odm, <name>.odm.dat and <name>.odm.idx
91  /// \return true if valid odm file. otherwise false
92  static bool isValidODM(const char *filename);
93  static bool isValidODM(const char *filename, TextHandle &errorMsg);
94 
95  /// get the full header information of an odm, without actually openning the odm (much faster)
96  static DatamanagerHeaderHandle getHeaderODM(const char *filename);
97  /// get the limits of an odm, without actually openning the odm (internally uses getHeaderODM)
98  static BoxHandle getLimitODM(const char *filename);
99  /// get the overview object of an odm, without actually openning the odm
100  static OverviewHandle getOverviewODM(const char *filename);
101 
102  static void SetPointInMemoryLimit(unsigned limit);
103 
104 
105  // Iterator typedefs ============================================================================
106  typedef ConstIterator<IGeometry> const_iterator_geometry; ///< Geometry iterator
107  typedef ConstIterator<IPoint> const_iterator_point; ///< Point iterator
108  typedef ConstIterator<IPolyline> const_iterator_line; ///< Polyline iterator
109  typedef ConstIterator<IFile> const_iterator_file; ///< File iterator
110 
111  typedef InsertIterator<IGeometry> insert_iterator_geometry; ///< Geometry insert iterator (used in searchGeometry function)
112  typedef InsertIterator<IPoint> insert_iterator_point; ///< Point insert iterator (used in searchPoint functions)
113  typedef InsertIterator<IPolyline> insert_iterator_line; ///< Polyline insert iterator (used in searchPolyline functions)
114 
115 
116 protected:
117  virtual ~IDatamanager() {}
118 
119 public:
120  // General memeber functions ====================================================================
121  virtual BoxHandle getLimit() const = 0;
122 
123  virtual int64_t sizeGeometry() const = 0;
124  virtual int64_t sizePoint() const = 0;
125  virtual int64_t sizePolyline() const = 0;
126  virtual int64_t sizePolylinePoint() const = 0;
127  virtual int64_t sizePolygon() const = 0;
128  virtual int64_t sizePolygonPoint() const = 0;
129 
130  /*virtual void clear()=0;*/
131 
132  virtual DatamanagerHeaderHandle getHeader() const = 0;
133 
134  virtual bool storesOrder() const = 0;
135  virtual bool threadSafe() const = 0;
136  virtual int indexDim() const = 0;
137  virtual bool readOnly() const = 0;
138 
139  virtual PointIndexHandle getPointIndex() = 0;
140  virtual PolylineIndexHandle getPolylineIndex() = 0;
141 
142  /// Get the boundary polygon of the data set
143  /// \param[in] type type of boundary output polygon (\see BoundaryOption::Type)
144  /// \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)
145  /// The approximative boundaries are computed on the fly, whereas the exact outlines needed to be computed using opalsBounds
146  virtual PolygonHandle getBoundary(BoundaryOption type, double alphaRadius = 0.) const = 0;
147  virtual bool getBoundaryFlag(BoundaryOption type) const = 0;
148 
149 
150  /// access object by its id
151  virtual GeometryHandle getGeometry(int64_t id) const = 0;
152 
153  // Overview matrix function =====================================================================
154  /// Get a matrix of point counts in native resolution
155  virtual UnsignedRasterHandle getDensityOverview(double &xLowerLeftCellCenter, double &yLowerLeftCellCenter, double &cellSize) = 0;
156  virtual DoubleRasterHandle getZMatrixOverview(double &xLowerLeftCellCenter, double &yLowerLeftCellCenter, double &cellSize, const double &nullValue = 0) = 0;
157  /*virtual void getDensityMatrix(const GdxLimit2d &limit, unsigned int rows, unsigned int cols, int *mat) const=0;
158  virtual void getPointPolylinesMatrix(const GdxLimit2d &limit, unsigned int rows, unsigned int cols, int *mat) const=0;
159  virtual void getFileMatrix(const GdxLimit2d &limit, unsigned int rows, unsigned int cols, int *mat) const=0;
160  */
161 
162  // IO functions =================================================================================
163  virtual void save() = 0;
164 
165  // Import / Export functions ====================================================================
166  /// \brief import from import object
167  /// \param[in] impObj import object
168  /// \param[in] control control object for handling progress
169  /// \param[in] preserveFileIdOrder in case of odm import object, this variable allows preserving the order of the file ids of the import odm.
170  /// if false, the file ids will be assigned by import occurrence. do not use import filter in conjunction with
171  /// the flag being set to true.
172  virtual ImportError doImport( IImport &impObj, DM::ControlObjectHandle control = ControlObjectHandle(), bool preserveFileIdOrder = false ) = 0;
173  virtual ExportError doExport( IExport &expObj, bool restoreOrder = false, DM::ControlObjectHandle control = ControlObjectHandle() ) = 0;
174  virtual ExportError doExport( IExport &expObj, BoxHandle box, DM::ControlObjectHandle control = ControlObjectHandle() ) = 0;
175  virtual ExportError doExport(IExport &expObj, bool ascending, DM::AddInfoLayoutHandle &layout, DM::ControlObjectHandle control = ControlObjectHandle()) = 0;
176 
177  // Iterator function ============================================================================
178  virtual const_iterator_geometry beginGeometry(IteratorOrder order = IteratorOrder::internal) const = 0;
179  virtual const_iterator_geometry endGeometry(IteratorOrder order = IteratorOrder::internal) const = 0;
180 
181  virtual const_iterator_point beginPoint(IteratorOrder order = IteratorOrder::internal) const = 0;
182  virtual const_iterator_point endPoint(IteratorOrder order = IteratorOrder::internal) const = 0;
183 
184  virtual const_iterator_line beginPolyline(IteratorOrder order = IteratorOrder::internal) const = 0;
185  virtual const_iterator_line endPolyline(IteratorOrder order = IteratorOrder::internal) const = 0;
186 
187  virtual const_iterator_file beginFile() const=0;
188  virtual const_iterator_file endFile() const=0;
189 
190  virtual PointIndexLeafHandle getPointIndexLeaf(const_iterator_geometry &it) = 0;
191 
192  // Spatial access functions =====================================================================
193  virtual void searchGeometry(const IWindow &win, insert_iterator_geometry &instIt, bool includeRightBoundary = true) = 0;
194  virtual void searchGeometry(const IBox &box, insert_iterator_geometry &instIt, bool includeRightBoundary = true) = 0;
195  virtual void searchGeometry(const IPolygon &p, insert_iterator_geometry &instIt) = 0;
196 
197  virtual void searchPoint(const IWindow &win, insert_iterator_point &instIt, bool includeRightBoundary = true, DM::ControlObjectHandle control = ControlObjectHandle()) = 0;
198  virtual void searchPoint(const IBox &box, insert_iterator_point &instIt, bool includeRightBoundary = true, DM::ControlObjectHandle control = ControlObjectHandle()) = 0;
199  virtual void searchPoint(const IPolygon &p, insert_iterator_point &instIt) = 0;
200 
201  virtual void searchPolyline (const IWindow &win, insert_iterator_line &instIt, bool includeRightBoundary = true) = 0;
202  virtual void searchPolyline (const IBox &box, insert_iterator_line &instIt, bool includeRightBoundary = true) = 0;
203  virtual void searchPolyline (const IPolygon &p, insert_iterator_line &instIt) = 0;
204 
205  // Edit function ================================================================================
206  /// adds point to the datamanager (secure that addinfo of the point is NOT linked to another datamanager or
207  /// set the cloneAddInfo flag)
208  /// \param[in] p point object
209  /// \param[in] cloneAddInfo flag if the addinfo object should be cloned, before adapting
210  /// file and layer id in addinfo object
211  /// \param[in] fileId the point is inserted into the given file (it is assumed that the given file exists) or
212  /// to the default file in case of -1
213  /// \param[in] layerId the point is inserted into the given layer of the given file (layer and file entry must exist) or
214  /// to the default layer in case of -1
215  /// \return point id
216  virtual int64_t addPoint(const IPoint &p, bool cloneAddInfo = true, int fileId = -1, int layerId = -1 ) = 0;
217 
218  /// replace an existing point within the datamanager (the point is identified by its id)
219  /// \param[in] p point object
220  /// \param[in] attributeOnly flag if complete point should be replace (i.e. coordinates have changed) or only the attribute object is updated
221  virtual void replacePoint(const IPoint &p, bool attributeOnly = false) = 0;
222 
223  /// remove a point from from the datamanager by its id
224  /// \param[in] id point id
225  virtual void deletePoint(int64_t id) = 0;
226 
227 
228  /// adds a polyline to the datamanager (secure that addinfo of the polyline is NOT linked to another datamanager or
229  /// set the cloneAddInfo flag)
230  /// \param[in] l polyline object
231  /// \param[in] cloneAddInfo flag if the addinfo object should be cloned, before adapting
232  /// file and layer id in addinfo object
233  /// \param[in] fileId the point is inserted into the given file (it is assumed that the given file exists) or
234  /// to the default file in case of -1
235  /// \param[in] layerId the point is inserted into the given layer of the given file (layer and file entry must exist) or
236  /// to the default layer in case of -1
237  /// \return polyline id
238  virtual int64_t addPolyline(const IPolyline &l, bool cloneAddInfo = true, int fileId = -1, int layerId = -1 ) = 0;
239 
240  /// replace an existing polyline within the datamanager (the object is identified by its id)
241  /// \param[in] l polyline object
242  /// \param[in] attributeOnly flag if complete line should be replace (i.e. coordinates have changed) or only the attribute objects is updated
243  virtual void replacePolyline(const IPolyline &l, bool attributeOnly = false) = 0;
244 
245  /// remove a polyline object from from the datamanager by its id
246  /// \param[in] id polyline id
247  virtual void deletePolyline(int64_t id) = 0;
248 
249 
250 
251 
252  /// adds a polygon to the datamanager (secure that addinfo of the polygon is NOT linked to another datamanager or
253  /// set the cloneAddInfo flag)
254  /// \param[in] p polygon object
255  /// \param[in] cloneAddInfo flag if the addinfo object should be cloned, before adapting
256  /// file and layer id in addinfo object
257  /// \param[in] fileId the point is inserted into the given file (it is assumed that the given file exists) or
258  /// to the default file in case of -1
259  /// \param[in] layerId the point is inserted into the given layer of the given file (layer and file entry must exist) or
260  /// to the default layer in case of -1
261  /// \return polyline id
262  virtual int64_t addPolygon(const IPolygon &p, bool cloneAddInfo = true, int fileId = -1, int layerId = -1 ) = 0;
263 
264  /// replace an existing polygon within the datamanager (the object is identified by its id)
265  /// \param[in] p polygon object
266  /// \param[in] attributeOnly flag if complete polygon should be replace (i.e. coordinates have changed) or only the attribute objects is updated
267  virtual void replacePolygon(const IPolygon &p, bool attributeOnly = false) = 0;
268 
269  /// remove a polygon object from from the datamanager by its id
270  /// \param[in] id polygon id
271  virtual void deletePolygon(int64_t id) = 0;
272 
273 
274  /*virtual void beginUpdate(void)=0;
275  virtual void endUpdate(void)=0;
276 
277  virtual int addFile (const GdxFile &f)=0;
278  virtual int64_t addPoint(const GdxPoint &p)=0;
279  virtual int64_t addPolyline (const GdxPolyline &l)=0;
280 
281  virtual void deleteFile (unsigned int ngfilid)=0;
282  virtual void deletePoint(int64_t ngpntid)=0;
283  virtual void deletePolyline (int64_t nglinid)=0;
284 
285  virtual void replaceFile (const GdxFile &f, bool attributsOnly)=0;
286  virtual void replacePoint(const GdxPoint &p, bool attributsOnly)=0;
287  virtual void replacePolyline (const GdxPolyline &l, bool attributsOnly)=0; */
288 
289  ///get the statistics of all addinfo objects
290  virtual AddInfoStatisticsHandle getAddInfoStatistics() const = 0;
291 
292  /// get filename of manager;
293  virtual const char * getFilename() const = 0;
294 
295  /// output statistics parameter how the data are actually stored on disk
296  virtual void outputDiskmanagerStatistics() const = 0;
297 
298  /// drop all freeable memory object
299  virtual void freeMemory() const = 0;
300 
301  /// mark the odm that processing should be interrupted
302  virtual void interrupt(bool inter = true) = 0;
303  /// check if the interrupt flag was set
304  virtual bool isInterrupted() const = 0;
305 
306  virtual bool isManagerCorrupt() const = 0;
307 
308  /// \brief get histograms of all attributes described by the layout
309  virtual HistogramSetHandle getHistogramSet(const IAddInfoLayout &layout, int maxDistinctValues = 1000, FilterHandle filter = FilterHandle()) = 0;
310 
311  // Coordinate reference system function ================================================================================
312  /// \brief get the coordinate reference system as a WKT string
313  virtual const char* getCRS() const = 0;
314  /// \brief set the coordinate reference system from a WKT string
315  virtual void setCRS(const char *crs) = 0;
316 
317  // prepare the layout manager to avoid rare multi thread crashes ======================================================
318  virtual void prepareLayout(const IAddInfoLayout &layout, bool readOnly) const = 0;
319  virtual void prepareLayout(const ICalculator &calc) const = 0;
320 };
321 
322 typedef Handle< IDatamanager > DatamanagerHandle;
323 
324 DM_NAMESPACE_END
DM::ConstIterator
Definition: Iterator.hpp:96
DM::IDatamanager::insert_iterator_point
InsertIterator< IPoint > insert_iterator_point
Point insert iterator (used in searchPoint functions)
Definition: IDatamanager.hpp:112
DM::IWindow
2d window object
Definition: IWindow.hpp:11
DM::ExportError
ExportError
Definition: M/c++_api/inc/DM/IO/IExport.hpp:26
DM::IAddInfoLayout
AddInfo layouts describe a set of attributes that can be attached to geometry objects.
Definition: IAddInfoLayout.hpp:18
DM::IDatamanager::const_iterator_point
ConstIterator< IPoint > const_iterator_point
Point iterator.
Definition: IDatamanager.hpp:107
DM::ICalculator
Generic calculator for evaluating formulas or manipulating objects based on the OPALS generic filter ...
Definition: ICalculator.hpp:8
DM::BoundaryOption
BoundaryOption
Definition: BoundaryOption.hpp:9
DM::IImport
base class for importing original geometry data file
Definition: M/c++_api/inc/DM/IO/IImport.hpp:45
DM::IBox
Geometry object describing a 3d box.
Definition: IBox.hpp:11
DM::ImportError
ImportError
Definition: M/c++_api/inc/DM/IO/IImport.hpp:20
DM::IDatamanager::const_iterator_line
ConstIterator< IPolyline > const_iterator_line
Polyline iterator.
Definition: IDatamanager.hpp:108
DM::IPolygon
interface to a 2.5d polygon of arbitrary complexity
Definition: IPolygon.hpp:33
DM::StaticHandle
Definition: Handle.hpp:427
DM::IteratorOrder
IteratorOrder
Definition: Iterator.hpp:9
DM::IParameterSet
Object can store a set of named parameter of different type.
Definition: IParameterSet.hpp:11
DM::IDatamanager::const_iterator_file
ConstIterator< IFile > const_iterator_file
File iterator.
Definition: IDatamanager.hpp:109
DM::IPolyline
Definition: IPolyline.hpp:14
DM::InsertIterator
Definition: Iterator.hpp:183
DM::IExport
base class for exporting original geometry data file
Definition: M/c++_api/inc/DM/IO/IExport.hpp:50
DM::IDatamanager::insert_iterator_geometry
InsertIterator< IGeometry > insert_iterator_geometry
Geometry insert iterator (used in searchGeometry function)
Definition: IDatamanager.hpp:111
DM::IDatamanager::insert_iterator_line
InsertIterator< IPolyline > insert_iterator_line
Polyline insert iterator (used in searchPolyline functions)
Definition: IDatamanager.hpp:113
DM::IDatamanager::const_iterator_geometry
ConstIterator< IGeometry > const_iterator_geometry
Geometry iterator.
Definition: IDatamanager.hpp:106
DM::IDatamanager
Interface to an Datamanager (ODM) object.
Definition: IDatamanager.hpp:57
DM::Handle
Smart pointer class using reference counting with support for DM objects (see ObjectBase)
Definition: Handle.hpp:75
DM::ObjectBase
Definition: M/c++_api/inc/DM/ObjectBase.hpp:8
DM::IPoint
3d point object
Definition: IPoint.hpp:14