IExportLAS.hpp

#ifndef DM_IO_EXPORT_LAS_HPP_INCLUDED
#define DM_IO_EXPORT_LAS_HPP_INCLUDED

#ifdef _MSC_VER
  #pragma once
#endif

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

#include "DM/ColumnTypes.hpp"
#include "DM/IO/IExport.hpp"
#include "DM/Array.hpp"

//boost
#include <boost/any.hpp>

DM_NAMESPACE_BEGIN

class DM_API IExportLAS : public virtual IExport
{
public:
  static IExportLAS* New( const char *file, FilterHandle filter = FilterHandle(), 
                          unsigned versionMajor = 1, unsigned versionMinor = 1, unsigned pointDataFormat = 0,
                          unsigned extraPointDataLength = 0, ControlObjectHandle control = ControlObjectHandle(),
                          double invalidHeight = DBL_MAX, double coordPrecision = -1.0 );

protected:
  virtual ~IExportLAS() {}

public:
  typedef std::pair<boost::any,boost::any>  MinMax;
  typedef Array<MinMax,2>                   MinMax2;
  typedef Array<MinMax,3>                   MinMax3;

  typedef Array<double,2> double2;
  typedef Array<double,3> double3;

  // functions to retrieve empty defaults
  static MinMax  undefMinMax(); 
  static MinMax2 undefMinMax2();  
  static MinMax3 undefMinMax3();

  static double  undefDouble();
  static double2 undefDouble2();
  static double3 undefDouble3();

  /// \name EXTRA_BYTES / LASattributes
  /// LAS v.1.4+ allows for the definition of the semantic of extra bytes following each point record:
  /** name, description, data type, number of elements [1 3], NO_DATA value; scale==1.0, offset==0.0. */
  //@{
  // By default, no extra bytes are exported.
  // Calls to exportExtraBytes(.) result in the definition of an EXTRA_BYTES VLR in the header,
  //   and the export of according extra bytes following the bytes defined by the point record format for each point record.
  // unred = offset + scale * red | unred(uced) = actual value; red(uced) = value stored in LAS file
  // invalidValue is used as is (i.e. without application of offset/scale) if the attribute for a certain point is undefined or NULL
  // defaults:
  //   invalidValue is undefined in header; undefined attributes are stored with value T() i.e. default-instantiated lasType
  //   lasName is equal to colName(ngCol)
  //   lasDescription is the NG-attribute-comment, as specified in NG_AddInfoColumns.hpp
  //   lasType is the type of the NG-attribute. If offset and/or scale are used, then lasType defaults to double.

  // Offset and/or scale are estimated if not given explicitly.
  // Estimated offset and/or scale are only used if
  //   - necessary to avoid numerical over-/underflows and/or
  //   - helpful to reduce loss of precision.
  // Passing the actual range of values of the respective attribute via \param minMax (e.g. queried from NG_AddInfoStatistics),
  // and passing type information of user-defined attributes via \param ngType helps to better determine if offset and/or scale are necessary.
  // If only ngType is known (which is always the case for predefined attributes), but not minMax, then the range of values is assumed to be the range of representable values of ngType.
  // If neither ngType, nor minMax are known, then neither offset, nor scale are used. Users then must make sure that the actual range of attribute values to be stored
  // fits into lasType. Otherwise, a range over-/underflow exception will be thrown.

  // predefined attributes
  // with 1 element
  virtual void exportExtraBytes( ColumnSemantic::Type col,
                         const boost::any &invalidValue = boost::any(),
                         const char* lasName = 0,
                         const char* lasDescription = 0,
                         ColumnType::Type lasType = ColumnType::count,
                         const MinMax &minMax = undefMinMax(),
                         const double &scale  = undefDouble(),
                         const double &offset = undefDouble() ) = 0;
  
  // with 2 elements
  virtual void exportExtraBytes( ColumnSemantic::Type col1, ColumnSemantic::Type col2,
                         const boost::any &invalidValue = boost::any(),
                         const char* lasName = 0,
                         const char* lasDescription = 0,
                         ColumnType::Type lasType = ColumnType::count,
                         const MinMax2 &minMax = undefMinMax2(),
                         const double2 &scale  = undefDouble2(), 
                         const double2 &offset = undefDouble2() ) = 0;
  // with 3 elements
  virtual void exportExtraBytes( ColumnSemantic::Type col1, ColumnSemantic::Type col2, ColumnSemantic::Type col3,
                         const boost::any &invalidValue = boost::any(),
                         const char* lasName = 0,
                         const char* lasDescription = 0,
                         ColumnType::Type lasType = ColumnType::count,
                         const MinMax3 &minMax = undefMinMax3(),
                         const double3 &scale  = undefDouble3(), 
                         const double3 &offset = undefDouble3() ) = 0;

  // custom attributes, or predefined attributes accessed by their names (not by their enums)
  // with 1 element
  virtual void exportExtraBytes( const char* ngName,
                         ColumnType::Type lasType,
                         const boost::any &invalidValue = boost::any(),
                         const char* lasName = 0,
                         const char* lasDescription = 0,
                         ColumnType::Type ngType = ColumnType::count,
                         const MinMax &minMax = undefMinMax(),
                         const double &scale  = undefDouble(),
                         const double &offset = undefDouble() ) = 0;
  // with 2 elements
  virtual void exportExtraBytes( const char* ngName1, const char* ngName2,
                         ColumnType::Type lasType,
                         const boost::any &invalidValue = boost::any(),
                         const char* lasName = 0,
                         const char* lasDescription = 0,
                         ColumnType::Type ngType = ColumnType::count,
                         const MinMax2 &minMax = undefMinMax2(),
                         const double2 &scale  = undefDouble2(), 
                         const double2 &offset = undefDouble2() ) = 0;
  // with 3 elements
  virtual void exportExtraBytes( const char* ngName1, const char* ngName2, const char* ngName3,
                         ColumnType::Type lasType,
                         const boost::any &invalidValue = boost::any(),
                         const char* lasName = 0,
                         const char* lasDescription = 0,
                         ColumnType::Type ngType = ColumnType::count,
                         const MinMax3 &minMax = undefMinMax3(),
                         const double3 &scale  = undefDouble3(), 
                         const double3 &offset = undefDouble3() ) = 0;

  // remove any definitions of extra bytes.
  // Make sure to call this function before exportExtraBytes(.), if a header is passed in the constructor.
  virtual void clearExtraBytes() = 0;
  //}@

};

typedef Handle<IExportLAS> ExportLASHandle;

DM_NAMESPACE_END

#endif //DM_IO_EXPORT_LAS_HPP_INCLUDED