Skip to main content

Clarity Deconvolution Library

Clarity is an open-source C/C++ library implementing many of the common deconvolution algorithms used in fluorescence microscopy image processing. It is designed specifically for processing 3D images generated from optical sectioning.

Because deconvolution is a computationally intensive process, Clarity uses multithreaded algorithms to make full use of all the cores on modern multi-core computer systems. For even greater performance, the deconvolution algorithms can optionally run on commodity graphics processing units that feature hundreds of computing cores. Support for acceleration on graphics processing units is currently limited to NVIDIA graphics cards.

Deconvolution Algorithms Implemented

Clarity features implementations of several standard deconvolution algorithms:

  • Wiener filter
  • Jansson-van Cittert iterative
  • Maximum likelihood iterative

We are working on implementing a blind deconvolution algorithm and will include that in a future release.

Library Usage

The Clarity library consists of a few simple C-style functions documented here. A typical example of library usage is provided below.

#include <cstdio>
#include <cmath>

#include <Clarity.h>

#include "../common/Test_Common.h"

int main(int argc, char* argv[]) {
  float *inputImage, *kernelImage;
  Clarity_Dim3 imageDims; // Image dimensions
  Clarity_Dim3 kernelDims; // Kernel dimensions

  // Initialize image data arrays.
  inputImage  = Test_GenerateTrueImage(&imageDims);
  kernelImage = Test_GenerateGaussianKernel(&kernelDims, 3.0f);

  // Initialize Clarity by registering this application as a client.
  Clarity_Register();

  // We'll create test data here by convolving the input image with the PSF.
  float *convolvedImage =
    (float *) malloc(sizeof(float)*imageDims.x*imageDims.y*imageDims.z);
  Clarity_Convolve(inputImage, imageDims, kernelImage, kernelDims,
                   convolvedImage);

  // We need to allocate memory for the deconvolution result
  float *deconvolvedImage =
    (float *) malloc(sizeof(float)*imageDims.x*imageDims.y*imageDims.z);

  // Now we are ready to apply a deconvolution algorithm. We'll try the
  // maximum likelihood algorithm.
  int iterations = 10;
  Clarity_MaximumLikelihoodDeconvolve(convolvedImage, imageDims,
    kernelImage, kernelDims, deconvolvedImage, iterations);

  // See how far off the deconvolved image is from the known input image.
  Test_ReportMatch(inputImage, deconvolvedImage, imageDims);

  // Free up the memory used by images
  free(inputImage);
  free(kernelImage);
  free(convolvedImage);
  free(deconvolvedImage);

  // Unregister this application as a client.
  Clarity_UnRegister();

  return 0;
}

Further examples can be found under the ‘tests’ directory in the source code distribution.

Dependencies

  • FFTW – Clarity uses this open-source software for its high-performance and multi-threaded Fast Fourier Transform algorithm.
  • CUDA – Clarity can optionally be built with CUDA support for accelerating deconvolution by using graphics processing units from NVIDIA. CUDA is supported on graphics cards in the GeForce 8 series or above and the Quadro FX series.

Build Instructions

Clarity uses the cross-platform CMake build system, the latest version of which can be downloaded here. For managing CUDA code, it uses the FindCuda.cmake script from Abe Stephens at the University of Utah.

Using this build system, we have successfully built Clarity on the following operating system and compiler combinations:

  • Windows XP, Visual Studio 2005
  • RedHat Enterprise Linux 64-bit, gcc 4.1.2
  • Mac OS X, 10.5.5 with XCode 3.0 (gcc version 4.0.1)

The build process consists of just a few steps:

  1. The most up-to-date version of Clarity is available at github. Alternatively, you can download the Clarity source code from here and unzip the source code.
  2. If building on Windows, download and install/unzip FFTW3 from http://www.fftw.org/install/windows.html. Follow the instructions on that page to create the ‘.lib’ files. If building on Linux, download the source from http://www.fftw.org/download.html. Untar the file and go to the fftw source library. Run the ‘configure’ script with the options ‘–enable-single’,  ‘–enable-threads’, and ‘–with-pic.
  3. Fire up CMake. Set the Clarity root directory as the source code directory, and pick a build directory.
  4. Set BUILD_SHARED_LIBS to “ON” if you so choose.
  5. If you want to build with CUDA-acceleration, set BUILD_WITH_CUDA to “ON”, and continue with these directions. Otherwise, skip to Step 7.
  6. Download and install CUDA Toolkit, Version 2.0 or later from http://developer.nvidia.com/object/cuda.html. Pick the default install directory if you can, otherwise remember where you installed CUDA. If you are on a system with a CUDA-enabled graphics card, you should probably also install the latest NVIDIA display drivers.
  7. Configure the CUDA settings, set CUDA_BUILD_TYPE to “Device”. If CUDA_INSTALL_PREFIX does not give a valid path name, set the path to your CUDA Toolkit installation directory.
  8. In CMake, set FFTW_INCLUDE_DIR to the directory where you installed FFTW3, and set FFTW_LIBRARY to that same directory but with libfftw3f-3.lib appended to the end (libfftw3f.a on linux and Mac OS X).
  9. If you are compiling with gcc, switch to the advanced mode (type “t” in linux, click the “Advanced” checkbox in Windows). Under CMAKE_EXE_LINKER_FLAGS, add the -lpthread and -lgomp options.
  10. Click “Configure” (type “c” in linux) and click “OK” (type “g” in linux). CMake will build the project files (makefiles) and exit.
  11. Navigate to the Clarity build directory you created in Step 2. Under Windows, open Clarity.sln. Under linux, type “make”.
  12. Select a build configuration and build the solution.

License

Clarity is released under the GNU Public License (GPL). For license terms of the software that Clarity uses, please see the licenses directory at the top level of the source code distribution.

Applications Using Clarity

  • ImageSurfer

If your program uses Clarity and you would like to see it listed here, please contact Cory Quammen.

Further Information

For more information on Clarity or to contribute to the code base, please contact Cory Quammen.

Last updated 2008-12-14