MeVisLab Toolbox Reference
List of all members
ml::KernelTools Class Reference

Class collecting a set of templated an normal functions for filtering operations using kernels. More...

#include <mlKernelTools.h>

Static Public Member Functions

Helper functions for kernel module implementations
static MLsoffset * createIndexTab (const ImageVector &inSubImgStrides, const Kernel &kernel)
 Create the table of offsets from the voxel (0,0,0,0,0,0) to the coordinates given by kernel.getCoordTab(). More...
 
static void deleteIndexTab (MLsoffset *idxTab)
 Function to delete an index table created with createIndexTab. More...
 
static MLsoffset calcSrcVoxelOffset (const ImageVector &strides, const ImageVector &kernelNegExt)
 Computes the offset index from voxel in output image to voxel in input image which can be returned as original voxel, e.g. More...
 
static ImageVector calcOutImageExt (const ImageVector &imgExt, const ImageVector &kernelExt, BorderHandling borderHandling, MLint numIterations=1)
 Calculate extents of output image for input image extents imgExt and kernel extents kernelExt if border handling borderHandling is used. More...
 
static void adaptWorldCoordinates (PagedImage &outImg, BorderHandling borderHandling, const ImageVector &negExt)
 Convenience function to correct the world matrix of the image outImg when a kernel is applied to outImg with border handling borderHandling. More...
 
static void expandForSeparableOrIterativeFiltering (SubImageBox &box, const ImageVector &negKernelExt, const ImageVector &posKernelExt, bool isSeparable, MLint numIterations)
 Adds additional "borders around a box for separable or iterative filtering, for example around requested input subimages. More...
 
static SubImageBox calcInSubImageBoxForOutSubImg (const SubImageBox &outSubImgBox, BorderHandling borderHandling, const ImageVector &negExt, const ImageVector &posExt, bool isSeparable=false, MLint numIterations=1)
 Computes the size of the input page needed to calculate the page whose extents are given by outSubImgBox. More...
 
static ImageVector calcOutInCoordShift (BorderHandling borderHandling, const ImageVector &negKernelExt)
 For every voxel coordinate written into the output image there is a voxel coordinate in the input image which serves as the origin for the kernel. More...
 
static SubImageBox calcAreaToBeCalculated (const ImageVector &inImgExt, const ImageVector &negFilterExt, const ImageVector &posFilterExt, BorderHandling borderHandling, bool isSeparable=false, MLint numIterations=1)
 Calculate the area of the output to be calculated when the kernel the negative negKernelExt and the positive posKernelExt extents and the border handling mode borderHandling is used on an image of extent inImgExt. More...
 
static void fillBorders (const ImageVector &inImgExt, const ImageVector &negKernelExt, const ImageVector &posKernelExt, KernelTools::BorderHandling borderHandling, MLdouble fillValue, SubImage &outSubImg, SubImage &inSubImg)
 Fill the borders of the input or the output subimage (inSubImg or outSubImg) with the correct values dependent on the passed border handling borderHandling. More...
 
template<typename IN_DATATYPE , typename OUT_DATATYPE >
static void copyLine (const IN_DATATYPE *inCursor, OUT_DATATYPE *outCursor, size_t numVox, MLsoffset srcVoxelOffset)
 Wrapping of functions globally available in ML_NAMESPACE for backward compatibility. More...
 
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)
 See MLKernelToolsCorrelateLine. More...
 
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)
 See MLKernelToolsCorrelateLineWithImageInterval. More...
 
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)
 See MLKernelToolsCorrelateLineWithKernelInterval. More...
 
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)
 See MLKernelToolsCorrelateLineWithImageAndKernelInterval. More...
 
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)
 See MLKernelToolsCorrelateLineEvtWithIntervals. More...
 
