/* @file  psImageConvolve.h
 *
 * @brief image convolution functionality
 *
 * @author Robert DeSonia, MHPCC
 *
 * @version $Revision: 1.18 $ $Name: not supported by cvs2svn $
 * @date $Date: 2007-03-02 22:19:21 $
 * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_IMAGE_CONVOLVE_H
#define PS_IMAGE_CONVOLVE_H

/// @addtogroup ImageOps Image Operations
/// @{

#include "psImage.h"
#include "psVector.h"
#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 */

/// A convolution kernel
typedef struct
{
    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.
}
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(
    int xMin,                          ///< Most negative x index
    int xMax,                          ///< Most positive x index
    int yMin,                          ///< Most negative y index
    int yMax                           ///< Most positive y index
);

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


/// 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, 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(
    const psImage *in,                  ///< the psImage to convolve
    const psKernel *kernel              ///< kernel to colvolve with
);

/// 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(
    const psImage *in,                  ///< the psImage to convolve
    const psKernel *kernel,             ///< kernel to colvolve with
    float pad                           ///< Value to use to pad the input image
);

/// Convolve a mask image with a kernel
///
/// Returns a mask, grown by the supplied kernel.  Only those pixels specified by the maskVal are grown; the
/// rest are simply propagated.
psImage *psImageConvolveMask(const psImage *mask, psMaskType maskVal, const psKernel *kernel);


/// 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
    double  sigma,                     ///< the width of the smoothing kernel in pixels
    double  Nsigma                     ///< the size of the smoothing box in sigmas
);

bool psImageSmoothMaskF32(
    psImage *image,                    ///< the image to be smoothed
    psImage *mask,                     ///< optional mask
    psMaskType maskVal,
    double  sigma,                     ///< the width of the smoothing kernel in pixels
    double  Nsigma                     ///< the size of the smoothing box in sigmas
);

/// @}
#endif // #ifndef PS_IMAGE_CONVOLVE_H
