package ij.plugin.filter;
import ij.*;
import ij.process.*;
/** ImageJ plugins that process an image may implement this interface.
* In addition to the features of PlugInFilter, it is better suited
* for filters that have a dialog asking for the options or filter
* parameters. It also offers support for preview, for a smooth
* progress bar when processing stacks and for calling back
* the PlugInFilterRunner (needed, e.g., to get the slice number
* when processing a stack in parallel threads).
*<p>
* The sequence of calls to an ExtendedPlugInFilter is the following:
*<p>
* - <code>setup(arg, imp)</code>: The filter should return its flags. <p>
* - <code>showDialog(imp, command, pfr)</code>: The filter should display
* the dialog asking for parameters (if any) and do all operations
* needed to prepare for processing the individual image(s) (E.g.,
* slices of a stack). For preview, a separate thread may call
* <code>setNPasses(nPasses)</code> and <code>run(ip)</code> while
* the dialog is displayed. The filter should return its flags. <p>
* - <code>setNPasses(nPasses)</code>: Informs the filter of the number
* of calls of <code>run(ip)</code> that will follow. <p>
* - <code>run(ip)</code>: Processing of the image(s). With the
* <code>CONVERT_TO_FLOAT</code> flag, this method will be called for
* each color channel of an RGB image. With <code>DOES_STACKS</code>,
* it will be called for each slice of a stack. <p>
* - <code>setup("final", imp)</code>: called only if flag
* <code>FINAL_PROCESSING</code> has been specified.
*<p>
* Flag <code>DONE</code> stops this sequence of calls.
*/
public interface ExtendedPlugInFilter extends PlugInFilter {
/**
* This method is called after <code>setup(arg, imp)</code> unless the
* <code>DONE</code> flag has been set.
* @param imp The active image already passed in the
* <code>setup(arg, imp)</code> call. It will be null, however, if
* the <code>NO_IMAGE_REQUIRED</code> flag has been set.
* @param command The command that has led to the invocation of
* the plugin-filter. Useful as a title for the dialog.
* @param pfr The PlugInFilterRunner calling this plugin-filter.
* It can be passed to a GenericDialog by <code>addPreviewCheckbox</code>
* to enable preview by calling the <code>run(ip)</code> method of this
* plugin-filter. <code>pfr</code> can be also used later for calling back
* the PlugInFilterRunner, e.g., to obtain the slice number
* currently processed by <code>run(ip)</code>.
* @return The method should return a combination (bitwise OR)
* of the flags specified in interfaces <code>PlugInFilter</code> and
* <code>ExtendedPlugInFilter</code>.
*/
public int showDialog(ImagePlus imp, String command, PlugInFilterRunner pfr);
/**
* 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 <code>CONVERT_TO_FLOAT</code>
* 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 <code>CONVERT_TO_FLOAT</code>.
*/
public void setNPasses(int nPasses);
/** Set this flag if the last preview image may be kept as a result.
For stacks, this flag can lead to out-of-sequence processing of the
slices, irrespective of the <code>PARALLELIZE_STACKS<code> flag.
*/
public final int KEEP_PREVIEW = 0x1000000;
}