M/c++_api/inc/DM/IO/IImport.hpp

#pragma once
 
#include "DM/config.hpp"
#include "DM/AutoLink.hpp" //enable autolink
 
#include "DM/IControlObject.hpp"
#include "DM/IFilter.hpp"
#include "DM/IAddInfoLayout.hpp"
#include "DM/IAddInfoStatistics.hpp"
#include "DM/IHistogramSet.hpp"
#include "DM/IRaster.hpp"
 
#include "DM/IO/IFileHeader.hpp"
 
#include "DM/Log.hpp"
#include "DM/IO/DataFormat.hpp"
 
DM_NAMESPACE_BEGIN
 
enum struct ImportError
{
  demoLimitExceeded = -9,     ///< demo limit of the DM exceeded
  unknownFormat,              ///< unknown import file format
  memoryOverflow,             ///< memory overflow occurred
  importStreamNotAccessible,  ///< import stream is not accessible
  headerContentsErroneous,    ///< the file header content is erroneous 
  readingData,                ///< general error while reading data
  importStreamClosed,         ///< import stream was already closed
  endOfStreamReached,         ///< end of input stream is reached
  interrupted,                ///< import was interrupted 
  successful = 1              ///< no error occured
};
 
DM_API const char* toString(ImportError error);   ///< get a textual description of an import error (this function is not thread safe)
 
enum struct PolygonMerging
{
  safe = 0, ///< incremental merge of polygon parts (slow but robust)
  fast = 1  ///< build polygon object at once (fast but fails in case of topological incorrect polygon parts)
};
 
class DM_API IDatamanager;
 
/// \brief base class for importing original geometry data file
class DM_API IImport : public ObjectBase 
{
public:
  /// \brief creates new import object
  /**
    interface for importing geometry objects for different file formats. if not specified the function automatically detects the file format
    based on the file content.
    \param[in]  file                filename
    \param[in]  format              defines file format or use null for auto detection
    \param[in]  filter              filter for subselecting/transforming objects during import
    \param[in]  control             control object for retrieving import progress information
    \param[in]  collectHdrContents  flag for explicitly collecting header information while importing
    \param[in]  maxBulkPoints       chunk size for bulk points being imported at once
    \param[in]  defaultLayout       default attribute layout for objects while importing (attribute stored within the file, will be extended to this layout)
  */
  static IImport* New(const char *file, DataFormat format, FilterHandle filter = FilterHandle(), ControlObjectHandle control = ControlObjectHandle(),
    bool collectHdrContents = false, unsigned maxBulkPoints = 1000, AddInfoLayoutHandle defaultLayout = AddInfoLayoutHandle());
 
  /// \brief creates new import object
  /**
    interface for importing geometry objects for different file formats. if not specified the function automatically detects the file format
    based on the file content. 
    \param[in]  instance            ptr to parent module instance
    \param[in]  file                filename
    \param[in]  format              defines file format or use null for auto detection
    \param[in]  filter              filter for subselecting/transforming objects during import 
    \param[in]  control             control object for retrieving import progress information
    \param[in]  collectHdrContents  flag for explicitly collecting header information while importing
    \param[in]  maxBulkPoints       chunk size for bulk points being imported at once 
    \param[in]  defaultLayout       default attribute layout for objects while importing (attribute stored within the file, will be extended to this layout)
  */
  static IImport* New( void *instance, const char *file, DataFormat format, FilterHandle filter = FilterHandle(), ControlObjectHandle control = ControlObjectHandle(), 
                       bool collectHdrContents = false, unsigned maxBulkPoints = 1000, AddInfoLayoutHandle defaultLayout = AddInfoLayoutHandle() );
 
  /// deprecated odm import creation functions (use IImportODM::New instead)
  static IImport* NewODM( Handle< IDatamanager > manager, bool restoreOrder, FilterHandle filter = FilterHandle(), ControlObjectHandle control = ControlObjectHandle(),
                          bool collectHdrContents = false, unsigned maxBulkPoints = 1000 );
  /// deprecated odm import creation functions (use IImportODM::New instead)
  static IImport* NewODM( IDatamanager &manager, bool restoreOrder, FilterHandle filter = FilterHandle(), ControlObjectHandle control = ControlObjectHandle(),
                          bool collectHdrContents = false, unsigned maxBulkPoints = 1000 );
 
  static IImport* NewGDAL( const char *file, FilterHandle filter = FilterHandle(), ControlObjectHandle control = ControlObjectHandle(), 
                          bool collectHdrContents = false, unsigned maxBulkPoints = 1000,
                          unsigned bandNumber = 1, const char *driver = 0 );
 
