MeVisLab/Standard/Sources/ML/MLKernel/mlKernelTools.h

Go to the documentation of this file.

// **InsertLicense** code
//-------------------------------------------------------------------------

//-------------------------------------------------------------------------
// Prevent multiple including of this file.
#if !defined(__mlKernelTools_H)
#define __mlKernelTools_H

// ML-includes
#ifndef __mlInitSystemKernel_H
#include "mlInitSystemKernel.h"
#endif
// Exclude some files for an older release for a SYNGO application. 
// The "if !defined" is going to be removed in future.
#if !defined(USE_SYNGO)
#include "mlLineApplicator.h"
#endif
#ifndef __mlKernel_H
#include "mlKernel.h"
#endif

ML_START_NAMESPACE

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

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

  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template<typename DATATYPE> struct fctLineFilter{
    public:
      virtual void operator() (TSubImageWithCursor<DATATYPE> *, TSubImageWithCursor<DATATYPE> *, size_t) const {}

      virtual ~fctLineFilter() {}
  };

  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template<class T, typename DATATYPE>
  struct useObjectLineFilter : public fctLineFilter<DATATYPE>{

    T* pOb;

    void (T::*pLF)(TSubImageWithCursor<DATATYPE>*, TSubImageWithCursor<DATATYPE>*, size_t);

    public:
      explicit useObjectLineFilter(T* po, void (T::*pf)(TSubImageWithCursor<DATATYPE>*, TSubImageWithCursor<DATATYPE>*, size_t)) :
        pOb(po), pLF(pf) {}

      virtual ~useObjectLineFilter() {}

      void operator () (TSubImageWithCursor<DATATYPE> *inSubImg, TSubImageWithCursor<DATATYPE> *outSubImg, size_t numVox) const
         { (pOb->*pLF)(inSubImg, outSubImg, numVox);}
  };



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

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

  // internal function, for scalar types
  template <typename DATATYPE>
    static inline bool _isScalarValueInRange(const DATATYPE& v, bool normal, double minVal, double maxVal,
                                            OverloadSelector::OnTrue)
    {
      if (normal) {
        return (v >= minVal) && (v <= maxVal);
      } else {
        return (v <  maxVal) || (v >  minVal);
      }
    }

  // internal function, for non-scalar types
  template <typename DATATYPE>
    static inline bool _isScalarValueInRange(const DATATYPE&, bool, double, double,
                                             OverloadSelector::OnFalse)
    {
      return true;
    }
  template <typename DATATYPE>
    static inline bool isScalarValueInRange(const DATATYPE& v, bool normal, double minVal, double maxVal)
    {
      return _isScalarValueInRange(v, normal, minVal, maxVal, OverloadSelector::isScalarType<DATATYPE>());
    }

  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template <typename IN_DATATYPE, typename OUT_DATATYPE>
    static void MLKernelToolsCopyLine(const IN_DATATYPE *inCursor,
                                      OUT_DATATYPE      *outCursor,
                                      size_t            numVox,
                                      MLsoffset         srcVoxelOffset)
  {
    ML_TRACE_IN( "MLKernelToolsCopyLine()" );
    ML_TRY
    {
      // Add srcVoxelOffset to inCursor. So we don't need to do it again and again in the loop.
      inCursor += srcVoxelOffset;
      for (size_t i=0; i<numVox; ++i){
        // Copy input voxel to output.
        *outCursor = static_cast<OUT_DATATYPE>(*inCursor);

        // Move read and write cursor forward.
        ++outCursor;
        ++inCursor;
      }
    }
    ML_CATCH_RETHROW;
  }

  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
    static void MLKernelToolsCorrelateLine(const IN_DATATYPE *inCursor,
                                           OUT_DATATYPE      *outCursor,
                                           size_t             numVox,
                                           const K_DATATYPE  *valTab,
                                           const MLsoffset   *indexTab,
                                           size_t             indexTabSize)
  {
    ML_TRACE_IN( "MLKernelToolsCorrelateLine( )" );
    ML_TRY
    {
      // Sum up the products of the kernel element values and the input image voxels which are
      // found in the input page covered by kernel elements. Input image voxels are found
      // by offsetting the pointer to the input image voxel with the indexes from indexTab.

      typedef typename TypeTraits<OUT_DATATYPE>::IntermediateType IntermediateType;

      // Apply kernel tab to all voxels in line.
      for (size_t i=0; i < numVox; i++){

        // IntermediateType is double for scalar types and OUT_DATATYPE itself for all other types
        IntermediateType retVal = ml_cast_from_scalar<IntermediateType>(0);
        for (size_t c=0; c < indexTabSize; c++){
          retVal += static_cast<IntermediateType>(inCursor[indexTab[c]]) * 
                    ml_scalar_factor_cast<IntermediateType>(valTab[c]);
        }

        // Write result into output image.
        *outCursor = ml_cast_from_intermediate_type_without_clamping<OUT_DATATYPE>(retVal);

        // Move read and write cursor forward.
        ++outCursor;
        ++inCursor;
      } // for 
    }
    ML_CATCH_RETHROW;
  }

  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
    static void MLKernelToolsCorrelateLineWithImageInterval(const IN_DATATYPE *inCursor,
                                                            OUT_DATATYPE      *outCursor,
                                                            size_t            numVox,
                                                            const K_DATATYPE  *valTab,
                                                            const MLsoffset   *indexTab,
                                                            size_t            indexTabSize,
                                                            MLsoffset         srcVoxelOffset,
                                                            MLdouble          minVal,
                                                            MLdouble          maxVal)
  {
    ML_TRACE_IN( "MLKernelToolsCorrelateLineWithImageInterval( )" );
    ML_TRY
    {
      // Test whether we have a normal interval or an exclusive one (i.e. min > max).
      const bool normal = minVal <= maxVal;

      typedef typename TypeTraits<OUT_DATATYPE>::IntermediateType IntermediateType;

      // Apply kernel tab to all voxels in line.
      for (size_t i=0; i < numVox; i++){
        IN_DATATYPE srcVox = *(inCursor+srcVoxelOffset);

        // Test input image voxel. Is it in image interval?
        if (! isScalarValueInRange(srcVox, normal, minVal, maxVal)){
          // No, copy value from input.
          *outCursor = static_cast<OUT_DATATYPE>(srcVox);
        }
        else{
          // Sum up the products of the kernel element values and the input image voxels which are
          // found in the input page covered by kernel elements. Input image voxels are found
          // by offsetting the pointer to the input image voxel with the indexes from indexTab.

          // IntermediateType is double for scalar types and OUT_DATATYPE itself for all other types
          IntermediateType retVal = ml_cast_from_scalar<IntermediateType>(0);
          for (size_t c=0; c < indexTabSize; c++){
            retVal += static_cast<IntermediateType>(inCursor[indexTab[c]]) * 
                      ml_scalar_factor_cast<IntermediateType>(valTab[c]);
          }

          // Write result into output image.
          *outCursor = ml_cast_from_intermediate_type_without_clamping<OUT_DATATYPE>(retVal);

        } // else

        // Move read and write cursor forward.
        ++outCursor;
        ++inCursor;
      } // for 
    }
    ML_CATCH_RETHROW;
  }




  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
    static void MLKernelToolsCorrelateLineWithKernelInterval(const IN_DATATYPE *inCursor,
                                                             OUT_DATATYPE      *outCursor,
                                                             size_t            numVox,
                                                             const K_DATATYPE  *valTab,
                                                             const MLsoffset   *indexTab,
                                                             size_t            indexTabSize,
                                                             MLsoffset         srcVoxelOffset,
                                                             MLdouble          minVal,
                                                             MLdouble          maxVal)
  {
    ML_TRACE_IN( "MLKernelToolsCorrelateLineWithKernelInterval ( )" );
    ML_TRY
    {
      // Test whether we have a normal interval or an exclusive one (i.e. min > max).
      const bool normal = minVal <= maxVal;

      typedef typename TypeTraits<OUT_DATATYPE>::IntermediateType IntermediateType;

      // Apply kernel tab to all voxels in line.
      for (size_t i=0; i < numVox; i++){

        // Sums of weights for the kernel elements
        MLdouble posValSum = 0; // that match the threshold criterion
        MLdouble negValSum = 0; // that doesn't match the threshold criterion

        // IntermediateType is double for scalar types and OUT_DATATYPE itself for all other types
        IntermediateType retVal = ml_cast_from_scalar<IntermediateType>(0);
        for (size_t c=0; c < indexTabSize; c++){
          IN_DATATYPE val = inCursor[indexTab[c]];

          // Get element from kernel table and multiply it with its corresponding input
          // page voxel and add it to result value. Do this only if the voxel belongs
          // to the kernel interval. Sum up the weights of valid and invalid voxels.
          if (isScalarValueInRange(val, normal, minVal, maxVal)){
            retVal += static_cast<IntermediateType>(val) * 
                      ml_scalar_factor_cast<IntermediateType>(valTab[c]);
            posValSum += valTab[c];
          }
          else {
            negValSum += valTab[c];
          }
        }

        // If any value has been added to retVal then pretend as if all kernel voxels which did
        // not match the kernel threshold interval hold the weighted average of those who did.
        // Otherwise return value from input image which is under the replaced output image voxel.
        if (MLValueIs0WOM(posValSum)) {
          *outCursor = static_cast<OUT_DATATYPE>(inCursor[srcVoxelOffset]);
        } else {
          *outCursor = ml_cast_from_intermediate_type_without_clamping<OUT_DATATYPE>(retVal *
            ml_scalar_factor_cast<IntermediateType>((posValSum + negValSum) / posValSum));
        }

        // Move read and write cursor forward.
        ++outCursor;
        ++inCursor;
      }
    }
    ML_CATCH_RETHROW;
  }




  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
    static void MLKernelToolsCorrelateLineWithImageAndKernelInterval(const IN_DATATYPE *inCursor,
                                                                     OUT_DATATYPE      *outCursor,
                                                                     size_t            numVox,
                                                                     const K_DATATYPE  *valTab,
                                                                     const MLsoffset   *indexTab,
                                                                     size_t            indexTabSize,
                                                                     MLsoffset         srcVoxelOffset,
                                                                     MLdouble          imgIntMinVal,
                                                                     MLdouble          imgIntMaxVal,
                                                                     MLdouble          kernIntMinVal,
                                                                     MLdouble          kernIntMaxVal)
  {
    ML_TRACE_IN( "MLKernelToolsCorrelateLineWithImageAndKernelInterval( )" );
    ML_TRY
    {
      // Test whether we have a normal interval or an exclusive one (i.e. min > max).
      const bool normalImgInt  = imgIntMinVal  <= imgIntMaxVal;
      const bool normalKernInt = kernIntMinVal <= kernIntMaxVal;

      typedef typename TypeTraits<OUT_DATATYPE>::IntermediateType IntermediateType;

      // Scan all voxels in line.
      for (size_t i=0; i < numVox; i++){

        // Get pointer to kernel origin in input data and the voxel corresponding to the changed voxel.
        const IN_DATATYPE *voxPtr = inCursor;
        IN_DATATYPE       srcVox  = *(voxPtr+srcVoxelOffset);

        // Test input image voxel. Is it in image interval?
        if (! isScalarValueInRange(srcVox, normalImgInt, imgIntMinVal, imgIntMaxVal)){
          // No, copy value from input.
          *outCursor = static_cast<OUT_DATATYPE>(srcVox);
        }
        else{
          // Yes, voxel needs to be filtered.

          // Sums of weights for the kernel elements
          MLdouble posValSum = 0; // that match the threshold criterion
          MLdouble negValSum = 0; // that do not match the threshold criterion

          // IntermediateType is double for scalar types and OUT_DATATYPE itself for all other types
          IntermediateType retVal = ml_cast_from_scalar<IntermediateType>(0);
          for (size_t c=0; c < indexTabSize; c++){
            IN_DATATYPE val = inCursor[indexTab[c]];

            // Get element from kernel table and multiply it with its corresponding input
            // page voxel and add it to result value. Do this only if the voxel belongs
            // to the kernel interval. Sum up the weights of valid and invalid voxels.
            if (isScalarValueInRange(val, normalKernInt, kernIntMinVal, kernIntMaxVal)){
              retVal += static_cast<IntermediateType>(val) * 
                        ml_scalar_factor_cast<IntermediateType>(valTab[c]);
              posValSum += valTab[c];
            }
            else {
              negValSum += valTab[c];
            }
          }

          // If any value has been added to retVal then pretend as if all kernel voxels which did
          // not match the kernel threshold interval hold the weighted average of those who did.
          // Otherwise return value from input image which is under the replaced output image voxel.
          if (MLValueIs0WOM(posValSum)) {
            *outCursor = static_cast<OUT_DATATYPE>(inCursor[srcVoxelOffset]);
          } else {
            *outCursor = ml_cast_from_intermediate_type_without_clamping<OUT_DATATYPE>(retVal *
              ml_scalar_factor_cast<IntermediateType>((posValSum + negValSum) / posValSum));
          }

        }  // else

        // Move read and write cursor forward.
        ++outCursor;
        ++inCursor;
      }
    }
    ML_CATCH_RETHROW;
  }

  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
    static void MLKernelToolsCorrelateLineEvtWithIntervals(const IN_DATATYPE *inCursor,
                                                           OUT_DATATYPE      *outCursor,
                                                           size_t            numVox,
                                                           const K_DATATYPE  *valTab,
                                                           const MLsoffset   *indexTab,
                                                           size_t            indexTabSize,
                                                           MLsoffset         srcVoxelOffset,
                                                           MLdouble          imgIntMinVal,
                                                           MLdouble          imgIntMaxVal,
                                                           MLdouble          kernIntMinVal,
                                                           MLdouble          kernIntMaxVal,
                                                           bool              useImgInt,
                                                           bool              useKernInt)
  {
    ML_TRACE_IN( "MLKernelToolsCorrelateLineEvtWithIntervals( )" );
    ML_TRY
    {
      if (useImgInt && !useKernInt) {
        // Image interval on but kernel interval off:
        MLKernelToolsCorrelateLineWithImageInterval(inCursor,
                                                    outCursor,
                                                    numVox,
                                                    valTab,
                                                    indexTab,
                                                    indexTabSize,
                                                    srcVoxelOffset,
                                                    imgIntMinVal,
                                                    imgIntMaxVal);
      } else if (!useImgInt && useKernInt) {
        // Image interval off but kernel interval on:
        MLKernelToolsCorrelateLineWithKernelInterval(inCursor,
                                                     outCursor,
                                                     numVox,
                                                     valTab,
                                                     indexTab,
                                                     indexTabSize,
                                                     srcVoxelOffset,
                                                     kernIntMinVal,
                                                     kernIntMaxVal);
      } else if (useImgInt && useKernInt) {
        // Image interval and kernel interval on:
        MLKernelToolsCorrelateLineWithImageAndKernelInterval(inCursor,
                                                             outCursor,
                                                             numVox,
                                                             valTab,
                                                             indexTab,
                                                             indexTabSize,
                                                             srcVoxelOffset,
                                                             imgIntMinVal,
                                                             imgIntMaxVal,
                                                             kernIntMinVal,
                                                             kernIntMaxVal);
      } else {
        // Convolute the line normally without using intervals.
        MLKernelToolsCorrelateLine(inCursor,
                                   outCursor,
                                   numVox,
                                   valTab,
                                   indexTab,
                                   indexTabSize);
      }
    }
    ML_CATCH_RETHROW

  } // correlateLineEvtWithIntervals




  //---------------------------------------------------------------------------------------------
  //---------------------------------------------------------------------------------------------
  class MLKERNELEXPORT KernelTools
  {
    public:


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

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

    //-------------------------------------------------------------------------------------------
    //-------------------------------------------------------------------------------------------
    enum BorderHandling {NO_PAD              = 0,
                         PAD_SRC_FILL        ,
                         PAD_DST_FILL        ,
                         PAD_DST_ORIGFILL    ,
                         PAD_SRC_UNDEFINED   ,
                         PAD_DST_UNDEFINED   ,
                         PAD_SRC_CLAMP       ,

                         NUM_BORDER_HANDLINGS};

    //-------------------------------------------------------------------------------------------
    //-------------------------------------------------------------------------------------------
    static const char* const BorderHandlingNames[];





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

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

    static MLsoffset *createIndexTab(const ImageVector &inSubImgStrides, const Kernel &kernel);

    static void deleteIndexTab(MLsoffset *idxTab);

    static MLsoffset calcSrcVoxelOffset(const ImageVector &strides, 
                                        const ImageVector &kernelNegExt);

    static ImageVector calcOutImageExt(const ImageVector   &imgExt,
                                  const ImageVector   &kernelExt,
                                  BorderHandling borderHandling, 
                                  MLint          numIterations=1);

    static void adaptWorldCoordinates(PagedImage &outImg,
                                      BorderHandling borderHandling,
                                      const ImageVector &negExt);

    static void expandForSeparableOrIterativeFiltering(SubImageBox  &box, 
                                                       const ImageVector &negKernelExt, 
                                                       const ImageVector &posKernelExt, 
                                                       bool          isSeparable, 
                                                       MLint         numIterations);

    static SubImageBox calcInSubImageBoxForOutSubImg(const SubImageBox &outSubImgBox,
                                                   BorderHandling   borderHandling,
                                                   const ImageVector    &negExt,
                                                   const ImageVector    &posExt,
                                                   bool             isSeparable=false,
                                                   MLint            numIterations=1);

    static ImageVector calcOutInCoordShift(BorderHandling borderHandling, 
                                      const ImageVector  &negKernelExt);

    static SubImageBox calcAreaToBeCalculated(const ImageVector  &inImgExt,
                                            const ImageVector  &negFilterExt,
                                            const ImageVector  &posFilterExt,
                                            BorderHandling borderHandling,
                                            bool           isSeparable=false,
                                            MLint          numIterations=1);


    static void fillBorders(const ImageVector           &inImgExt,
                            const ImageVector           &negKernelExt,
                            const ImageVector           &posKernelExt,
                            KernelTools::BorderHandling  borderHandling,
                            MLdouble                     fillValue,
                            SubImage                     &outSubImg,
                            SubImage                    &inSubImg);
 




    //-------------------------------------------------------------------------------------------
    //-------------------------------------------------------------------------------------------
    template <typename IN_DATATYPE, typename OUT_DATATYPE>
      static void copyLine(const IN_DATATYPE *inCursor,
                           OUT_DATATYPE      *outCursor,
                           size_t            numVox,
                           MLsoffset         srcVoxelOffset)
    {
      MLKernelToolsCopyLine(inCursor, outCursor, numVox, srcVoxelOffset);
    }

    template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
      static void correlateLine(const IN_DATATYPE *inCursor,
                                OUT_DATATYPE      *outCursor,
                                size_t             numVox,
                                const K_DATATYPE  *valTab,
                                const MLsoffset   *indexTab,
                                size_t             indexTabSize)
    {
      MLKernelToolsCorrelateLine(inCursor, outCursor, numVox, valTab, indexTab, indexTabSize);
    }

    template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
      static void correlateLineWithImageInterval(const IN_DATATYPE *inCursor,
                                                 OUT_DATATYPE      *outCursor,
                                                 size_t            numVox,
                                                 const K_DATATYPE  *valTab,
                                                 const MLsoffset   *indexTab,
                                                 size_t            indexTabSize,
                                                 MLsoffset         srcVoxelOffset,
                                                 MLdouble          minVal,
                                                 MLdouble          maxVal)
    {
      MLKernelToolsCorrelateLineWithImageInterval(inCursor, outCursor, numVox, valTab, indexTab, indexTabSize, srcVoxelOffset, minVal, maxVal);
    }

    template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
      static void correlateLineWithKernelInterval(const IN_DATATYPE *inCursor,
                                                  OUT_DATATYPE      *outCursor,
                                                  size_t            numVox,
                                                  const K_DATATYPE  *valTab,
                                                  const MLsoffset   *indexTab,
                                                  size_t            indexTabSize,
                                                  MLsoffset         srcVoxelOffset,
                                                  MLdouble          minVal,
                                                  MLdouble          maxVal)
    {
      MLKernelToolsCorrelateLineWithKernelInterval(inCursor, outCursor, numVox, valTab, indexTab, indexTabSize, srcVoxelOffset, minVal, maxVal);
    }

    template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
      static void correlateLineWithImageAndKernelInterval(const IN_DATATYPE *inCursor,
                                                          OUT_DATATYPE      *outCursor,
                                                          size_t            numVox,
                                                          const K_DATATYPE  *valTab,
                                                          const MLsoffset   *indexTab,
                                                          size_t            indexTabSize,
                                                          MLsoffset         srcVoxelOffset,
                                                          MLdouble          imgIntMinVal,
                                                          MLdouble          imgIntMaxVal,
                                                          MLdouble          kernIntMinVal,
                                                          MLdouble          kernIntMaxVal)
    {
      MLKernelToolsCorrelateLineWithImageAndKernelInterval(inCursor, outCursor, numVox, valTab, indexTab, indexTabSize, srcVoxelOffset,
                                                           imgIntMinVal, imgIntMaxVal, kernIntMinVal, kernIntMaxVal);
    }

    template <typename IN_DATATYPE, typename OUT_DATATYPE, typename K_DATATYPE>
      static void correlateLineEvtWithIntervals(const IN_DATATYPE *inCursor,
                                                OUT_DATATYPE      *outCursor,
                                                size_t            numVox,
                                                const K_DATATYPE  *valTab,
                                                const MLsoffset   *indexTab,
                                                size_t            indexTabSize,
                                                MLsoffset         srcVoxelOffset,
                                                MLdouble          imgIntMinVal,
                                                MLdouble          imgIntMaxVal,
                                                MLdouble          kernIntMinVal,
                                                MLdouble          kernIntMaxVal,
                                                bool              useImgInt,
                                                bool              useKernInt)
    {
      MLKernelToolsCorrelateLineEvtWithIntervals(inCursor, outCursor, numVox, valTab, indexTab, indexTabSize, srcVoxelOffset,
                                                 imgIntMinVal, imgIntMaxVal, kernIntMinVal, kernIntMaxVal, useImgInt, useKernInt);
    }

// Exclude some files for an older release for a SYNGO application. 
// The "if !defined" is going to be removed in future.
#if !defined(USE_SYNGO)

    template <typename DATATYPE>
      static void applyFiltering(const ImageVector        &inImgExt,
                                 LineApplicator<DATATYPE> &lineApp,
                                 BorderHandling           borderHandling,
                                 MLdouble                 fillValue,
                                 TSubImageWithCursor<DATATYPE>        &outSubImg,
                                 TSubImageWithCursor<DATATYPE>        &inSubImg)
    {
      MLKernelToolsApplyFiltering(inImgExt,lineApp,  borderHandling, fillValue, outSubImg, inSubImg);
    }
#endif

    template <typename DATATYPE>
      static void applyFiltering(const ImageVector             &inImgExt,
                                 const fctLineFilter<DATATYPE> &lineFilter,
                                 const ImageVector             &negKernelExt,
                                 const ImageVector             &posKernelExt,
                                 BorderHandling                borderHandling,
                                 MLdouble                      fillValue,
                                 TSubImageWithCursor<DATATYPE>             &outSubImg,
                                 TSubImageWithCursor<DATATYPE>             &inSubImg)
    {
      MLKernelToolsApplyFiltering(inImgExt, lineFilter, negKernelExt, posKernelExt, borderHandling, fillValue, outSubImg, inSubImg);
    }

  }; // end of class KernelTools



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

