/**
 * 
 */
package ie.dcu.eval;

import ie.dcu.matrix.ByteMatrix;
import ie.dcu.segment.SegmentationMask;

/**
 * Interface for a class that is capable of evaluating a segmentation mask
 * against a ground truth.
 * 
 * @author Kevin McGuinness
 */
public interface Evaluator {
	
	/**
	 * Value for the foreground pixels.
	 */
	public static final byte FG = SegmentationMask.FOREGROUND;
	
	/**
	 * Value for the background pixels.
	 */
	public static final byte BG = SegmentationMask.BACKGROUND;
	
	/**
	 * Returns the name of the evaluator.
	 * 
	 * @return The evaluator name. (never <code>null</code>).
	 */
	public String getName();


	/**
	 * Returns a short description of the evaluator.
	 * 
	 * @return A description (never <code>null</code>).
	 */
	public String getDescription();
	
	
	/**
	 * Returns the name of the author or vendor.
	 * 
	 * @return The vendor.
	 */
	public String getVendor();
	
	
	/**
	 * Run the evaluator on the given mask and ground truth.
	 * 
	 * @param mask
	 *          The segmentation mask to evaluate.
	 * @param gt
	 *          The ground truth to evaluate against.
	 * @throws IllegalArgumentException
	 *           If the mask or ground truth are <code>null</code>, if they do
	 *           not have the same dimensions, or if they contain invalid pixel
	 *           values.
	 * 
	 */
	public void run(ByteMatrix mask, ByteMatrix gt)
		throws IllegalArgumentException;
	
	
	/**
	 * Returns the names of the measures generated by this evaluator.
	 * 
	 * @return The names of the generated measures.
	 */
	public String[] getMeasures();
	
	
	/**
	 * Get the computed value of the measure with the given name.
	 * 
	 * @param name
	 *          The measure name.
	 * @return The value of the computed measure.
	 * 
	 * @throws IllegalStateException
	 *           If the run method was not previously called successfully.
	 * @throws IllegalArgumentException
	 *           If the name is not in the array returned by {@link #getMeasures()}.
	 */
	public double getMeasure(String name) 
		throws IllegalStateException, IllegalArgumentException;
}