template<typename DATATYPE >
static void applyFiltering (const ImageVector &inImgExt, LineApplicator< DATATYPE > &lineApp, BorderHandling borderHandling, MLdouble fillValue, TSubImageWithCursor< DATATYPE > &outSubImg, TSubImageWithCursor< DATATYPE > &inSubImg)
 See MLKernelToolsApplyFiltering. More...
 
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)
 See MLKernelToolsApplyFiltering. More...
 

Border handling type and names.

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
}
 The border handling defines how an image is filtered at its borders if the kernel reaches undefined regions. More...
 
static const char *const BorderHandlingNames []
 Strings for BorderHandling names. More...
 

Detailed Description

Class collecting a set of templated an normal functions for filtering operations using kernels.

This file defines the BorderHandling enum type and a set of string names corresponding to the enum values.

For related code and more information see mlKernelExample.h, mlKernel.h, mlKernelBaseModule.h, mlKernelModule.h, mlKernelEditor.h, mlRankFilter.h, mlExtConvolutionFilter.h, mlKernelMacros, mlKernelTools.h and mlConvolutionFilter.h.

This file also contains a set of helper functions in the class KernelTools. IMPORTANT NOTE: There are some functions called like "correlateLine..." which do the same like that what's typically called a "convolution" in a programming context. We use the correct mathematical name "correlate" here. A convolution then can be implemented correctly by mirroring the kernel elements and using one of the "correlate..." functions. For the usage of correlations see

  • Bernd Radig: Verarbeiten und Verstehen von Bildern, S.79
  • R.N. Bracewell: The Fourier Transform and its applications, S.46
  • or Bronstein: Taschenbuch der Mathematik, Verlag Harri Deutsch, Frankfurt 1995, S.498 for the formal definition of convolutions.

The following helper functions are available:

  • createIndexTab
    Create the offset table from the pointer to the voxel covered by the kernel origin to the image voxels covered by kernel elements.
  • calcSrcVoxelOffset
    Calculate the offset from the pointer to a the voxel covered by the kernel origin to that voxel in the input image which corresponds to the written output voxel.
  • calcOutImageExt
    Calculates the extent of an output image from the kernel extent and the input image extent and the border handling mode. Useful in calculateOutputImageProperties().
  • adaptWorldCoordinates
    Corrects the world coordinates of a kernel filtered output image dependent on the border handling. Useful in calculateOutputImageProperties().
  • expandForSeparableOrIterativeFiltering
    Adds additional "borders around a box for separable or iterative filtering, for example around requested input subimages.
  • calcInSubImageBoxForOutSubImg
    Calculates the region of the input image needed to calculate a kernel filtered region of the output image. Useful in calculateInputSubImageBox().
  • calcOutInCoordShift
    Calculated the voxel shift between input and output image of a kernel filtered image dependent on kernel extent and border handling.
  • calcAreaToBeCalculated
    Calculates the entire region of the output image which needs to be calculated/written by the kernel filtering.
  • copyLine
    copies the row to be filtered from the input buffer to the output buffer
  • correlateLine
    correlates the row to be filtered with the current settings.
  • correlateLineWithImageInterval
    correlates all voxels in the row to be filtered if they are within a certain interval. All other voxels are simply copied.
  • correlateLineWithKernelInterval
    Correlates a row of the input image and writes the to the corresponding row of an output image. Voxels which are not part of a kernel interval are not included in the correlation process.
  • correlateLineWithImageAndKernelInterval
    Correlates a row of the input image and writes the to the corresponding row of an output image. Voxels which are not in of a kernel interval are not included in the correlation process. Voxels not in an image interval are simply copied from input to output image which being filtered anyway.
  • correlateLineEvtWithIntervals
    Correlates a row of the input image and writes the to the corresponding row of an output image. Dependent on passed flags one of the methods
    • correlateLineWithImageAndKernelInterval
    • correlateLineWithKernelInterval
    • correlateLineWithImageInterval or
    • correlateLine is used to accomplish filtering.
  • fillBorders
    Fill borders of an input or output subimage correctly dependent on the border handling and the image extents.
  • applyFiltering
    Two versions of this function permit to apply a row filtering function to a subimage and to write the result to an output image dependent on border handling and fill values.

