mlKernelTools.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
**
**************************************************************************************/
 

 
#if !defined(__mlKernelTools_H)
#define __mlKernelTools_H
 
// ML-includes
#include "mlInitSystemKernel.h"
#include "mlLineApplicator.h"
#include "mlKernel.h"
 
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) {}

      ~useObjectLineFilter() override {}

      void operator () (TSubImageWithCursor<DATATYPE> *inSubImg, TSubImageWithCursor<DATATYPE> *outSubImg, size_t numVox) const override
         { (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)
  {
    if (inCursor == nullptr || outCursor == nullptr) {
      return;
    }
 
    // 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;
    }
  }
 
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  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)
  {
    // 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
  }
 
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  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)
  {
    // 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
  }
 
 
 
 
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  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)
  {
    // 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;
    }
  }
 
 
 
 
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  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)
  {
    // 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;
    }
  }
 
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  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)
  {
    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);
    }
  } // 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);
    }

    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);
    }

    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
 
 
 
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
 
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  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);
  }
 
  //-------------------------------------------------------------------------------------------
  //-------------------------------------------------------------------------------------------
  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)
  {
    // 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.setCursorImagePosition(rowStart);
              inSubImg .setCursorImagePosition(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_END_NAMESPACE
 
#endif // __mlKernelTools_H