FFTConvolution (ImgLib2 Javadocs 0-SNAPSHOT API)

java.lang.Object
- net.imglib2.algorithm.fft2.FFTConvolution<R>

```
public class FFTConvolution<R extends 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 and Description
`FFTConvolution(Img<R> img, Img<R> kernel)` Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
`FFTConvolution(Img<R> img, Img<R> kernel, ExecutorService service)` Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
`FFTConvolution(Img<R> img, Img<R> kernel, 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(Img<R> img, Img<R> kernel, 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(RandomAccessible<R> img, Interval imgInterval, RandomAccessible<R> kernel, Interval kernelInterval, ImgFactory<ComplexFloatType> factory)` Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
`FFTConvolution(RandomAccessible<R> img, Interval imgInterval, RandomAccessible<R> kernel, Interval kernelInterval, ImgFactory<ComplexFloatType> factory, ExecutorService service)` Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
`FFTConvolution(RandomAccessible<R> img, Interval imgInterval, RandomAccessible<R> kernel, Interval kernelInterval, RandomAccessibleInterval<R> output, ImgFactory<ComplexFloatType> factory)` Compute a Fourier space based convolution.
`FFTConvolution(RandomAccessible<R> img, Interval imgInterval, RandomAccessible<R> kernel, Interval kernelInterval, RandomAccessibleInterval<R> output, ImgFactory<ComplexFloatType> factory, ExecutorService service)` Compute a Fourier space based convolution.
`FFTConvolution(RandomAccessibleInterval<R> img, RandomAccessibleInterval<R> kernel, ImgFactory<ComplexFloatType> factory)` Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
`FFTConvolution(RandomAccessibleInterval<R> img, RandomAccessibleInterval<R> kernel, ImgFactory<ComplexFloatType> factory, ExecutorService service)` Compute a Fourier space based convolution in-place (img will be replaced by the convolved result).
`FFTConvolution(RandomAccessibleInterval<R> img, RandomAccessibleInterval<R> kernel, RandomAccessibleInterval<R> output, ImgFactory<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(RandomAccessibleInterval<R> img, RandomAccessibleInterval<R> kernel, RandomAccessibleInterval<R> output, ImgFactory<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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static <R extends RealType<R>> void`	`computeConvolution(Img<ComplexFloatType> fftImg, Img<ComplexFloatType> fftKernel, RandomAccessibleInterval<R> output, boolean keepImgFFT, boolean div, ExecutorService service)`
`static <R extends RealType<R>> Img<ComplexFloatType>`	`computeImgFFT(Interval imgConvolutionInterval, RandomAccessible<R> img, ImgFactory<ComplexFloatType> fftFactory, ExecutorService service)`
`static <R extends RealType<R>> Img<ComplexFloatType>`	`computeKernelFFT(Interval kernelConvolutionInterval, long[] min, long[] max, boolean complexConjugate, RandomAccessible<R> kernel, ImgFactory<ComplexFloatType> fftFactory, ExecutorService service)`
`void`	`convolve()`
`static <R extends RealType<R>> void`	`convolve(RandomAccessible<R> img, Interval imgInterval, RandomAccessible<R> kernel, Interval kernelInterval, RandomAccessibleInterval<R> output, ImgFactory<ComplexFloatType> factory, boolean div, ExecutorService service)`
`static ExecutorService`	`createExecutorService()` Utility function to create an ExecutorService Number of threads utilized matches available processors in runtime.
`static ExecutorService`	`createExecutorService(int nThreads)` Utility function to create an ExecutorService
`ImgFactory<ComplexFloatType>`	`fftImgFactory()`
`boolean`	`getComplexConjugate()`
`boolean`	`getDiv()`
`protected static ImgFactory<ComplexFloatType>`	`getFFTFactory(Img<? extends RealType<?>> img)`
`Img<ComplexFloatType>`	`imgFFT()`
`boolean`	`keepImgFFT()`
`Img<ComplexFloatType>`	`kernelFFT()`
`static void`	`multiplyDivideComplex(Img<ComplexFloatType> img, Img<ComplexFloatType> kernel, boolean div)`
`void`	`setComputeComplexConjugate(boolean complexConjugate)`
`void`	`setDiv(boolean div)`
`void`	`setExecutorService(ExecutorService service)` Set the executor service to use.
`void`	`setFFTImgFactory(ImgFactory<ComplexFloatType> factory)`
`void`	`setImg(RandomAccessible<R> img, Interval imgInterval)`
`void`	`setImg(RandomAccessibleInterval<R> img)`
`void`	`setImgFFT(Img<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(RandomAccessible<R> kernel, Interval kernelInterval)`
`void`	`setKernel(RandomAccessibleInterval<R> kernel)`
`void`	`setKernelFFT(Img<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(RandomAccessibleInterval<R> output)`
`static Pair<Interval,Interval>`	`setupFFTs(Interval imgInterval, 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 Detail
- FFTConvolution
```
public FFTConvolution(Img<R> 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(Img<R> 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(Img<R> img,
                      Img<R> kernel,
                      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(Img<R> img,
                      Img<R> kernel,
                      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(RandomAccessibleInterval<R> img,
                      RandomAccessibleInterval<R> kernel,
                      ImgFactory<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(RandomAccessibleInterval<R> img,
                      RandomAccessibleInterval<R> kernel,
                      ImgFactory<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(RandomAccessibleInterval<R> img,
                      RandomAccessibleInterval<R> kernel,
                      RandomAccessibleInterval<R> output,
                      ImgFactory<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(RandomAccessibleInterval<R> img,
                      RandomAccessibleInterval<R> kernel,
                      RandomAccessibleInterval<R> output,
                      ImgFactory<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(RandomAccessible<R> img,
                      Interval imgInterval,
                      RandomAccessible<R> kernel,
                      Interval kernelInterval,
                      ImgFactory<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(RandomAccessible<R> img,
                      Interval imgInterval,
                      RandomAccessible<R> kernel,
                      Interval kernelInterval,
                      ImgFactory<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(RandomAccessible<R> img,
                      Interval imgInterval,
                      RandomAccessible<R> kernel,
                      Interval kernelInterval,
                      RandomAccessibleInterval<R> output,
                      ImgFactory<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(RandomAccessible<R> img,
                      Interval imgInterval,
                      RandomAccessible<R> kernel,
                      Interval kernelInterval,
                      RandomAccessibleInterval<R> output,
                      ImgFactory<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 Detail

setImg

public void setImg(RandomAccessibleInterval<R> img)

setImg

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

setKernel

public void setKernel(RandomAccessibleInterval<R> kernel)

setKernel

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

setOutput

public void setOutput(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()
```

setDiv
```
public void setDiv(boolean div)
```
Parameters:

div - - perform deconvolution instead of convolution.

getDiv
```
public boolean getDiv()
```

setKeepImgFFT

public void setKeepImgFFT(boolean keep)

keepImgFFT
```
public boolean keepImgFFT()
```

setFFTImgFactory

public void setFFTImgFactory(ImgFactory<ComplexFloatType> factory)

fftImgFactory

public ImgFactory<ComplexFloatType> fftImgFactory()

imgFFT
```
public Img<ComplexFloatType> imgFFT()
```

kernelFFT

public Img<ComplexFloatType> kernelFFT()

setKernelFFT
```
public void setKernelFFT(Img<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(Img<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 Pair<Interval,Interval> setupFFTs(Interval imgInterval,
                                                Interval kernelInterval,
                                                long[] min,
                                                long[] max)

computeImgFFT

public static <R extends RealType<R>> Img<ComplexFloatType> computeImgFFT(Interval imgConvolutionInterval,
                                                                          RandomAccessible<R> img,
                                                                          ImgFactory<ComplexFloatType> fftFactory,
                                                                          ExecutorService service)

computeKernelFFT

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

computeConvolution

public static <R extends RealType<R>> void computeConvolution(Img<ComplexFloatType> fftImg,
                                                              Img<ComplexFloatType> fftKernel,
                                                              RandomAccessibleInterval<R> output,
                                                              boolean keepImgFFT,
                                                              boolean div,
                                                              ExecutorService service)

convolve

public static final <R extends RealType<R>> void convolve(RandomAccessible<R> img,
                                                          Interval imgInterval,
                                                          RandomAccessible<R> kernel,
                                                          Interval kernelInterval,
                                                          RandomAccessibleInterval<R> output,
                                                          ImgFactory<ComplexFloatType> factory,
                                                          boolean div,
                                                          ExecutorService service)

multiplyDivideComplex

public static final void multiplyDivideComplex(Img<ComplexFloatType> img,
                                               Img<ComplexFloatType> kernel,
                                               boolean div)

getFFTFactory

protected static ImgFactory<ComplexFloatType> getFFTFactory(Img<? extends RealType<?>> img)

setExecutorService
```
public void setExecutorService(ExecutorService service)
```
Set the executor service to use. When null, a temporary one will be created in convolve(), using as many Threads as Runtime.availableProcessors(), which will be ExecutorService.shutdownNow() when done. Otherwise, the caller is responsible for shutting down the provided ExecutorService.

Parameters:

service - - Executor service to use.

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

Class FFTConvolution<R extends RealType<R>>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

FFTConvolution

Method Detail

setImg

setImg

setKernel

setKernel

setOutput

setComputeComplexConjugate

getComplexConjugate

setDiv

getDiv

setKeepImgFFT

keepImgFFT

setFFTImgFactory

fftImgFactory

imgFFT

kernelFFT

setKernelFFT

setImgFFT

convolve

setupFFTs

computeImgFFT

computeKernelFFT

computeConvolution

convolve

multiplyDivideComplex

getFFTFactory

setExecutorService

createExecutorService

createExecutorService