// Exclude some files for an older release for a SYNGO application. 
// The "if !defined" is going to be removed in future.
#if !defined(USE_SYNGO)
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template <typename DATATYPE>
    static void MLKernelToolsApplyFiltering(const ImageVector           &inImgExt,
                                            LineApplicator<DATATYPE>    &lineApp,
                                            KernelTools::BorderHandling borderHandling,
                                            MLdouble                    fillValue,
                                            TSubImageWithCursor<DATATYPE>           &outSubImg,
                                            TSubImageWithCursor<DATATYPE>           &inSubImg)
  {
    // Extract parameters for the internal \c _applyFiltering function from \c KernelLineApplicator object
    MLKernelToolsApplyFiltering(inImgExt,
                                useObjectLineFilter<LineApplicator<DATATYPE>, DATATYPE>
                                        (&lineApp, &LineApplicator<DATATYPE>::applyToLine),
                                lineApp.getNegativeExtent(),
                                lineApp.getPositiveExtent(),
                                borderHandling,
                                fillValue,
                                outSubImg,
                                inSubImg);
  }
#endif

  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  template <typename DATATYPE>
    static void MLKernelToolsApplyFiltering(const ImageVector             &inImgExt,
                                            const fctLineFilter<DATATYPE> &lineFilter,
                                            const ImageVector             &negKernelExt,
                                            const ImageVector             &posKernelExt,
                                            KernelTools::BorderHandling   borderHandling,
                                            MLdouble                      fillValue,
                                            TSubImageWithCursor<DATATYPE>             &outSubImg,
                                            TSubImageWithCursor<DATATYPE>             &inSubImg)
  {
    ML_TRACE_IN( "MLKernelToolsApplyFiltering( )" );
    ML_TRY
    {
      // Fill border of subimages before calculating the correct area in output subimage.
      KernelTools::fillBorders(inImgExt, negKernelExt, posKernelExt, borderHandling, fillValue, outSubImg, inSubImg);

      // Calculate output image area to be calculated.
      SubImageBox area(KernelTools::calcAreaToBeCalculated(inImgExt, negKernelExt, posKernelExt, borderHandling));

      // Clamp region to be filled in output page, because e.g. in PAD_DST_FILL not the
      // entire output buffer needs to be calculated; the rest is filled.
      SubImageBox calcArea = outSubImg.getBox();
      calcArea = calcArea.intersect(area);

      // Print size and position of output page.
      ImageVector ov1 = calcArea.v1;
      ImageVector ov2 = calcArea.v2;
      ImageVector pOf = KernelTools::calcOutInCoordShift(borderHandling, negKernelExt);


      // Scan all voxels of the output page in u,t,c,z, y and x direction with a 'voxel cursor'.
      ImageVector p;
      ImageVector rowStart;
      MLint  rowLength = ov2.x - ov1.x + 1;
      for (p.u=ov1.u;   p.u<=ov2.u;   p.u++){
        for (p.t=ov1.t;   p.t<=ov2.t;   p.t++){
          for (p.c=ov1.c;   p.c<=ov2.c;   p.c++){
            for (p.z=ov1.z;   p.z<=ov2.z;   p.z++){
              rowStart .set(0, 0, p.z, p.c, p.t, p.u);
              for (p.y=ov1.y;   p.y<=ov2.y;   p.y++){
                // Move cursors in input and output subimage to start of rows.
                // The input image cursor defines the current kernel placement.
                // The output image cursor defines the result voxel filtered from kernel and input image values.
                // Note that both cursors are placed in global image coordinates, and NOT in local page coordinates!
                rowStart .x = ov1.x;
                rowStart .y = p.y;
                outSubImg.setCursorImgPos(rowStart);
                inSubImg .setCursorImgPos(rowStart-pOf);

                // Apply the kernel to a line in the input image and write result into the
                // output image. Note that \c lineFilter is a function-like object whose
                // operator() (TSubImageWithCursor<DATATYPE> *, TSubImageWithCursor<DATATYPE> *, long) is called
                // when the object is used as function.
                lineFilter(&inSubImg, &outSubImg, static_cast<size_t>(rowLength));
              }
            }
          }
        }
      }
    }
    ML_CATCH_RETHROW;
  }

ML_END_NAMESPACE

#endif // __mlKernelTools_H