Definition at line 645 of file mlKernelTools.h.

Member Enumeration Documentation

◆ BorderHandling

enum ml::KernelTools::BorderHandling

The border handling defines how an image is filtered at its borders if the kernel reaches undefined regions.

  • NO_PAD Only those voxels are passed to the output which can be filtered correctly by the entire kernel. So the output image usually shrinks by the kernel extents-1.
  • PAD_SRC_FILL The input image is virtually expanded by so many voxels that all input image voxels can be filtered correctly with the kernel. The area added around the input image is filled with the fill value.
  • PAD_DST_FILL All pixels of the output image which can be filtered correctly with the kernel without accessing voxels outside the output image are filtered with the kernel. All other voxels in the image are filled with the fill value.
  • PAD_DST_ORIGFILL All pixels of the output image which can be filtered correctly with the kernel without accessing voxels outside the output image are filtered with the kernel. All other voxels are copied from the input image.
  • PAD_SRC_UNDEFINED All pixels of the output image which can be filtered correctly with the kernel without accessing voxels outside the output image are filtered with the kernel. All other voxels are left undefined.
  • PAD_DST_UNDEFINED The input image is virtually expanded by so many voxels that all input image voxels can be filtered correctly with the kernel. The contents of the area added around the input image is left undefined. So the filtered image will also have a border with undefined image values.
  • PAD_SRC_CLAMP The input image is virtually expanded by so many voxels that all input image voxels can be filtered correctly with the kernel. The contents of the area added around the input image is filled with the next voxel found in the input image.

Notes:

PAD_DST_CLAMP cannot work, because clamping to valid data does not work for requested pages which are completely outside the valid area. E.g. slice 64 cannot be calculated if last valid page is 62 - clamping to 62 cannot work, because it does not exist when 64 is requested. Sorry, because that would be a nice mode.

Enumerator
NO_PAD 
PAD_SRC_FILL 
PAD_DST_FILL 
PAD_DST_ORIGFILL 
PAD_SRC_UNDEFINED 
PAD_DST_UNDEFINED 
PAD_SRC_CLAMP 
NUM_BORDER_HANDLINGS 

Definition at line 701 of file mlKernelTools.h.

Member Function Documentation

◆ adaptWorldCoordinates()

static void ml::KernelTools::adaptWorldCoordinates ( PagedImage &  outImg,
BorderHandling  borderHandling,
const ImageVector &  negExt 
)
static

Convenience function to correct the world matrix of the image outImg when a kernel is applied to outImg with border handling borderHandling.

negExt needs to be passed (can be retrieved from the applied kernel).

◆ applyFiltering() [1/2]

template<typename DATATYPE >
static void ml::KernelTools::applyFiltering ( const ImageVector &  inImgExt,
const fctLineFilter< DATATYPE > &  lineFilter,
const ImageVector &  negKernelExt,
const ImageVector &  posKernelExt,
BorderHandling  borderHandling,
MLdouble  fillValue,
TSubImageWithCursor< DATATYPE > &  outSubImg,
TSubImageWithCursor< DATATYPE > &  inSubImg 
)
inlinestatic

See MLKernelToolsApplyFiltering.

Definition at line 957 of file mlKernelTools.h.

References ml::MLKernelToolsApplyFiltering().

◆ applyFiltering() [2/2]

template<typename DATATYPE >
static void ml::KernelTools::applyFiltering ( const ImageVector &  inImgExt,
LineApplicator< DATATYPE > &  lineApp,
BorderHandling  borderHandling,
MLdouble  fillValue,
TSubImageWithCursor< DATATYPE > &  outSubImg,
TSubImageWithCursor< DATATYPE > &  inSubImg 
)
inlinestatic

See MLKernelToolsApplyFiltering.

Definition at line 945 of file mlKernelTools.h.

References ml::MLKernelToolsApplyFiltering().

◆ calcAreaToBeCalculated()

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

