Convolve 3D

Convolve 3D

Author: Bob Dougherty (rpd@optinav.com)

Installation: Download Convolve_3D.java or Convolve_3D.class and place it in the Plugins folder.

Description: ImageJ plugin to perform 2D or 3D convolution of two images or stacks: an "image" and a PSF. The width, height and depth of the stacks are not restricted and not required to match in any way (except the PSF image cannot be larger in any dimension). The spacings between the pixels and the the slices should agree between the image and the PSF: dx_image = dx_psf, dy_image = dy_psf, and dz_psf = dz_image. Use of a single-slice PSF gives 2D convolution of each slice in the image stack with the PSF, but convolving the slices separately may be faster. All image types except RGB are supported, but the output is always 32-bit, and cropped to the dimensions of the image input. Masking or mirroring are optionally applied to produce non-cyclic convolution. As of Version 3, there is an option to skip the anti-alias padding (by a factor of 1.5) and only pad to the nearest power of 2. This saves a lot of time and memory, and seems to give better results for correlation coefficient analysis (also new for in Version 3).
The "center point" for the PSF in each coordinate is (int)(n/2). For example, if the PSF is supplied as an 8x11 pixel image with 3 slices, then the center is pixel (4,5) in the second slice.

The Correlation option evaluates correlation instead of convolution.

The Correlation Coefficient option computes correlation and normalizes the result so that perfectly matched stacks would give a peak of 1. It also outputs the peak correation coefficient and the 3D offset in pixels in a message box. If this peak is all that is needed, then the "Create Output" box should be deselected to save memory. The Correlation Coefficient option overrides the inputs "Correlate" (yes) and "Normalize." One use of Correlation Coefficient is to determine the degree of alignment of two stacks. Perfect alignment should give an offset of 0 0 0. Notes: it may be necessary to experiment with the "Extension Method" to aviod incorrect peaks that can happen in several ways. As noted, the anti-alias padding option may not be helpful here because it increases opportunities for incorrect peaks, especially with large offsets. The Laplacian option applies a 3D Laplacian to the output; this can help to sharpen the peak and distinguish it from artifacts.

The plugin Gaussian PSF 3D can be used to generate a simple PSF stack for blur simulation. Gaussian_PSF_3D.java or Gaussian_PSF_3D.class. Also, there is a 3D PSF plugin for a diffraction limited microscope at Diffraction PSF 3D.

Example: Download a group photo from the ImageJ conference and apply some processing with the following macro. (The photo without processing can be seen at cimg1587.)
run("URL...", "url=http://www.optinav.com/Wayne_ImageJ_Conference_Photos/image/cimg1587.jpg");
run("Bandpass Filter...", "filter_large=10 filter_small=0 suppress=None tolerance=5 autoscale saturate");
run("Subtract Background...", "rolling=10");
run("8-bit");
setMinAndMax(0, 72);
run("Apply LUT");

Make a separate image of Wayne with this macro. Note that the left-top corner of the rectangle is (68, 114).
makeRectangle(68, 144, 25, 30);
run("Duplicate...", "title=wayne.jpg");

Run Convolve 3D in correlate mode to find Wayne in the image:
run("Convolve 3D", "image=cimg1587.jpg psf=wayne.jpg extension=[Zero Pad (usually best)] correlate normalize correlation laplacian create output=Laplacian_of_CC");

