Module imagingbook.common
Package imagingbook.common.filter.generic

Class GenericFilter

java.lang.Object
imagingbook.common.filter.generic.GenericFilter
All Implemented Interfaces:
ProgressReporter
Direct Known Subclasses:
GenericFilterScalar, GenericFilterScalarSeparable, GenericFilterVector, GenericFilterVectorSeparable, TschumperleDericheFilter
public abstract class GenericFilter extends Object implements ProgressReporter

This is the (abstract) root class of the generic filter hierarchy. Generic filters are designed to work with all types of ImageJ images, i.e., sub-classes of ImageProcessor. Filters implemented with this framework use a set of unified image data structures, all based on float values (see PixelPack and PixelPack.PixelSlice). Input images are transparently copied from and back to these float data, thus authors of new filters do not need to concern themselves with the original pixel data types. Behind the scenes, classes GridIndexer2D and OutOfBoundsStrategy are relevant for pixel indexing and out-of-boundary coordinates handling.

Generic filters support multiple passes, the associated control structures are implemented by this class GenericFilter. Most filters only require a single pass. If more passes are required, the concrete (terminal) filter class should override the method passesRequired() to return the required number, which may change dynamically during the execution of the filter (e.g., to reach convergence of some sort). Sub-classes provide definitions for scalar filters, i.e., filters that operate independently on the different components of color images (e.g., see GenericFilterScalar), as opposed to vector vector filters that deal with color datea as vectors (e.g., see GenericFilterVector). In addition, both types provide sub-classes for X/Y-separable versions (see GenericFilterScalarSeparable and GenericFilterVectorSeparable).

