Package util

Class FFTConvolution<R extends net.imglib2.type.numeric.RealType<R>>

java.lang.Object

util.FFTConvolution<R>

public class FFTConvolution<R extends net.imglib2.type.numeric.RealType<R>>
extends Object

Computes the convolution of an image with an arbitrary kernel. Computation is based on the Convolution Theorem (http://en.wikipedia.org/wiki/Convolution_theorem). By default computation is performed in-place, i.e. the input is replaced by the convolution. A separate output can, however, be specified. The class supports to sequentially convolve the same image with different kernels. To achieve that, you have to call setKeepImgFFT(true) and for each sequential run replace the kernel by either calling setKernel(RandomAccessibleInterval< R > kernel) or setKernel(RandomAccessible< R > kernel, Interval kernelInterval). The Fourier convolution will keep the FFT of the image which will speed up all convolutions after the initial run() call. NOTE: There is no checking if the sizes are compatible. If the new kernel has smaller or larger dimensions, it will simply fail. It is up to you to look for that. NOTE: This is not influenced by whether the computation is performed in-place or not, just the FFT of the image is kept. In the same way, you can sequentially convolve varying images with the same kernel. For that, you simply have to replace the image after the first run() call by calling either setImg(RandomAccessibleInterval< R > img) or setImg(RandomAccessible< R > img, Interval imgInterval). The Fourier convolution will keep the FFT of the kernel which will speed up all convolutions after the initial run() call. NOTE: There is no checking if the sizes are compatible. If the new input has smaller or larger dimensions, it will simply fail. It is up to you to look for that. NOTE: This is not influenced by whether the computation is performed in-place or not, just the FFT of the kernel is kept.

Author:

Stephan Preibisch, Jonathan Hale

Constructor Summary

Constructors

Constructor	Description
FFTConvolution(net.imglib2.img.Img<R> img, net.imglib2.img.Img<R> kernel)	Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
FFTConvolution(net.imglib2.img.Img<R> img, net.imglib2.img.Img<R> kernel, ExecutorService service)	Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
FFTConvolution(net.imglib2.img.Img<R> img, net.imglib2.img.Img<R> kernel, net.imglib2.RandomAccessibleInterval<R> output)	Compute a Fourier space based convolution The image will be extended by mirroring with single boundary, the kernel will be zero-padded.
FFTConvolution(net.imglib2.img.Img<R> img, net.imglib2.img.Img<R> kernel, net.imglib2.RandomAccessibleInterval<R> output, ExecutorService service)	Compute a Fourier space based convolution The image will be extended by mirroring with single boundary, the kernel will be zero-padded.
FFTConvolution(net.imglib2.RandomAccessible<R> img, net.imglib2.Interval imgInterval, net.imglib2.RandomAccessible<R> kernel, net.imglib2.Interval kernelInterval, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)	Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
FFTConvolution(net.imglib2.RandomAccessible<R> img, net.imglib2.Interval imgInterval, net.imglib2.RandomAccessible<R> kernel, net.imglib2.Interval kernelInterval, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory, ExecutorService service)	Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
FFTConvolution(net.imglib2.RandomAccessible<R> img, net.imglib2.Interval imgInterval, net.imglib2.RandomAccessible<R> kernel, net.imglib2.Interval kernelInterval, net.imglib2.RandomAccessibleInterval<R> output, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)	Compute a Fourier space based convolution.
FFTConvolution(net.imglib2.RandomAccessible<R> img, net.imglib2.Interval imgInterval, net.imglib2.RandomAccessible<R> kernel, net.imglib2.Interval kernelInterval, net.imglib2.RandomAccessibleInterval<R> output, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory, ExecutorService service)	Compute a Fourier space based convolution.
FFTConvolution(net.imglib2.RandomAccessibleInterval<R> img, net.imglib2.RandomAccessibleInterval<R> kernel, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)	Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
FFTConvolution(net.imglib2.RandomAccessibleInterval<R> img, net.imglib2.RandomAccessibleInterval<R> kernel, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory, ExecutorService service)	Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
FFTConvolution(net.imglib2.RandomAccessibleInterval<R> img, net.imglib2.RandomAccessibleInterval<R> kernel, net.imglib2.RandomAccessibleInterval<R> output, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)	Compute a Fourier space based convolution The image will be extended by mirroring with single boundary, the kernel will be zero-padded.
FFTConvolution(net.imglib2.RandomAccessibleInterval<R> img, net.imglib2.RandomAccessibleInterval<R> kernel, net.imglib2.RandomAccessibleInterval<R> output, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory, ExecutorService service)	Compute a Fourier space based convolution The image will be extended by mirroring with single boundary, the kernel will be zero-padded.

Method Summary

Modifier and Type	Method	Description
static <R extends net.imglib2.type.numeric.RealType<R>> void	computeConvolution(net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> fftImg, net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> fftKernel, net.imglib2.RandomAccessibleInterval<R> output, boolean keepImgFFT, ExecutorService service)
static <R extends net.imglib2.type.numeric.RealType<R>> net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType>	computeImgFFT(net.imglib2.Interval imgConvolutionInterval, net.imglib2.RandomAccessible<R> img, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> fftFactory, ExecutorService service)
static <R extends net.imglib2.type.numeric.RealType<R>> net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType>	computeKernelFFT(net.imglib2.Interval kernelConvolutionInterval, long[] min, long[] max, boolean complexConjugate, net.imglib2.RandomAccessible<R> kernel, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> fftFactory, ExecutorService service)
void	convolve()
static final <R extends net.imglib2.type.numeric.RealType<R>> void	convolve(net.imglib2.RandomAccessible<R> img, net.imglib2.Interval imgInterval, net.imglib2.RandomAccessible<R> kernel, net.imglib2.Interval kernelInterval, net.imglib2.RandomAccessibleInterval<R> output, net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory, int numThreads)
static final ExecutorService	createExecutorService()	Utility function to create an ExecutorService Number of threads utilized matches available processors in runtime.
static final ExecutorService	createExecutorService(int nThreads)	Utility function to create an ExecutorService
net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType>	fftImgFactory()
boolean	getComplexConjugate()
protected static net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType>	getFFTFactory(net.imglib2.img.Img<? extends net.imglib2.type.numeric.RealType<?>> img)
net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType>	imgFFT()
boolean	keepImgFFT()
net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType>	kernelFFT()
static final void	multiplyComplex(net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> img, net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> kernel)
void	setComputeComplexConjugate(boolean complexConjugate)
ExecutorService	setExecutorService(ExecutorService service)
void	setFFTImgFactory(net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)
void	setImg(net.imglib2.RandomAccessible<R> img, net.imglib2.Interval imgInterval)
void	setImg(net.imglib2.RandomAccessibleInterval<R> img)
void	setImgFFT(net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> fftImg)	Sets the FFT image as computed, be very careful with this method, if any parameters of the FFT are wrong, this will fail WARNING: if you do not set keepImgFFT, this image will be modified during convolution
void	setKeepImgFFT(boolean keep)
void	setKernel(net.imglib2.RandomAccessible<R> kernel, net.imglib2.Interval kernelInterval)
void	setKernel(net.imglib2.RandomAccessibleInterval<R> kernel)
void	setKernelFFT(net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> fftKernel)	Sets the FFT kernel as computed, be very careful with this method, if any parameters of the FFT are wrong, this will fail
void	setOutput(net.imglib2.RandomAccessibleInterval<R> output)
static net.imglib2.util.Pair<net.imglib2.Interval,net.imglib2.Interval>	setupFFTs(net.imglib2.Interval imgInterval, net.imglib2.Interval kernelInterval, long[] min, long[] max)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

FFTConvolution

public FFTConvolution(net.imglib2.img.Img<R> img,
 net.imglib2.img.Img<R> kernel)

Compute a Fourier space based convolution in-place (img will be replaced by the convolved result). The image will be extended by mirroring with single boundary, the kernel will be zero-padded. The ImgFactory for creating the FFT will be identical to the one used by the 'img' if possible, otherwise an ArrayImgFactory or CellImgFactory depending on the size. ExecutorService will be created on convolve() with threads equal to number of processors equal to the runtime.

Parameters:

img - - the image

kernel - - the convolution kernel

FFTConvolution

public FFTConvolution(net.imglib2.img.Img<R> img,
 net.imglib2.img.Img<R> kernel,
 ExecutorService service)

Compute a Fourier space based convolution in-place (img will be replaced by the convolved result). The image will be extended by mirroring with single boundary, the kernel will be zero-padded. The ImgFactory for creating the FFT will be identical to the one used by the 'img' if possible, otherwise an ArrayImgFactory or CellImgFactory depending on the size.

Parameters:

img - - the image

kernel - - the convolution kernel

service - - service providing threads for multi-threading

FFTConvolution

public FFTConvolution(net.imglib2.img.Img<R> img,
 net.imglib2.img.Img<R> kernel,
 net.imglib2.RandomAccessibleInterval<R> output)

Compute a Fourier space based convolution The image will be extended by mirroring with single boundary, the kernel will be zero-padded. The ImgFactory for creating the FFT will be identical to the one used by the 'img' if possible, otherwise an ArrayImgFactory or CellImgFactory depending on the size. ExecutorService will be created on convolve() with threads equal to number of processors equal to the runtime.

Parameters:

img - - the image

kernel - - the convolution kernel

output - - the result of the convolution

FFTConvolution

public FFTConvolution(net.imglib2.img.Img<R> img,
 net.imglib2.img.Img<R> kernel,
 net.imglib2.RandomAccessibleInterval<R> output,
 ExecutorService service)

Compute a Fourier space based convolution The image will be extended by mirroring with single boundary, the kernel will be zero-padded. The ImgFactory for creating the FFT will be identical to the one used by the 'img' if possible, otherwise an ArrayImgFactory or CellImgFactory depending on the size.

Parameters:

img - - the image

kernel - - the convolution kernel

output - - the result of the convolution

service - - service providing threads for multi-threading

FFTConvolution

public FFTConvolution(net.imglib2.RandomAccessibleInterval<R> img,
 net.imglib2.RandomAccessibleInterval<R> kernel,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)

Compute a Fourier space based convolution in-place (img will be replaced by the convolved result). The image will be extended by mirroring with single boundary, the kernel will be zero-padded. ExecutorService will be created on convolve() with threads equal to number of processors equal to the runtime.

Parameters:

img - - the image

kernel - - the convolution kernel

factory - - the ImgFactory to create the fourier transforms

FFTConvolution

public FFTConvolution(net.imglib2.RandomAccessibleInterval<R> img,
 net.imglib2.RandomAccessibleInterval<R> kernel,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory,
 ExecutorService service)

Compute a Fourier space based convolution in-place (img will be replaced by the convolved result). The image will be extended by mirroring with single boundary, the kernel will be zero-padded.

Parameters:

img - - the image

kernel - - the convolution kernel

factory - - the ImgFactory to create the fourier transforms

service - - service providing threads for multi-threading

FFTConvolution

public FFTConvolution(net.imglib2.RandomAccessibleInterval<R> img,
 net.imglib2.RandomAccessibleInterval<R> kernel,
 net.imglib2.RandomAccessibleInterval<R> output,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)

Compute a Fourier space based convolution The image will be extended by mirroring with single boundary, the kernel will be zero-padded. ExecutorService will be created on convolve() with threads equal to number of processors equal to the runtime.

Parameters:

img - - the image

kernel - - the convolution kernel

output - - the output

factory - - the ImgFactory to create the fourier transforms

FFTConvolution

public FFTConvolution(net.imglib2.RandomAccessibleInterval<R> img,
 net.imglib2.RandomAccessibleInterval<R> kernel,
 net.imglib2.RandomAccessibleInterval<R> output,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory,
 ExecutorService service)

Compute a Fourier space based convolution The image will be extended by mirroring with single boundary, the kernel will be zero-padded.

Parameters:

img - - the image

kernel - - the convolution kernel

output - - the output

factory - - the ImgFactory to create the fourier transforms

service - - service providing threads for multi-threading

FFTConvolution

public FFTConvolution(net.imglib2.RandomAccessible<R> img,
 net.imglib2.Interval imgInterval,
 net.imglib2.RandomAccessible<R> kernel,
 net.imglib2.Interval kernelInterval,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)

Compute a Fourier space based convolution in-place (img will be replaced by the convolved result). The input as well as the kernel need to be extended or infinite already as the Interval required to perform the Fourier convolution is significantly bigger than the Interval provided here. Interval size of img and kernel: size(img) + 2*(size(kernel)-1) + pad to fft compatible size ExecutorService will be created on convolve() with threads equal to number of processors equal to the runtime.

Parameters:

img - - the input

imgInterval - - the input interval (i.e. the area to be convolved)

kernel - - the kernel

kernelInterval - - the kernel interval

factory - - the ImgFactory to create the fourier transforms

FFTConvolution

public FFTConvolution(net.imglib2.RandomAccessible<R> img,
 net.imglib2.Interval imgInterval,
 net.imglib2.RandomAccessible<R> kernel,
 net.imglib2.Interval kernelInterval,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory,
 ExecutorService service)

Compute a Fourier space based convolution in-place (img will be replaced by the convolved result). The input as well as the kernel need to be extended or infinite already as the Interval required to perform the Fourier convolution is significantly bigger than the Interval provided here. Interval size of img and kernel: size(img) + 2*(size(kernel)-1) + pad to fft compatible size

Parameters:

img - - the input

imgInterval - - the input interval (i.e. the area to be convolved)

kernel - - the kernel

kernelInterval - - the kernel interval

factory - - the ImgFactory to create the fourier transforms

service - - service providing threads for multi-threading

FFTConvolution

public FFTConvolution(net.imglib2.RandomAccessible<R> img,
 net.imglib2.Interval imgInterval,
 net.imglib2.RandomAccessible<R> kernel,
 net.imglib2.Interval kernelInterval,
 net.imglib2.RandomAccessibleInterval<R> output,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)

Compute a Fourier space based convolution. The input as well as the kernel need to be extended or infinite already as the Interval required to perform the Fourier convolution is significantly bigger than the Interval provided here. Interval size of img and kernel: size(img) + 2*(size(kernel)-1) + pad to fft compatible size ExecutorService will be created on convolve() with threads equal to number of processors equal to the runtime.

Parameters:

img - - the input

imgInterval - - the input interval (i.e. the area to be convolved)

kernel - - the kernel

kernelInterval - - the kernel interval

output - - the output data+interval

factory - - the ImgFactory to create the fourier transforms

FFTConvolution

public FFTConvolution(net.imglib2.RandomAccessible<R> img,
 net.imglib2.Interval imgInterval,
 net.imglib2.RandomAccessible<R> kernel,
 net.imglib2.Interval kernelInterval,
 net.imglib2.RandomAccessibleInterval<R> output,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory,
 ExecutorService service)

Compute a Fourier space based convolution. The input as well as the kernel need to be extended or infinite already as the Interval required to perform the Fourier convolution is significantly bigger than the Interval provided here. Interval size of img and kernel: size(img) + 2*(size(kernel)-1) + pad to fft compatible size

Parameters:

img - - the input

imgInterval - - the input interval (i.e. the area to be convolved)

kernel - - the kernel

kernelInterval - - the kernel interval

output - - the output data+interval

factory - - the ImgFactory to create the fourier transforms

service - - service providing threads for multi-threading

Method Details

setImg

public void setImg(net.imglib2.RandomAccessibleInterval<R> img)

setImg

public void setImg(net.imglib2.RandomAccessible<R> img,
 net.imglib2.Interval imgInterval)

setKernel

public void setKernel(net.imglib2.RandomAccessibleInterval<R> kernel)

setKernel

public void setKernel(net.imglib2.RandomAccessible<R> kernel,
 net.imglib2.Interval kernelInterval)

setOutput

public void setOutput(net.imglib2.RandomAccessibleInterval<R> output)

setComputeComplexConjugate

public void setComputeComplexConjugate(boolean complexConjugate)

Parameters:

complexConjugate - - If the complex conjugate of the FFT of the kernel should be used.

getComplexConjugate

public boolean getComplexConjugate()

setKeepImgFFT

public void setKeepImgFFT(boolean keep)

keepImgFFT

public boolean keepImgFFT()

setFFTImgFactory

public void setFFTImgFactory(net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory)

fftImgFactory

public net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> fftImgFactory()

imgFFT

public net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> imgFFT()

kernelFFT

public net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> kernelFFT()

setKernelFFT

public void setKernelFFT(net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> fftKernel)

Sets the FFT kernel as computed, be very careful with this method, if any parameters of the FFT are wrong, this will fail

Parameters:

fftKernel - - the FFT of the kernel

setImgFFT

public void setImgFFT(net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> fftImg)

Sets the FFT image as computed, be very careful with this method, if any parameters of the FFT are wrong, this will fail WARNING: if you do not set keepImgFFT, this image will be modified during convolution

Parameters:

fftImg - - the FFT of the image

convolve

public void convolve()

setupFFTs

public static net.imglib2.util.Pair<net.imglib2.Interval,net.imglib2.Interval> setupFFTs(net.imglib2.Interval imgInterval,
 net.imglib2.Interval kernelInterval,
 long[] min,
 long[] max)

computeImgFFT

public static <R extends net.imglib2.type.numeric.RealType<R>>
net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> computeImgFFT(net.imglib2.Interval imgConvolutionInterval,
 net.imglib2.RandomAccessible<R> img,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> fftFactory,
 ExecutorService service)

computeKernelFFT

public static <R extends net.imglib2.type.numeric.RealType<R>>
net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> computeKernelFFT(net.imglib2.Interval kernelConvolutionInterval,
 long[] min,
 long[] max,
 boolean complexConjugate,
 net.imglib2.RandomAccessible<R> kernel,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> fftFactory,
 ExecutorService service)

computeConvolution

public static <R extends net.imglib2.type.numeric.RealType<R>>
void computeConvolution(net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> fftImg,
 net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> fftKernel,
 net.imglib2.RandomAccessibleInterval<R> output,
 boolean keepImgFFT,
 ExecutorService service)

convolve

public static final <R extends net.imglib2.type.numeric.RealType<R>>
void convolve(net.imglib2.RandomAccessible<R> img,
 net.imglib2.Interval imgInterval,
 net.imglib2.RandomAccessible<R> kernel,
 net.imglib2.Interval kernelInterval,
 net.imglib2.RandomAccessibleInterval<R> output,
 net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> factory,
 int numThreads)

multiplyComplex

public static final void multiplyComplex(net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> img,
 net.imglib2.img.Img<net.imglib2.type.numeric.complex.ComplexFloatType> kernel)

getFFTFactory

protected static net.imglib2.img.ImgFactory<net.imglib2.type.numeric.complex.ComplexFloatType> getFFTFactory(net.imglib2.img.Img<? extends net.imglib2.type.numeric.RealType<?>> img)

setExecutorService

public ExecutorService setExecutorService(ExecutorService service)

createExecutorService

public static final ExecutorService createExecutorService()

Utility function to create an ExecutorService Number of threads utilized matches available processors in runtime.

Returns:

- the new ExecutorService

createExecutorService

public static final ExecutorService createExecutorService(int nThreads)

Utility function to create an ExecutorService

Parameters:

nThreads - - number of threads to utilize

Returns:

- the new ExecutorService