Calculate the area of the output to be calculated when the kernel the negative negKernelExt and the positive posKernelExt extents and the border handling mode borderHandling is used on an image of extent inImgExt.

isSeparable denotes whether a separable kernel filtering is applied; its default value is false. numIterations denotes the number of iterations to be applied; its default is 1. All values below 1 will be considered as 1. The area is in OUTPUT image coordinates.

◆ calcInSubImageBoxForOutSubImg()

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

Computes the size of the input page needed to calculate the page whose extents are given by outSubImgBox.

The extents are influenced by borderHandling and the negative and positive kernel extents given by negExt and posExt.

Parameters
outSubImgBoxis the region of the output subimage to be calculated.
borderHandlingdescribes the handling at image borders and needs to an enumerator values from BorderHandling.
negExtis the negative kernel extent given by getNegativeExtent() method of class kernel.
posExtis the positive kernel extent given by getPositiveExtent() method of class kernel.
isSeparabledenotes whether a separable kernel filtering is applied; its default value is false.
numIterationsdenotes the number of iterations to be applied; its default is 1. All values below 1 will be considered as 1.
Returns
is the region which needs to be requested from the input image to be able to calculate the outSubImgBox.

◆ calcOutImageExt()

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

Calculate extents of output image for input image extents imgExt and kernel extents kernelExt if border handling borderHandling is used.

For the number of iterations 1 (the default) needs to be used for normal filtering.

◆ calcOutInCoordShift()

static ImageVector ml::KernelTools::calcOutInCoordShift ( BorderHandling  borderHandling,
const ImageVector &  negKernelExt 
)
static

For every voxel coordinate written into the output image there is a voxel coordinate in the input image which serves as the origin for the kernel.

The shift between the voxel coordinate in the output image and kernel origin coordinate in input image is specified with this return value. To explain it another way: This is the shift vector in global image coordinates from an output voxel coordinate O to the voxel coordinate V where the filter kernel is placed so that V gets the right filter result. This value is the negative kernel extent for all BorderHandling modes, only in case of NO_PAD it's the null vector.

◆ calcSrcVoxelOffset()

static MLsoffset ml::KernelTools::calcSrcVoxelOffset ( const ImageVector &  strides,
const ImageVector &  kernelNegExt 
)
static

Computes the offset index from voxel in output image to voxel in input image which can be returned as original voxel, e.g.

if filter operation fails or if it does nothing.

Returns
is the offset from the voxel in the output image to voxel in input image which can be returned as original voxel, e.g. if filter operation fails or if it does nothing.

◆ copyLine()

template<typename IN_DATATYPE , typename OUT_DATATYPE >
static void ml::KernelTools::copyLine ( const IN_DATATYPE *  inCursor,
OUT_DATATYPE *  outCursor,
size_t  numVox,
MLsoffset  srcVoxelOffset 
)
inlinestatic

Wrapping of functions globally available in ML_NAMESPACE for backward compatibility.

See MLKernelToolsCopyLine.

Definition at line 855 of file mlKernelTools.h.

References ml::MLKernelToolsCopyLine().

Referenced by ml::KernelLineApplicator< DATATYPE, KDATATYPE >::applyToLine(), and ml::KernelLineApplicator< DATATYPE, KDATATYPE >::applyUserFilterToLine().

◆ correlateLine()

template<typename IN_DATATYPE , typename OUT_DATATYPE , typename K_DATATYPE >
static void ml::KernelTools::correlateLine ( const IN_DATATYPE *  inCursor,
OUT_DATATYPE *  outCursor,
size_t  numVox,
const K_DATATYPE *  valTab,
const MLsoffset *  indexTab,
size_t  indexTabSize 
)
inlinestatic

See MLKernelToolsCorrelateLine.

Definition at line 865 of file mlKernelTools.h.

References ml::MLKernelToolsCorrelateLine().

Referenced by ml::KernelLineApplicator< DATATYPE, KDATATYPE >::applyToLine().