In the simplest (though frequent) case a concrete filter class only needs to implement a single method to specify the work to be done for calculating the value of a single image pixel (e.g., see GenericFilterVector.doPixel(PixelPack, int, int) and GenericFilterScalar.doPixel(PixelSlice, int, int). See ExampleFilter3x3Scalar and ExampleFilter3x3Vector for examples.

To apply as filter to a given image, the key method is applyTo(ImageProcessor) (or applyTo(PixelPack) if the pixel data are already available as a PixelPack). All filters operate destructively, i.e., by modifying the supplied image.

GenericFilters support asynchronous progress reporting based on the ProgressMonitor framework. Here is a usage example (from one of the sample plugins):

 ImageProcessor ip = ... // any image
 ...
 GenericFilter filter = new TschumperleDericheFilter();
 try (ProgressMonitor m = new ProgressBarMonitor(filter)) {
     filter.applyTo(ip);
 }

During execution of the filter, the IjProgressBarMonitor instance queries the filter periodically (in a separate thread) for its progress status and updates ImageJ's progress bar.

Version:
2012/01/12

  • Constructor Summary

    Constructors
    Constructor
    Description
    GenericFilter()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final void
    abort()
    This method can be called to abort the filter execution prematurely, e.g.
    void
    applyTo(ImageProcessor ip)
    Applies this filter to the given ImageProcessor, which is modified.
    void
    applyTo(ImageProcessor ip, OutOfBoundsStrategy obs)
    Applies this filter to the given ImageProcessor, which is modified; the specified OutOfBoundsStrategy is used to handle out-of-bounds coordinates.
    void
    applyTo(PixelPack source)
    Applies this filter to the given PixelPack instance, which is modified.
    protected void
    closeFilter()
    This method is called once when the filter terminates.
    protected int
    getDepth()
    Returns the depth (number of components) of the currently processed image.
    protected int
    getHeight()
    Returns the height of the currently processed image.
    protected int
    getPass()
    Returns the current filter pass number, starting with 0.
    final double
    getProgress()
    Returns a value in [0,1) indicating to which degree this task is complete.
    protected int
    getWidth()
    Returns the width of the currently processed image.
    protected void
    initFilter(PixelPack source, PixelPack target)
    This method is called once at the start of the filter execution.
    protected void
    initPass(PixelPack source, PixelPack target)
    This method is called once at the start of each filter pass.
    protected int
    passesRequired()
    Returns the necessary number of passes, which may change during execution of the filter.
    protected double
    reportProgress()
    This method is called asynchonously and may be overridden by the terminal filter class if it does extensive work that should be monitored.
    protected double
    reportProgress(double subProgress)
    This method is used for internal progress reporting through the class hierarchy.
    protected abstract void
    runPass(PixelPack source, PixelPack target)
    This method performs one pass of the filter, it must be implemented by a sub-class.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

  • Method Details

    • getPass

      protected int getPass()
      Returns the current filter pass number, starting with 0.
      Returns:
      the filter pass number

    • getWidth

      protected int getWidth()
      Returns the width of the currently processed image.
      Returns:
      the width of the image

    • getHeight

      protected int getHeight()
      Returns the height of the currently processed image.
      Returns:
      the height of the image

    • getDepth

      protected int getDepth()
      Returns the depth (number of components) of the currently processed image.
      Returns:
      the depth of the image

    • applyTo

      public void applyTo(PixelPack source)
      Applies this filter to the given PixelPack instance, which is modified.
      Parameters:
      source - the image to be filtered

    • applyTo

      public void applyTo(ImageProcessor ip)
      Applies this filter to the given ImageProcessor, which is modified. PixelPack.DefaultOutOfBoundsStrategy is used to handle out-of-bounds coordinates.
      Parameters:
      ip - the image to be filtered

    • applyTo

      public void applyTo(ImageProcessor ip, OutOfBoundsStrategy obs)
      Applies this filter to the given ImageProcessor, which is modified; the specified OutOfBoundsStrategy is used to handle out-of-bounds coordinates.
      Parameters:
      ip - the image to be filtered
      obs - the out-of-bounds strategy to be used

    • initFilter

      protected void initFilter(PixelPack source, PixelPack target)
      This method is called once at the start of the filter execution. It does nothing by default. Concrete filter classes should override this method, e.g., for setting up temporary data structures.
      Parameters:
      source - the image source data
      target - the image target data

    • initPass

      protected void initPass(PixelPack source, PixelPack target)
      This method is called once at the start of each filter pass. It does nothing by default. Concrete filter classes should override this method if needed.
      Parameters:
      source - the image source data
      target - the image target data

    • closeFilter

      protected void closeFilter()
      This method is called once when the filter terminates. It does nothing by default. Concrete filter classes should override this method if needed.

    • passesRequired

      protected int passesRequired()
      Returns the necessary number of passes, which may change during execution of the filter. The value 1 is returned by default. Multi-pass filters must override this method. The filter terminates as soon as the requested number of passes is reached. This this method can be used to terminate filter execution once some desired state has been reached (e.g., convergence). See also getPass().
      Returns:
      the required number of filter passes

    • abort

      protected final void abort()
      This method can be called to abort the filter execution prematurely, e.g. for debugging.

    • runPass

      protected abstract void runPass(PixelPack source, PixelPack target)
      This method performs one pass of the filter, it must be implemented by a sub-class. There is usually no need for a custom filter class to override this method.
      Parameters:
      source - the image source data
      target - the image target data

    • getProgress

      public final double getProgress()
      Description copied from interface: ProgressReporter
      Returns a value in [0,1) indicating to which degree this task is complete.
      Specified by:
      getProgress in interface ProgressReporter
      Returns:
      a value between 0 and 1

    • reportProgress

      protected double reportProgress()
      This method is called asynchonously and may be overridden by the terminal filter class if it does extensive work that should be monitored. In this case the method must return a value between 0 and 1, reflecting the degree of completion (only of the final class's subtask) at the time of invocation. Normally this is not necessary, since the intermediate classes return their own progress state (for the less granular tasks) anyways. The default implementations returns 0 (progress). See FilterProgressExample for an example.
      Returns:
      the degree of completion (0,...,1)

    • reportProgress

      protected double reportProgress(double subProgress)
      This method is used for internal progress reporting through the class hierarchy. It should not be overridden or modified.
      Parameters:
      subProgress - the current progress reported by the immediate sub-task (0,...,1)
      Returns:
      the cumulative progress (0,...,1)