mlModule.h

Go to the documentation of this file.

// **InsertLicense** code
//-------------------------------------------------------------------------
//-------------------------------------------------------------------------
#ifndef __mlModule_H
#define __mlModule_H

// ML-includes
#include "mlInitSystemML.h"
#include "mlRuntimeSubClass.h"
#include "mlBasics.h"
#include "mlBase.h"
#include "mlInputSubImageProperties.h"
#include "mlFields.h"
#include "mlFieldContainer.h"

#include "mlModuleInterfaces.h"
#include "mlProcessAllPagesHandler.h"
#include "mlPagedImage.h"

#include <mlMetaProfilePtr.h>


#define ML_ADD_FIELD(NAME_P, TYPE_P, VALUE_P) \
(static_cast<TYPE_P##Field*> (this->getFieldContainer()->addField(NAME_P, #TYPE_P, VALUE_P)));


class MLMemoryBlockHandle;

// Namespace ML. It is recommended that all ML classes and modules are in this
// name space to avoid collisions with types of other libraries.
ML_START_NAMESPACE

// ML-classes
class SubImage;
class PagedImage;
class ProcessAllPagesHandler;
#ifdef ML_DEPRECATED
class BaseOp;
class DummyOp;
#endif

//-------------------------------------------------------------------------

//-------------------------------------------------------------------------
class MLEXPORT Module : public FieldContainer
{

  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
  friend class Host;
  friend class PagedImage;
  friend class PageRequest;
  friend class TileRequest;
  friend class ModuleCalculateOutputImageHandler;
  friend class State;
  friend class ClassicHost;

  ML_DISALLOW_COPY_AND_ASSIGN(Module)

public:
  typedef void (*DiagnosisModuleStackCallback)(void*);

  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

public: Module(int numInputImages, int numOutputImages);

public: virtual ~Module();



  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

protected: void setOutputImageInplace(MLint outputIndex=0, MLint inputIndex=0);

protected: void unsetOutputImageInplace(MLint outputIndex=0);

public:    MLint getOutputImageInplace(MLint outputIndex=0) const;



protected: void setBypass(MLint outputIndex=0, MLint inputIndex=0);

public:    MLint getBypass(MLint outputIndex=0) const;

  enum THREAD_SUPPORT {
    NO_THREAD_SUPPORT = PagedImage::NO_THREAD_SUPPORT, 
    MULTITHREADED     = PagedImage::MULTITHREADED,     
    IO_THREAD         = PagedImage::IO_THREAD,         

    ML_CALCULATEOUTPUTSUBIMAGE_ON_STD_TYPES = PagedImage::MULTITHREADED, 
    ML_CALCULATEOUTPUTSUBIMAGE_ON_ALL_TYPES = PagedImage::MULTITHREADED, 
#ifdef ML_DEPRECATED
    CALC_OUTSUBIMAGE_ON_STD_TYPES           = PagedImage::MULTITHREADED, 
    CALC_OUTSUBIMAGE_ON_ALL_TYPES           = PagedImage::MULTITHREADED  
#endif // ML_DEPRECATED
  };

protected: void setThreadSupport(THREAD_SUPPORT supportMode);

public:    THREAD_SUPPORT getThreadSupport() const;


protected: void permitRecursiveHandleNotifications(bool enable);

public:    bool areRecursiveHandleNotificationsPermitted() const;

public:    MLint getHandleNotificationEntryCounter() const;



  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------
public: enum PERMITTED_TYPES {
  ONLY_SCALAR_TYPES,
  ONLY_DEFAULT_TYPES,
  ALL_REGISTERED_TYPES,
  ONLY_STANDARD_TYPES   = ONLY_SCALAR_TYPES,    
  FULLY_OPERATIONAL     = ONLY_DEFAULT_TYPES,   
  MINIMUM_OPERATIONAL   = ALL_REGISTERED_TYPES  
};

protected: void setVoxelDataTypeSupport(PERMITTED_TYPES permTypes);

public:    PERMITTED_TYPES getVoxelDataTypeSupport() const;

public:    bool isSupportedVoxelDataType(MLDataType dt) const;


  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

public:    std::string whoAmI(bool withInstanceName=true) const;




  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

public:    enum INPUT_STATE  {
  DISCONNECTED = 0, //<! defines that the input is disconnected. In the case of handleInput, this means that the input image can not be updated to a valid image.
  CONNECTED_BUT_INVALID      = 1,  //<! defines that the input is connected but has no valid data.
  CONNECTED_AND_VALID        = 2,  //<! defines that the input is connected and valid.
  CONNECTED_BUT_NEEDS_UPDATE = 3,  //<! defines that the input is connected and needs to be updated via updateImageProperties(). After the update it may either become CONNECTED_AND_VALID or CONNECTED_BUT_INVALID.
#ifdef ML_DEPRECATED
  OPEN             = DISCONNECTED,         //<! \deprecated, use DISCONNECTED
  UNDEFINED_CLOSED = CONNECTED_BUT_INVALID //<! \deprecated, use CONNECTED_BUT_INVALID
#endif
};

public:    enum INPUT_HANDLE {
  INVALIDATE                = 0, //<! Used as return value of handleInput() to indicate that the given input is not allowed to be invalid and the output images of the module should be invalidated without calling calculateOutputImageProperties().
  ALLOW_INVALID_INPUT       = 2, //<! Used as return value of handleInput() to indicate that the given input is allowed to be invalid. calculateOutputImageProperties() will be called and getInputImage() for that input index will return NULL.
#ifdef ML_DEPRECATED
  REDIRECT_TO_DUMMY_OP = 1, //<! Deprecated flag to indicate that an invalid input should be redirected to the DummyOp module.
#endif
};

public:    virtual INPUT_HANDLE handleInput(int /*inputIndex*/, INPUT_STATE /*state*/) const { return INVALIDATE; }

public:    INPUT_STATE getInputState(MLint index);

public:    INPUT_STATE getUpdatedInputState(MLint index);



  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

public:
  InputConnectorField*  getInputImageField(MLint i) const;
  OutputConnectorField* getOutputImageField(MLint i=0) const;

  MLint getNumInputImages() const;

  MLint getNumOutputImages() const;

  PagedImage* getOutputImage(MLint outputIndex=0) const;

  InputConnectorField* addInputImage(const char* name = NULL);

  OutputConnectorField* addOutputImage(const char* name = NULL);

  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
public:    PagedImage* getInputImage(MLint inputIndex, bool getReal=false) const;

  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
public:    PagedImage *getUpdatedInputImage(MLint inputIndex, bool getReal=false);




  //---------------------------------------------------------------------------

  //         These functions are identical to those from
  //         Host::getDefaultHost() and are
  //         wrapped here for convenience and to avoid direct accesses
  //         to the host and to avoid includes of mlHost.h.
  //         See mlHost.h for documentation.
  //---------------------------------------------------------------------------
public:

  static MLErrorCode getTile(PagedImage*  image,
                             SubImageBox  loc,
                             MLDataType datatype,
                             void**     data,
                             const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED;

  static MLErrorCode getTile(PagedImage* image,
                             SubImage &subimg,
                             const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED;

  static MLErrorCode updateImageProperties(PagedImage* image) ML_RETURN_VALUE_SHOULD_BE_USED;

  static void        freeTile(void* data);

  static void        updateProgress(const char* info1, const char* info2);

  static bool        shouldTerminate();

  static Field*      getPressedNotifyField();

  static void adaptPageExtent (ImageVector&       pageExtent,
                               MLDataType         imageType,
                               const ImageVector& newImgExtent,
                               const ImageVector& oldImgExtent,
                               const ImageVector& pageUnit      = ImageVector(0),
                               const ImageVector& minPageExtent = ImageVector(0),
                               const ImageVector& maxPageExtent = ImageVector(0));


  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

  static std::string getVoxelValueAsString(PagedImage*          image,
                                           const ImageVector& position,
                                           MLErrorCode*       errorCode=NULL,
                                           const std::string& errorResult="");



  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

protected: virtual CalculateOutputImageHandler* createCalculateOutputImageHandler(PagedImage* outputImage);

protected: virtual void calculateOutputImageProperties(int outputIndex, PagedImage* /*outputImage*/) { calculateOutputImageProperties(outputIndex); };

protected: virtual void calculateOutputImageProperties(int /*outputIndex*/) {};

protected: virtual SubImageBox calculateInputSubImageBox(int /*inputIndex*/,
                                                       const SubImageBox& outputSubImageBox,
                                                       int /*outputIndex*/)
  {
    return outputSubImageBox;
  };

protected: virtual void calculateOutputSubImage(SubImage *outputSubImage, int outputIndex, SubImage *inputSubImages);


  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

protected: virtual void provideCustomPage(int /*outputIndex*/, const SubImageBox& /*pageBox*/, MLMemoryBlockHandle& /*resultPage*/) {};


  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------
public: MLErrorCode processAllPages(int       outputIndex = -1,
                                    SubImageBox region      = SubImageBox()) ML_RETURN_VALUE_SHOULD_BE_USED;

public: MLErrorCode processAllPages(ProcessAllPagesHandler& handler,
                                    SubImageBox region  = SubImageBox()) ML_RETURN_VALUE_SHOULD_BE_USED;

public: MLErrorCode processMissingPages(int outputIndex = 0,
                                        SubImageBox region  = SubImageBox()) ML_RETURN_VALUE_SHOULD_BE_USED;



  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

public:    void clearOutputImage(MLint i=0);

public: MLMetaProfilePtr& getMetaProfile() const;



public:
  static void setCallbacksForDiagnosisModuleStack(DiagnosisModuleStackCallback pushCallback, DiagnosisModuleStackCallback popCallback)
  {
    pushModuleForDiagnosis = pushCallback;
    popModuleForDiagnosis = popCallback;
  }

  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------
protected: void handleNotificationOff();

protected: void handleNotificationOn();

protected: bool isHandleNotificationOn();


  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------

public:    bool isInputImageField(Field* field) const;

public:    void touchOutputImageFields() const;

public:    inline FieldContainer* getFieldContainer()                  { return this; }

public:    inline const FieldContainer* getFieldContainer() const { return this; }

protected: virtual void handleNotification(Field* /*field*/) {}

public:    virtual void beginSaveFields() {}

public:    virtual void endSaveFields() {}
  
protected: virtual void handleNotificationInternal(Field* field, FieldSensor::Strength strength);


  //---------------------------------------------------------------------------

  //---------------------------------------------------------------------------
public:    static size_t getNumModules();

public:    static Module* getModule(size_t index);

public:    static MLint findModuleIndex(Module& module);

public:    static void destroyModule();


  
private:   void setWasVisited(bool flag) { _visitedFlag = flag;  }

private:   bool wasVisited()             { return _visitedFlag; }


private:
  //-----------Private methods:
  bool _addBaseOp(Module& module);

  MLint _removeBaseOp(Module& module);


  //-----------Private members:
  std::vector <OutputConnectorField*> _outputConnectorFields;

  std::vector <InputConnectorField*>  _inputConnectorFields;

  THREAD_SUPPORT         _threadSupport;

  MLint                  _handleNotificationEntryCounter;

  bool                   _permitRecursiveHandleNotifications;

  bool                   _visitedFlag;

  PERMITTED_TYPES        _permittedTypes;

  MLint                  _handleNotificationBlockCounter;

  mutable MLMetaProfilePtr _metaProfilePtr;

  static std::vector<Module*> _instantiatedModules;

  static DiagnosisModuleStackCallback pushModuleForDiagnosis;
  static DiagnosisModuleStackCallback popModuleForDiagnosis;

  ML_ABSTRACT_CLASS_HEADER(Module)

public:

  virtual InputConnectorField* addInputConnector(const char* name, Module* module, MLint i);

  virtual OutputConnectorField* addOutputConnector(const char* name, Module* module, MLint i);


#ifdef ML_DEPRECATED



public:

protected: void setMemoryOutputControl(MLint outputIndex, bool manually);

public:    bool getMemoryOutputControl(MLint outputIndex) const;


  static inline ML_DEPRECATED std::string getVoxelValueAsString(Module &op,
                                                                MLint outIdx,
                                                                const ImageVector &pos,
                                                                MLErrorCode *errCode=NULL,
                                                                const std::string &errResult="")
  {
    return getVoxelValueAsString(op.getOutputImage(outIdx), pos, errCode, errResult);
  }
  static ML_DEPRECATED MLErrorCode getTile(Module* op,
                                           MLint outIndex,
                                           SubImageBox loc,
                                           MLDataType datatype,
                                           void** data,
                                           const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED;
  static ML_DEPRECATED MLErrorCode getTile(Module* op,
                                           MLint outIndex,
                                           SubImage &subimg,
                                           const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED;
  static ML_DEPRECATED MLErrorCode updateImageProps(Module* op, MLint outIndex) ML_RETURN_VALUE_SHOULD_BE_USED;
  static ML_DEPRECATED MLErrorCode updateImageProperties(Module* op, MLint outIndex) ML_RETURN_VALUE_SHOULD_BE_USED;
  ML_DEPRECATED BaseOp* getInOp(MLint i, bool getReal=false) const;
  ML_DEPRECATED MLint getInOpIndex(MLint i, bool getReal=false) const;
  inline ML_DEPRECATED MLint getOutImgInplace(MLint outIndex=0) const { return getOutputImageInplace(outIndex); }

  ML_DEPRECATED static void getInInfos(const BaseOp  &op,
                                              MLint          i,
                                              bool           getReal,
                                              bool          *isValidInputRet,
                                              BaseOp       **inOpRet,
                                              PagedImage     **inImgRet,
                                              MLint         *inOpIndexRet);

  inline ML_DEPRECATED MLint getInputNum() const { return getNumInputImages(); }
  inline ML_DEPRECATED MLint getOutputNum() const { return getNumOutputImages(); }
  inline ML_DEPRECATED PagedImage* getOutImg(MLint i=0) const { return getOutputImage(i); }
  inline ML_DEPRECATED PagedImage* getInImg(MLint i, bool getReal=false) const { return getInputImage(i, getReal); }
  inline ML_DEPRECATED PagedImage* getUpdatedInImg(MLint i, bool getReal=false) { return getUpdatedInputImage(i, getReal); }

  ML_DEPRECATED PagedImage* getNonDummyUpdatedInImg(int inIndex);

  inline ML_DEPRECATED static void adaptPageExt (ImageVector &pageExt,
                                                 MLDataType imgType,
                                                 const ImageVector &newImgExt,
                                                 const ImageVector &oldImgExt,
                                                 const ImageVector &pageUnit   = ImageVector(0),
                                                 const ImageVector &minPageExt = ImageVector(0),
                                                 const ImageVector &maxPageExt = ImageVector(0))
  {
    adaptPageExtent(pageExt, imgType, newImgExt, oldImgExt, pageUnit, minPageExt, maxPageExt);
  }
  inline ML_DEPRECATED void clearOutImg(MLint i=0) { clearOutputImage(i); }
  inline ML_DEPRECATED InputConnectorField* getInField(MLint i) const       { return getInputImageField(i); }
  inline ML_DEPRECATED OutputConnectorField* getOutField(MLint i=0) const   { return getOutputImageField(i); }
  inline const FieldContainer* getConstFieldContainer() const { return getFieldContainer(); }
  inline ML_DEPRECATED static size_t getNumBaseOps() { return getNumModules(); }
  ML_DEPRECATED static BaseOp* getBaseOp(size_t idx);
  inline ML_DEPRECATED static MLint findBaseOpIndex(Module &op) { return findModuleIndex(op); }
  inline ML_DEPRECATED static void destroyBaseOp() { destroyModule(); }


protected:

  inline ML_DEPRECATED void setOutImgInplace(MLint outIndex=0, MLint inIndex=0) { setOutputImageInplace(outIndex, inIndex); }
  inline ML_DEPRECATED void unsetOutImgInplace(MLint outIndex=0) { unsetOutputImageInplace(outIndex); }


#endif // ML_DEPRECATED

};

#ifdef ML_DEPRECATED

#define calcOutImageProps calculateOutputImageProperties
#define calcInSubImageBox calculateInputSubImageBox
#define calcOutSubImage   calculateOutputSubImage
#define typedCalcOutSubImage   typedCalculateOutputSubImage

#if defined(WIN32) && defined(ML_WARN_DEPRECATED)
#pragma deprecated("calcOutImageProps", "calcInSubImageBox", "calcOutSubImage", "typedCalcOutSubImage")
#endif

#ifndef DOXYGEN_SHOULD_SKIP_THIS

template<typename CauseAnErrorIfNotSpecified>
class calcInSubImageProps_has_been_removed_from_the_ML {
};

#define calcInSubImageProps(a,b,c) calcInSubImageProps() { calcInSubImageProps_has_been_removed_from_the_ML; };

#endif

// disable deprecation warnings
#ifdef _MSC_VER
#pragma warning(push)
#pragma warning(disable : 4996 )
#endif

class MLEXPORT ML_DEPRECATED BaseOp : public Module
{
public:
  BaseOp(int numInputImages, int numOutputImages):Module(numInputImages, numOutputImages)
  {};

  ML_ABSTRACT_CLASS_HEADER(BaseOp)
};

// re-enable deprecation warnings
#ifdef _MSC_VER
#pragma warning(pop)
#endif


#endif // ML_DEPRECATED


ML_END_NAMESPACE

#endif //of __mlModule_H