001/**
002 * 
003 */
004package icy.plugin.interface_;
005
006import icy.roi.ROI;
007import icy.roi.ROIDescriptor;
008import icy.sequence.Sequence;
009
010import java.util.List;
011import java.util.Map;
012
013/**
014 * Plugin interface providing the basic functionalities to compute various descriptors for regions
015 * of interest (ROI)
016 * 
017 * @author Stephane Dallongeville, Alexandre Dufour
018 */
019public interface PluginROIDescriptor extends PluginNoEDTConstructor
020{
021    /**
022     * Returns the list of {@link ROIDescriptor} available in this plug-in.<br/>
023     * While simple descriptors usually have just to return a single a real-valued number (e.g.
024     * volume), advanced descriptors may need to produce several results for a given ROI (e.g. a
025     * best-fitting ellipse is defined by multiple parameters), or adjust the name of the
026     * descriptor(s) based on the type of ROI (e.g. "surface" would only apply in 2D, while "volume"
027     * would only apply in 3D).<br/>
028     * Example:
029     * 
030     * <pre>
031     * List<ROIDescriptor> result = ArrayList<ROIDescriptor>();
032     * result.add(new ROIDescriptor("area", Double.class));
033     * result.add(new ROIDescriptor("volume", Double.class));
034     * result.add(new ROIDescriptor("...", Double.class));
035     * </pre>
036     */
037    public List<ROIDescriptor> getDescriptors();
038
039    /**
040     * Computes the descriptor(s) (declared in the {@link #getDescriptors()}) on the specified ROI.<br/>
041     * Depending on the type of descriptor and ROI, this method can return <code>null</code> for some of the
042     * descriptor results.<br/>
043     * Note that using this method may be faster than calling the <code>compute</code> method for
044     * each descriptor separately as some descriptor can group their calculation.
045     * 
046     * @param roi
047     *        the ROI on which the descriptor(s) should be computed
048     * @param sequence
049     *        an optional sequence where the pixel informations can be retrieved
050     * @return a map where each entry associates a descriptor to its value (which can be <code>null</code> if the
051     *         descriptor cannot be computed).
052     * @throws UnsupportedOperationException
053     *         if the type of the given ROI is not supported by this descriptor or if <code>sequence</code> is
054     *         <code>null</code> while the calculation requires it.
055     */
056    public Map<ROIDescriptor, Object> compute(ROI roi, Sequence sequence) throws UnsupportedOperationException;
057}