Module ij
Package ij.plugin.filter

# Class BackgroundSubtracter

java.lang.Object
ij.plugin.filter.BackgroundSubtracter

All Implemented Interfaces:
  `DialogListener`, `ExtendedPlugInFilter`, `PlugInFilter`

public class BackgroundSubtracter extends Object implements ExtendedPlugInFilter, DialogListener
Implements ImageJ's Subtract Background command. Based on the concept of the rolling ball algorithm described in Stanley Sternberg's article, "Biomedical Image Processing", IEEE Computer, January 1983. Imagine that the 2D grayscale image has a third (height) dimension by the image value at every point in the image, creating a surface. A ball of given radius is rolled over the bottom side of this surface; the hull of the volume reachable by the ball is the background. With "Sliding Parabvoloid", the rolling ball is replaced by a sliding paraboloid of rotation with the same curvature at its apex as a ball of a given radius. A paraboloid has the advantage that suitable paraboloids can be found for any image values, even if the pixel values are much larger than a typical object size (in pixels). The paraboloid of rotation is approximated as parabolae in 4 directions: x, y and the two 45-degree directions. Lines of the image in these directions are processed by sliding a parabola against them. Obtaining the hull needs the parabola for a given direction to be applied multiple times (after doing the other directions); in this respect the current code is a compromise between accuracy and speed. For noise rejection, with the sliding paraboloid algorithm, a 3x3 maximum of the background is applied. With both, rolling ball and sliding paraboloid, the image used for calculating the background is slightly smoothened (3x3 average). This can result in negative values after background subtraction. This preprocessing can be disabled. In the sliding paraboloid algorithm, additional code has been added to avoid subtracting corner objects as a background (note that a paraboloid or ball would always touch the 4 corner pixels and thus make them background pixels). This code assumes that corner particles reach less than 1/4 of the image size into the image. Rolling ball code based on the NIH Image Pascal version by Michael Castle and Janice Keller of the University of Michigan Mental Health Research Institute. Sliding Paraboloid by Michael Schmid, 2007. Version 10-Jan-2008

## Field Summary

### Fields inherited from interface ij.plugin.filter.ExtendedPlugInFilter

`KEEP_PREVIEW`

### Fields inherited from interface ij.plugin.filter.PlugInFilter

`CONVERT_TO_FLOAT, DOES_16, DOES_32, DOES_8C, DOES_8G, DOES_ALL, DOES_RGB, DOES_STACKS, DONE, FINAL_PROCESSING, KEEP_THRESHOLD, NO_CHANGES, NO_IMAGE_REQUIRED, NO_UNDO, NO_UNDO_RESET, PARALLELIZE_IMAGES, PARALLELIZE_STACKS, ROI_REQUIRED, SNAPSHOT, STACK_REQUIRED, SUPPORTS_MASKING`

## Constructor Summary

Constructors
Constructor
Description
`BackgroundSubtracter()`

## Method Summary

Modifier and Type
Method
Description
`boolean`
`dialogItemChanged(GenericDialog gd, AWTEvent e)`
This method is invoked by a Generic Dialog if any of the inputs have changed (CANCEL does not trigger it; OK and running the dialog from a macro only trigger the first DialogListener added to a GenericDialog).
`void`
`rollingBallBackground(ImageProcessor ip, double radius, boolean createBackground, boolean lightBackground, boolean useParaboloid, boolean doPresmooth, boolean correctCorners)`
Create or subtract a background, works for all image types.
`void`
`rollingBallBrightnessBackground(ColorProcessor ip, double radius, boolean createBackground, boolean lightBackground, boolean useParaboloid, boolean doPresmooth, boolean correctCorners)`
Create or subtract a background, based on the brightness of an RGB image (keeping the hue of each pixel unchanged)
`void`
`run(ImageProcessor ip)`
Background for any image type
`void`
`setNPasses(int nPasses)`
This method is called by ImageJ to inform the plugin-filter about the passes to its run method.
`int`
`setup(String arg, ImagePlus imp)`
This method is called once when the filter is loaded.
`int`
`showDialog(ImagePlus imp, String command, PlugInFilterRunner pfr)`
This method is called after `setup(arg, imp)` unless the `DONE` flag has been set.
`void`
`subtractBackround(ImageProcessor ip, int ballRadius)`
Depracated.
`void`
`subtractRGBBackround(ColorProcessor ip, int ballRadius)`
Depracated.

### Methods inherited from class java.lang.Object

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

## Constructor Details

### BackgroundSubtracter

public BackgroundSubtracter()

## Method Details

### setup

public int setup(String arg, ImagePlus imp)
Description copied from interface: `PlugInFilter`
This method is called once when the filter is loaded. 'arg', which may be blank, is the argument specified for this plugin in IJ_Props.txt or in the plugins.config file of a jar archive containing the plugin. 'imp' is the currently active image. This method should return a flag word that specifies the filters capabilities.