  static IImport* NewWinput( const char *file, bool binary, ColumnSemantic structIdAddInfoCol = ColumnSemantic::null, 
                          ColumnSemantic wnpCodeAddInfoCol = ColumnSemantic::null, 
                          FilterHandle filter = FilterHandle(), ControlObjectHandle control = ControlObjectHandle(), 
                          bool collectHdrContents = false, unsigned maxBulkPoints = 1000,
                          AddInfoLayoutHandle layout = AddInfoLayoutHandle() );
 
 
  struct InvalidObjectStatistic {
    long long polygonsInvalidOrientation; ///< number of polygons that are orientated incorrectly
    long long polygonsSelfIntersecting;   ///< number of polygons that are self intersecting
  };
 
  /// Store the string representation of the import object in representation and return the length of representation.
  /// Memory for representation must be allocated externally.
  /// Pass a null pointer to query the length of representation only.
  /// Note that the stored representation may contain null bytes.
  virtual unsigned serialize( char *representation = 0 ) const = 0;
 
  /// Restore an import object from its string representation. Since the representation may contain null bytes, its size must also be specified.
  static IImport* unserialize( const char *representation, unsigned repSize );
 
protected:
  virtual ~IImport() {}
 
public:
  virtual void setControlObject(ControlObjectHandle control) = 0;
  virtual ControlObjectHandle getControlObject() const = 0;
 
  //get the file header object
  virtual FileHeaderHandle getHeader() const = 0;
 
  virtual void setFilter( FilterHandle filter ) = 0;
  virtual FilterHandle getFilter() const = 0;
 
  virtual void setPolygonMerging(PolygonMerging mode) = 0;
  virtual PolygonMerging getPolygonMerging() const = 0;
 
  /// Returns the filename 
  virtual const char* getFilename() const = 0;
 
  /// Returns the file format
  virtual DataFormat getFileFormat() const = 0;
 
  /// Set logging call back function
  virtual void logTo( LogFn logFn ) = 0;
 
  /// read the header in advance
  virtual bool readHeaderSeparately() = 0;
 
  /// after reading the header and befor calling the actual readNext function, necessary 
  /// public and internal attribute handling structures are build
  virtual void prepareForReading() = 0;
 
  /// read next object from import object
  virtual ImportError readNext(GeometryHandle &obj) = 0; 
 
  /// get a statistic of invalid geometries (after import)
  virtual InvalidObjectStatistic getInvalidGeometries() const = 0;
};
 
typedef Handle<IImport> ImportHandle;
 
/// \brief import data and extract/compute an attribute statistics 
DM_API AddInfoStatisticsHandle importStatistics(IImport &imp, ControlObjectHandle control = ControlObjectHandle());
/// \brief import data and extract/compute an attribute statistics including and estimation of the pointDensity (using the overview matrix of the odm)
DM_API AddInfoStatisticsHandle importStatistics(IImport &imp, double &pointDensity, ControlObjectHandle control = ControlObjectHandle());
 
/// \brief import data and extract/compute an attribute statistics and specified value frequencies
DM_API std::pair<AddInfoStatisticsHandle, HistogramSetHandle> importStatistics(IImport &imp, 
      const IAddInfoLayout &valueFrequencyLayout, int maxDistinctValues = 1000, ControlObjectHandle control = ControlObjectHandle());
/// \brief import data and extract/compute an attribute statistics, specified value frequencies and estimation of the pointDensity (using the overview matrix of the odm)
DM_API std::pair<AddInfoStatisticsHandle, HistogramSetHandle> importStatistics(IImport &imp, double &pointDensity, 
      const IAddInfoLayout &valueFrequencyLayout, int maxDistinctValues = 1000, ControlObjectHandle control = ControlObjectHandle());
 
/// \brief import data and extract overview rasters
DM_API void importStatistics(IImport &imp, AddInfoStatisticsHandle &impStat, double &pointDensity,
      UnsignedRasterHandle &densityOverview, DoubleRasterHandle &zmatrixOverview,
      double &xLowerLeftCellCenter, double &yLowerLeftCellCenter, double &cellSize, const double &nullValue,
      ControlObjectHandle control = ControlObjectHandle());
DM_API void importStatistics(IImport &imp, AddInfoStatisticsHandle &impStat, double &pointDensity, 
      UnsignedRasterHandle &densityOverview, DoubleRasterHandle &zmatrixOverview,
      double &xLowerLeftCellCenter, double &yLowerLeftCellCenter, double &cellSize, const double &nullValue,
      HistogramSetHandle &histo, const IAddInfoLayout &valueFrequencyLayout, int maxDistinctValues = 1000, 
      ControlObjectHandle control = ControlObjectHandle());
 
DM_NAMESPACE_END