mlModule.h

Go to the documentation of this file.

/*************************************************************************************
**
** Copyright 2007, MeVis Medical Solutions AG
**
** The user may use this file in accordance with the license agreement provided with
** the Software or, alternatively, in accordance with the terms contained in a
** written agreement between the user and MeVis Medical Solutions AG.
**
** For further information use the contact form at https://www.mevislab.de/contact
**
**************************************************************************************/
 
#ifndef ML_MODULE_H
#define ML_MODULE_H
 
 
// ML-includes
#include "mlInitSystemML.h"
#include "mlRuntimeSubClass.h"
#include "mlBase.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;
#if ML_DEPRECATED_SINCE(3,5,0)
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:
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
 
public: Module(int numInputImages, int numOutputImages);
 
public: ~Module() override;
 
 
 
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
 
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;
 
protected: void setClampPagesToImageExtent(bool flag = true);
 
  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, 
#if ML_DEPRECATED_SINCE(3,5,0)
    CALC_OUTSUBIMAGE_ON_STD_TYPES           = PagedImage::MULTITHREADED, 
    CALC_OUTSUBIMAGE_ON_ALL_TYPES           = PagedImage::MULTITHREADED  
#endif
  };
 
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:    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.
#if ML_DEPRECATED_SINCE(3,5,0)
  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.
#if ML_DEPRECATED_SINCE(3,5,0)
  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 = nullptr);
 
  OutputConnectorField* addOutputImage(const char* name = nullptr);
 
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
public:    PagedImage* getInputImage(MLint inputIndex, bool getReal=false) const;
 
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
public:    PagedImage *getUpdatedInputImage(MLint inputIndex, bool getReal=false) const;
 
 
 
 
  //---------------------------------------------------------------------------
  //         These functions are identical to those from
  //         Host::getDefaultHost() and are
  //         wrapped here for convenience.
  //         See mlHost.h for documentation.
  //---------------------------------------------------------------------------
public:
 
  [[nodiscard]]
  static MLErrorCode getTile(PagedImage*  image,
                             SubImageBox  loc,
                             MLDataType datatype,
                             void**     data,
                             const ScaleShiftData &scaleShiftData=ScaleShiftData(),
                             MLRequestProgressCB* progressCallback = nullptr,
                             void*                progressCallbackUserData = nullptr);
 
  [[nodiscard]]
  static MLErrorCode getTile(PagedImage* image,
                             SubImage &subimg,
                             const ScaleShiftData &scaleShiftData = ScaleShiftData(),
                             MLRequestProgressCB*  progressCallback = nullptr,
                             void*                 progressCallbackUserData = nullptr);
 
  static MLErrorCode updateImageProperties(PagedImage* image);
 
  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=nullptr,
                                           const std::string& errorResult="");
 
 
 
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
 
protected: virtual CalculateOutputImageHandler* createCalculateOutputImageHandler(PagedImage* outputImage);
 
protected: virtual void calculateOutputImageProperties(int outputIndex, PagedImage* /*outputImage*/) { calculateOutputImageProperties(outputIndex); }
 
#if ML_DEPRECATED_SINCE(3,6,0)
protected: virtual void calculateOutputImageProperties(int /*outputIndex*/) {}
#else
private: virtual void calculateOutputImageProperties(int /*outputIndex*/) {}
#endif
 
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:
  [[nodiscard]]
  MLErrorCode processAllPages(int       outputIndex = -1,
                                    SubImageBox region = SubImageBox(),
                                    MLRequestProgressCB* progressCallback = nullptr,
                                    void* progressCallbackUserData = nullptr);
 
public:
  [[nodiscard]]
  MLErrorCode processAllPages(ProcessAllPagesHandler& handler,
                                    SubImageBox region  = SubImageBox(),
                                    MLRequestProgressCB* progressCallback = nullptr,
                                    void* progressCallbackUserData = nullptr);
 
public:
  [[nodiscard]]
  MLErrorCode processMissingPages(int outputIndex = 0,
                                        SubImageBox region  = SubImageBox(),
                                        MLRequestProgressCB* progressCallback = nullptr,
                                        void* progressCallbackUserData = nullptr);
 
 
 
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
 
public:    void clearOutputImage(MLint i=0);
 
public: MLMetaProfilePtr& getMetaProfile() const;
 
 
 
public:
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
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: void handleNotificationInternal(Field* field, FieldSensor::Strength strength) override;
 
 
  //---------------------------------------------------------------------------
  //---------------------------------------------------------------------------
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;
 
  ML_ABSTRACT_CLASS_HEADER(Module)
 
public:
 
  const char* getTypeNameFast() const { return getTypeId() ? getTypeId()->getName() : "<unregistered_module>"; }
 
  InputConnectorField* addInputConnector(const char* name, Module* module, MLint i) override;
 
  OutputConnectorField* addOutputConnector(const char* name, Module* module, MLint i) override;
 
 
#if ML_DEPRECATED_SINCE(3,5,0)
 
 
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=nullptr,
                                                                const std::string &errResult="")
  {
    return getVoxelValueAsString(op.getOutputImage(outIdx), pos, errCode, errResult);
  }
  [[nodiscard]]
  static ML_DEPRECATED MLErrorCode getTile(Module* op,
                                           MLint outIndex,
                                           SubImageBox loc,
                                           MLDataType datatype,
                                           void** data,
                                           const ScaleShiftData &scaleShiftData=ScaleShiftData());
  [[nodiscard]]
  static ML_DEPRECATED MLErrorCode getTile(Module* op,
                                           MLint outIndex,
                                           SubImage &subimg,
                                           const ScaleShiftData &scaleShiftData=ScaleShiftData());
  [[nodiscard]]
  static ML_DEPRECATED MLErrorCode updateImageProps(Module* op, MLint outIndex);
  [[nodiscard]]
  static ML_DEPRECATED MLErrorCode updateImageProperties(Module* op, MLint outIndex);
  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
 
};
 
class MLEXPORT ModuleDiagnosisStackScope
{
public:
  ModuleDiagnosisStackScope(Module* module) : _module(module) { if (pushModuleForDiagnosis) { pushModuleForDiagnosis(_module); } }
  ~ModuleDiagnosisStackScope() { if (popModuleForDiagnosis) { popModuleForDiagnosis(_module); } }
 
  typedef void (*DiagnosisModuleStackCallback)(void*);
 
  static void setCallbacksForDiagnosisModuleStack(DiagnosisModuleStackCallback pushCallback, DiagnosisModuleStackCallback popCallback)
  {
    pushModuleForDiagnosis = pushCallback;
    popModuleForDiagnosis = popCallback;
  }
 
private:
  static DiagnosisModuleStackCallback pushModuleForDiagnosis;
  static DiagnosisModuleStackCallback popModuleForDiagnosis;
 
  Module* _module;
};
 
#if ML_DEPRECATED_SINCE(3,5,0)
#define calcOutImageProps calculateOutputImageProperties
#define calcInSubImageBox calculateInputSubImageBox
#define calcOutSubImage   calculateOutputSubImage
#define typedCalcOutSubImage   typedCalculateOutputSubImage
 
#if defined(WIN32) && !defined(ML_NO_DEPRECATED_WARNINGS)
#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_END_NAMESPACE
 
#endif