Gauss Package ImgLib2

Revision as of 06:07, 20 December 2011 by StephanP (talk | contribs) (Documentation)
Gaussian Convolution (Fiji/ImgLib2)
Author Stephan Preibisch
Maintainer Stephan Preibisch
Source [1]
Initial release 20 December 2011
Latest version 20 December 2011
Development status active
Website [2]


Gauss Package for ImgLib2

Purpose

The gauss package for ImgLib2 is an generic, optimized implementation of the traditional Gaussian convolution. It can perform anisotropic, n-dimensional convolution on any image or any interval on an image, if required even in-place.

The computation is performed multi-threaded and accesses each pixel of the input and output containers only once to guarantee high performance, even on paged cell containers. The precision of the computation can be of any ImgLib2 NumericType, however, there are more efficient implementations for convolution with float and double precision. Any precision of gaussian convolution can be computed on any type of real valued input data, it will be internally wrapped to either float or double. For other conversions (e.g. perform a gaussian convolution on complex float data with complex double precision) respective converters need to be provided. However, any NumericType can always be convolved with its own precision. Warning: this might reduce the accuracy of the computation significantly if the Type itself is an integer type.

Documentation

The Gauss package for ImgLib2 consists of several classes which abstract the convolution operations to n dimensions. The developer/user should use the static methods provided in the Gauss.java class. It will determine itself which class should be used with which parameters in order to provide the best performance possible.

Computing gaussian convolutions on entire images

For computing a Gaussian convolution on an entire Img<T>, simply call one the following lines of code:

import net.imglib2.algorithm.gauss.Gauss;

// the source
final Img< T > img = ...

// define the sigma for each dimension
final double[] sigma = new double[ img.numDimensions() ];
for ( int d = 0; d < sigma.length; ++d )
    sigma[ d ] = 1 + d;

//
// float-precision
//
// compute with float precision, but on T
final Img< T > convolved = Gauss.inFloat( sigma, img );

// compute with float precision, and output a FloatType Img
final Img< FloatType > convolved = Gauss.toFloat( sigma, img );

// compute with float precision in-place
Gauss.inFloatInPlace( sigma, img );

//
// double-precision
//
// compute with double precision, but on T
final Img< T > convolved = Gauss.inDouble( sigma, img );

// compute with double precision, and output a FloatType Img
final Img< DoubleType > convolved = Gauss.toDouble( sigma, img );

// compute with double precision in-place
Gauss.inDoubleInPlace( sigma, img );

//
// precision defined by the type T itself (this will produce garbage if T has insufficient range 
// or accuracy like ByteType, IntType, etc, but will work nicely on for example ComplexFloatType)
//
// compute with precision of T
final Img< T > convolved = Gauss.inNumericType( sigma, img );

// compute with precision of T in-place
Gauss.inNumericTypeInPlace( sigma, img );

By default, the Gaussian convolution will use the OutOfBoundsMirrorFactory with single boundary. If another OutOfBoundsFactory is desired, it can be defined on any of those methods as follows:

// compute with float precision, but on T using an periodic (FFT-like) strategy where at the end of
// each dimension the image simply starts again
final Img< T > convolved = Gauss.inFloat( sigma, img, 
  new OutOfBoundsPeriodicFactory<FloatType, RandomAccessibleInterval<FloatType>>() ) );

Computing gaussian convolutions on RandomAccessibles with Intervals

For more advanced use of the Gaussian convolution, it accepts RandomAccessibles as input and output, too. In this way

Some examples

// create a new, empty 2-d image
final ArrayImgFactory<FloatType> factory = new ArrayImgFactory<FloatType>();
final Img<FloatType> img = factory.create( new int[]{ 512, 256 }, new FloatType() );

// fill it with some funny content			
int i = 0;
for ( final FloatType f : img )
	f.set( i++ );
			
for ( final FloatType f : img )
	if ( i++ % 7 == 0 || i % 8 == 0 )
		f.set( f.get() * 1.5f );

// show the input			
ImageJFunctions.show( img );

// define the 2-d sigmas
final double[] sigma = new double[] { 2, 0.75 };

// compute a gauss convolution in float precision
ImageJFunctions.show( Gauss.inFloat( sigma, img );	

// compute a Gaussian convolution in-place in a small Interval	
Gauss.inFloat( sigma, Views.extendMirrorSingle( img ), new FinalInterval( new long[]{300,150},
	new long[]{ 400,200 } ), img, new Location( new long[] {300,150} ), img.factory() );

// show the result
ImageJFunctions.show( img );

Implementation