Index: trunk/psLib/src/imageops/psImageConvolve.h =================================================================== --- trunk/psLib/src/imageops/psImageConvolve.h (revision 11248) +++ trunk/psLib/src/imageops/psImageConvolve.h (revision 11703) @@ -5,6 +5,6 @@ * @author Robert DeSonia, MHPCC * - * @version $Revision: 1.15 $ $Name: not supported by cvs2svn $ - * @date $Date: 2007-01-23 22:47:23 $ + * @version $Revision: 1.16 $ $Name: not supported by cvs2svn $ + * @date $Date: 2007-02-08 04:17:58 $ * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii */ @@ -20,55 +20,48 @@ #include "psType.h" -#define PS_TYPE_KERNEL PS_TYPE_F32 /**< the data member to use for kernel image */ -#define PS_TYPE_KERNEL_DATA F32 /**< the data member to use for kernel image */ -#define PS_TYPE_KERNEL_NAME "psF32" /**< the data type for kernel as a string */ +#define PS_TYPE_KERNEL PS_TYPE_F32 ///< the data member to use for kernel image */ +#define PS_TYPE_KERNEL_DATA F32 ///< the data member to use for kernel image */ +#define PS_TYPE_KERNEL_NAME "psF32" ///< the data type for kernel as a string */ -/** Kernel Type - * - * A floating-point data type used for storing kernel data. - * - */ -//typedef float psKernelType; - -/** A convolution kernel */ +/// A convolution kernel typedef struct { - psImage* image; ///< Kernel data, in the form of an image + psImage *image; ///< Kernel data, in the form of an image int xMin; ///< Most negative x index int yMin; ///< Most negative y index int xMax; ///< Most positive x index int yMax; ///< Most positive y index - float** kernel; ///< Pointer to the kernel data - float** p_kernelRows; ///< Pointer to the rows of the kernel data; not intended for user use. + float **kernel; ///< Pointer to the kernel data + float **p_kernelRows; ///< Pointer to the rows of the kernel data; not intended for user use. } psKernel; -/** Allocates a convolution kernel of the given range - * - * In order to perform a convolution, we need to define the convolution - * kernel. We need a more general object than a psImage so that we can - * incorporate the offset from the (0, 0) pixel to the (0, 0) value of the - * kernel. It might be convenient to allow both positive and negative - * indices to convey the positive and negative shifts. One might consider - * setting the x0 and y0 members of a psImage to the appropriate offsets, - * but this is not the purpose of these members, and doing so may affect the - * behavior of other psImage operations. - * - * This construction allows the kernel member to use negative indices, while - * preserving the location of psMemBlocks relative to allocated memory. - * - * The maximum extent of the kernel shifts shall be defined by the xMin, - * xMax, yMin and yMax members. Note that xMin and yMin, under normal - * circumstances, should be negative numbers. That is, - * myKernel->kernel[-3][-2] may be defined if yMin and xMin are equal to or - * more negative than -3 and -2, respectively. - * - * In the event that one of the minimum values is greater than the - * corresponding maximum value, the function shall generate a warning, and - * the offending values shall be exchanged. - * - * @return psKernel* A new kernel object - */ -psKernel* psKernelAlloc( +/// Allocates a convolution kernel of the given range +/// +/// In order to perform a convolution, we need to define the convolution +/// kernel. We need a more general object than a psImage so that we can +/// incorporate the offset from the (0, 0) pixel to the (0, 0) value of the +/// kernel. It might be convenient to allow both positive and negative +/// indices to convey the positive and negative shifts. One might consider +/// setting the x0 and y0 members of a psImage to the appropriate offsets, +/// but this is not the purpose of these members, and doing so may affect the +/// behavior of other psImage operations. +/// +/// This construction allows the kernel member to use negative indices, while +/// preserving the location of psMemBlocks relative to allocated memory. +/// +/// The maximum extent of the kernel shifts shall be defined by the xMin, +/// xMax, yMin and yMax members. Note that xMin and yMin, under normal +/// circumstances, should be negative numbers. That is, +/// myKernel->kernel[-3][-2] may be defined if yMin and xMin are equal to or +/// more negative than -3 and -2, respectively. +/// +/// In the event that one of the minimum values is greater than the +/// corresponding maximum value, the function shall generate a warning, and +/// the offending values shall be exchanged. +/// +/// @return psKernel* A new kernel object +/// +psKernel *psKernelAlloc( int xMin, ///< Most negative x index int xMax, ///< Most positive x index @@ -77,10 +70,10 @@ ); -/** Checks the type of a particular pointer. - * - * Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. - * - * @return bool: True if the pointer matches a psKernel structure, false otherwise. - */ +/// Checks the type of a particular pointer. +/// +/// Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. +/// +/// @return bool: True if the pointer matches a psKernel structure, false otherwise. +/// bool psMemCheckKernel( psPtr ptr ///< the pointer whose type to check @@ -88,60 +81,58 @@ -/** Generates a kernel given a list of shift values - * - * Given a list of values (e.g., shifts made in the course of OT guiding), - * psKernelGenerate shall return the appropriate kernel. The vectors xShifts - * and yShifts, which are a list of shifts relative to some starting point, - * will be supplied by the user. The elements of the vectors should be of an - * integer type; otherwise the values shall be truncated to integers. The - * output kernel shall be normalized such that the sum over the kernel is - * unity. - * - * If the vectors are not of the same number of elements, then the function - * shall generate a warning shall be generated, following which, the longer - * vector trimmed to the length of the shorter, and the function shall continue. - * - * @return psKernel* new Kernel object - */ -psKernel* psKernelGenerate( - const psVector* tShifts, ///< list of time shifts - const psVector* xShifts, ///< list of x-axis shifts - const psVector* yShifts, ///< list of y-axis shifts - bool relative - /**< specifies the starting point for the shifts; true=relative to previous shift - * false = relative to some other starting point. */ +/// Generates a kernel given a list of shift values +/// +/// Given a list of values (e.g., shifts made in the course of OT guiding), +/// psKernelGenerate shall return the appropriate kernel. The vectors xShifts +/// and yShifts, which are a list of shifts relative to some starting point, +/// will be supplied by the user. The elements of the vectors should be of an +/// integer type; otherwise the values shall be truncated to integers. The +/// output kernel shall be normalized such that the sum over the kernel is +/// unity. +/// +/// If the vectors are not of the same number of elements, then the function +/// shall generate a warning shall be generated, following which, the longer +/// vector trimmed to the length of the shorter, and the function shall continue. +/// +/// @return psKernel* new Kernel object +/// +psKernel *psKernelGenerate( + const psVector *tShifts, ///< list of time shifts (F32) + const psVector *xShifts, ///< list of x-axis shifts (S32) + const psVector *yShifts, ///< list of y-axis shifts (S32) + bool tRelative, ///< Are times relative (durations) or absolute? + bool xyRelative ///< Are x,y positions relative (shifts) or absolute? ); -/** convolve an image with a kernel - * - * Given an input image and the convolution kernel, psImageConvolve shall - * convolve the input image, in, with the kernel, kernel and return the - * convolved image, out. - * - * Two methods shall be available for the convolution: if direct is true, - * then the convolution shall be performed in real space (appropriate for - * small kernels); otherwise, the convolution shall be performed using Fast - * Fourier Transforms (FFTs; appropriate for larger kernels). The latter - * option involves padding the input image, copying the kernel into an image - * of the same size as the padded input image, performing an FFT on each, - * multiplying the FFTs, and performing an inverse FFT before trimming the - * image back to the original size. - * - * @return psImage* resulting image - */ -psImage* psImageConvolve( - psImage* out, ///< a psImage to recycle. If NULL, a new psImage is made. - const psImage* in, ///< the psImage to convolve - const psKernel* kernel, ///< kernel to colvolve with - bool direct ///< specifies method, true=direct convolution, false=fourier +/// Convolve an image with a kernel, using a direct convolution +/// +/// This is appropriate for small kernels, where there is no time saving to use FFT method. +/// +/// @return psImage* resulting image +/// +psImage *psImageConvolveDirect( + psImage *out, ///< a psImage to recycle. If NULL, a new psImage is made. + const psImage *in, ///< the psImage to convolve + const psKernel *kernel ///< kernel to colvolve with ); -/** Smooths an image by parts using 1D Gaussian independently in x and y. - * - * Applies a circularly symmetric Gaussian smoothing first in x and then in y - * directions with just a vector. This process is 2N faster than 2D convolutions (in general). - * - * @return bool TRUE if successful, otherwise FALSE - */ +/// Convolve an image with a kernel, using the FFT +/// +/// This is appropriate for larger kernels, where the direct convolution is slow. The input image and kernel +/// are suitably padded to avoid wrap-around effects. +psImage *psImageConvolveFFT( + psImage *out, ///< a psImage to recycle. If NULL, a new psImage is made. + const psImage *in, ///< the psImage to convolve + const psKernel *kernel, ///< kernel to colvolve with + float pad ///< Value to use to pad the input image +); + +/// Smooths an image by parts using 1D Gaussian independently in x and y. +/// +/// Applies a circularly symmetric Gaussian smoothing first in x and then in y +/// directions with just a vector. This process is 2N faster than 2D convolutions (in general). +/// +/// @return bool TRUE if successful, otherwise FALSE +/// bool psImageSmooth( psImage *image, ///< the image to be smoothed