Note the peak output report of 68 144 0, giving the location that the PSF image (Wayne's) would be inserted into the first image to overlay the region of best correlation. The offset in the slice direction is 0 becase this is a 2D example. The output image of the Laplacian of the correlation coefficient shows a spot at x=252, y = 82. The location of this spot is relative to the center of the image at x = 640/2 = 320, y = 453/2 = 226. In other words, 320 - 252 = 68, 226 - 82 = 144. Sometimes wrapping by the dimensions of an internally produced, enlarged, image needs to be applied to map the correlation peaks to the offset. This wrapping is usually only needed for large offsets. The processing applied to the image before the correlation was intended to increase the contrast of the correlation operation. It would have been less important with a larger second image.

History: Version 0: 4/28/2005
Version 1: 4/30/2005 Mirror and Periodic extension options; Title input.
Version 1.1 5/2/2005 Improved performance for 2D images.
Version 2 5/23/2006 (not posted) Correlation option.
Version 3 8/4/2006 Correlation coeffieienct option. Option to skip anti-alias image expansion.
Version 3.1 8/4/2006 Fixed a bug that caused an exception with non-matching stack dimensions.
Version 3.2 8/4/2006 Fixed a bug that caused CC output when not requested. Added Laplacian option.
Version 3.3 8/6/2006 Reversed sign and improved "wrapping" of CC peak report.

License:
Copyright (c) 2005, 2006 OptiNav, Inc.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of OptiNav, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ImageJ: ImageJ can be freely downloaded from the ImageJ web site.

Author:	Bob Dougherty (rpd@optinav.com)
Installation:	Download Convolve_3D.java or Convolve_3D.class and place it in the Plugins folder.
Description:	ImageJ plugin to perform 2D or 3D convolution of two images or stacks: an "image" and a PSF. The width, height and depth of the stacks are not restricted and not required to match in any way (except the PSF image cannot be larger in any dimension). The spacings between the pixels and the the slices should agree between the image and the PSF: dx_image = dx_psf, dy_image = dy_psf, and dz_psf = dz_image. Use of a single-slice PSF gives 2D convolution of each slice in the image stack with the PSF, but convolving the slices separately may be faster. All image types except RGB are supported, but the output is always 32-bit, and cropped to the dimensions of the image input. Masking or mirroring are optionally applied to produce non-cyclic convolution. As of Version 3, there is an option to skip the anti-alias padding (by a factor of 1.5) and only pad to the nearest power of 2. This saves a lot of time and memory, and seems to give better results for correlation coefficient analysis (also new for in Version 3). The "center point" for the PSF in each coordinate is (int)(n/2). For example, if the PSF is supplied as an 8x11 pixel image with 3 slices, then the center is pixel (4,5) in the second slice. The Correlation option evaluates correlation instead of convolution. The Correlation Coefficient option computes correlation and normalizes the result so that perfectly matched stacks would give a peak of 1. It also outputs the peak correation coefficient and the 3D offset in pixels in a message box. If this peak is all that is needed, then the "Create Output" box should be deselected to save memory. The Correlation Coefficient option overrides the inputs "Correlate" (yes) and "Normalize." One use of Correlation Coefficient is to determine the degree of alignment of two stacks. Perfect alignment should give an offset of 0 0 0. Notes: it may be necessary to experiment with the "Extension Method" to aviod incorrect peaks that can happen in several ways. As noted, the anti-alias padding option may not be helpful here because it increases opportunities for incorrect peaks, especially with large offsets. The Laplacian option applies a 3D Laplacian to the output; this can help to sharpen the peak and distinguish it from artifacts. The plugin Gaussian PSF 3D can be used to generate a simple PSF stack for blur simulation. Gaussian_PSF_3D.java or Gaussian_PSF_3D.class. Also, there is a 3D PSF plugin for a diffraction limited microscope at Diffraction PSF 3D.
Example:	Download a group photo from the ImageJ conference and apply some processing with the following macro. (The photo without processing can be seen at cimg1587.) run("URL...", "url=http://www.optinav.com/Wayne_ImageJ_Conference_Photos/image/cimg1587.jpg"); run("Bandpass Filter...", "filter_large=10 filter_small=0 suppress=None tolerance=5 autoscale saturate"); run("Subtract Background...", "rolling=10"); run("8-bit"); setMinAndMax(0, 72); run("Apply LUT"); Make a separate image of Wayne with this macro. Note that the left-top corner of the rectangle is (68, 114). makeRectangle(68, 144, 25, 30); run("Duplicate...", "title=wayne.jpg"); Run Convolve 3D in correlate mode to find Wayne in the image: run("Convolve 3D", "image=cimg1587.jpg psf=wayne.jpg extension=[Zero Pad (usually best)] correlate normalize correlation laplacian create output=Laplacian_of_CC"); Note the peak output report of 68 144 0, giving the location that the PSF image (Wayne's) would be inserted into the first image to overlay the region of best correlation. The offset in the slice direction is 0 becase this is a 2D example. The output image of the Laplacian of the correlation coefficient shows a spot at x=252, y = 82. The location of this spot is relative to the center of the image at x = 640/2 = 320, y = 453/2 = 226. In other words, 320 - 252 = 68, 226 - 82 = 144. Sometimes wrapping by the dimensions of an internally produced, enlarged, image needs to be applied to map the correlation peaks to the offset. This wrapping is usually only needed for large offsets. The processing applied to the image before the correlation was intended to increase the contrast of the correlation operation. It would have been less important with a larger second image.
History:	Version 0: 4/28/2005 Version 1: 4/30/2005 Mirror and Periodic extension options; Title input. Version 1.1 5/2/2005 Improved performance for 2D images. Version 2 5/23/2006 (not posted) Correlation option. Version 3 8/4/2006 Correlation coeffieienct option. Option to skip anti-alias image expansion. Version 3.1 8/4/2006 Fixed a bug that caused an exception with non-matching stack dimensions. Version 3.2 8/4/2006 Fixed a bug that caused CC output when not requested. Added Laplacian option. Version 3.3 8/6/2006 Reversed sign and improved "wrapping" of CC peak report.
License:	Copyright (c) 2005, 2006 OptiNav, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of OptiNav, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
ImageJ:	ImageJ can be freely downloaded from the ImageJ web site.