For Plugin-filters specifying the `PlugInFilter.FINAL_PROCESSING` flag, the setup method will be called again, this time with arg = "final" after all other processing is done.

Specified by:
  `setup` in interface `PlugInFilter`

### showDialog

public int showDialog(ImagePlus imp, String command, PlugInFilterRunner pfr)
Description copied from interface: `ExtendedPlugInFilter`
This method is called after `setup(arg, imp)` unless the `DONE` flag has been set.

Specified by:
  `showDialog` in interface `ExtendedPlugInFilter`
Parameters:
  `imp` - The active image already passed in the `setup(arg, imp)` call. It will be null, however, if the `NO_IMAGE_REQUIRED` flag has been set.
  `command` - The command that has led to the invocation of the plugin-filter. Useful as a title for the dialog.
  `pfr` - The PlugInFilterRunner calling this plugin-filter. It can be passed to a GenericDialog by `addPreviewCheckbox` to enable preview by calling the `run(ip)` method of this plugin-filter. `pfr` can be also used later for calling back the PlugInFilterRunner, e.g., to obtain the slice number currently processed by `run(ip)`.
Returns:
  The method should return a combination (bitwise OR) of the flags specified in interfaces `PlugInFilter` and `ExtendedPlugInFilter`.

### dialogItemChanged

public boolean dialogItemChanged(GenericDialog gd, AWTEvent e)
Description copied from interface: `DialogListener`
This method is invoked by a Generic Dialog if any of the inputs have changed (CANCEL does not trigger it; OK and running the dialog from a macro only trigger the first DialogListener added to a GenericDialog).

Specified by:
  `dialogItemChanged` in interface `DialogListener`
Parameters:
  `gd` - A reference to the GenericDialog.
  `e` - The event that has been generated by the user action in the dialog. Note that `e` is `null` if the dialogItemChanged method is called after the user has pressed the OK button or if the GenericDialog has read its parameters from a macro.
Returns:
  Should be true if the dialog input is valid. False disables the OK button and preview (if any).

### run

public void run(ImageProcessor ip)
Background for any image type

Specified by:
  `run` in interface `PlugInFilter`

### subtractRGBBackround

public void subtractRGBBackround(ColorProcessor ip, int ballRadius)
Depracated. For compatibility with previous ImageJ versions

### subtractBackround

public void subtractBackround(ImageProcessor ip, int ballRadius)
Depracated. For compatibility with previous ImageJ versions

### rollingBallBrightnessBackground

public void rollingBallBrightnessBackground(ColorProcessor ip, double radius, boolean createBackground, boolean lightBackground, boolean useParaboloid, boolean doPresmooth, boolean correctCorners)
Create or subtract a background, based on the brightness of an RGB image (keeping the hue of each pixel unchanged)

Parameters:
  `ip` - The RGB image. On output, it will become the background-subtracted image or the background (depending on `createBackground`).
  `radius` - Radius of the rolling ball creating the background (actually a paraboloid of rotation with the same curvature)
  `createBackground` - Whether to create a background, not to subtract it.
  `lightBackground` - Whether the image has a light background.
  `doPresmooth` - Whether the image should be smoothened (3x3 mean) before creating the background. With smoothing, the background will not necessarily be below the image data.
  `correctCorners` - Whether the algorithm should try to detect corner particles to avoid subtracting them as a background.

### rollingBallBackground

public void rollingBallBackground(ImageProcessor ip, double radius, boolean createBackground, boolean lightBackground, boolean useParaboloid, boolean doPresmooth, boolean correctCorners)
Create or subtract a background, works for all image types. For RGB images, the background is subtracted from each channel separately

Parameters:
  `ip` - The image. On output, it will become the background-subtracted image or the background (depending on `createBackground`).
  `radius` - Radius of the rolling ball creating the background (actually a paraboloid of rotation with the same curvature)
  `createBackground` - Whether to create a background, not to subtract it.
  `lightBackground` - Whether the image has a light background.
  `useParaboloid` - Whether to use the "sliding paraboloid" algorithm.
  `doPresmooth` - Whether the image should be smoothened (3x3 mean) before creating the background. With smoothing, the background will not necessarily be below the image data.
  `correctCorners` - Whether the algorithm should try to detect corner particles to avoid subtracting them as a background.

### setNPasses

public void setNPasses(int nPasses)
Description copied from interface: `ExtendedPlugInFilter`
This method is called by ImageJ to inform the plugin-filter about the passes to its run method. During preview, the number of passes is one (or 3 for RGB images, if `CONVERT_TO_FLOAT` has been specified). When processing a stack, it is the number of slices to be processed (minus one, if one slice has been processed for preview before), and again, 3 times that number for RGB images processed with `CONVERT_TO_FLOAT`.

Specified by:
  `setNPasses` in interface `ExtendedPlugInFilter`