◆ correlateLineEvtWithIntervals()

template<typename IN_DATATYPE , typename OUT_DATATYPE , typename K_DATATYPE >
static void ml::KernelTools::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 
)
inlinestatic

See MLKernelToolsCorrelateLineEvtWithIntervals.

Definition at line 925 of file mlKernelTools.h.

References ml::MLKernelToolsCorrelateLineEvtWithIntervals().

◆ correlateLineWithImageAndKernelInterval()

template<typename IN_DATATYPE , typename OUT_DATATYPE , typename K_DATATYPE >
static void ml::KernelTools::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 
)
inlinestatic

See MLKernelToolsCorrelateLineWithImageAndKernelInterval.

Definition at line 907 of file mlKernelTools.h.

References ml::MLKernelToolsCorrelateLineWithImageAndKernelInterval().

Referenced by ml::KernelLineApplicator< DATATYPE, KDATATYPE >::applyToLine().

◆ correlateLineWithImageInterval()

template<typename IN_DATATYPE , typename OUT_DATATYPE , typename K_DATATYPE >
static void ml::KernelTools::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 
)
inlinestatic

See MLKernelToolsCorrelateLineWithImageInterval.

Definition at line 877 of file mlKernelTools.h.

References ml::MLKernelToolsCorrelateLineWithImageInterval().

Referenced by ml::KernelLineApplicator< DATATYPE, KDATATYPE >::applyToLine().

◆ correlateLineWithKernelInterval()

template<typename IN_DATATYPE , typename OUT_DATATYPE , typename K_DATATYPE >
static void ml::KernelTools::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 
)
inlinestatic

See MLKernelToolsCorrelateLineWithKernelInterval.

Definition at line 892 of file mlKernelTools.h.

References ml::MLKernelToolsCorrelateLineWithKernelInterval().

Referenced by ml::KernelLineApplicator< DATATYPE, KDATATYPE >::applyToLine().

◆ createIndexTab()

static MLsoffset* ml::KernelTools::createIndexTab ( const ImageVector &  inSubImgStrides,
const Kernel &  kernel 
)
static

Create the table of offsets from the voxel (0,0,0,0,0,0) to the coordinates given by kernel.getCoordTab().

The offsets work corresponding to the strides given by inSubImgStrides. If kernel.isSeparable() then kernel.getSeparableCoordTab() is used instead kernel.getCoordTab(). The returned table must be deleted with deleteIndexTab(). On error NULL (e.g. allocation failure) NULL is returned.

◆ deleteIndexTab()

static void ml::KernelTools::deleteIndexTab ( MLsoffset *  idxTab)
static

Function to delete an index table created with createIndexTab.

NULL pointers can be passed safely.

◆ expandForSeparableOrIterativeFiltering()

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

Adds additional "borders around a box for separable or iterative filtering, for example around requested input subimages.

Parameters
boxis the region to be expanded.
negKernelExtis the negative extent of the kernel.
posKernelExtis the positive extent of the kernel.
isSeparableis true for separable filtering; otherwise, it returns false.
numIterationsis 1 for normal filtering or greater for additional iterations; values <=1 are set to 1.

◆ fillBorders()

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

Fill the borders of the input or the output subimage (inSubImg or outSubImg) with the correct values dependent on the passed border handling borderHandling.

For border handling modes which fill a border (*fill) fillValue is used as fill value, otherwise it's not used. For correct operation the negative negKernelExt and the positive posKernelExt extents of the kernel dimensions are needed, the extents of inSubImg must have been calculated with calcInSubImageBoxForOutSubImg() and the operator output image image extents must have been calculated with calcOutImageExt(). Also the extent of the used input image inImgExt must be passed.

Member Data Documentation

◆ BorderHandlingNames

const char* const ml::KernelTools::BorderHandlingNames[]
static

Strings for BorderHandling names.

Definition at line 714 of file mlKernelTools.h.

The documentation for this class was generated from the following file: