/* DocuImage -- General image interface class

  Digital Image Library servlet components

  Copyright (C) 2001, 2002, 2003 Robert Casties (robcast@mail.berlios.de)

  This program is free software; you can redistribute  it and/or modify it
  under  the terms of  the GNU General  Public License as published by the
  Free Software Foundation;  either version 2 of the  License, or (at your
  option) any later version.
   
  Please read license.txt for the full details. A copy of the GPL
  may be found at http://www.gnu.org/copyleft/lgpl.html

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

 */

package digilib.image;

import java.awt.Rectangle;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Iterator;

import digilib.io.FileOpException;
import digilib.io.ImageInput;
import digilib.util.ImageSize;

/**
 * The basic class for the representation of a digilib image.
 * 
 * The actual image object is hidden in the class, only methods for loading,
 * manipulation, and saving are exported. This strategy enables implementations
 * using different toolkits that rely on different image base classes (like
 * JIMI, Java2D and JAI).
 */
public interface DocuImage {

    /**
     * Loads an image file into the Object.
     * 
     * @param ii
     *            Image File.
     * @throws FileOpException
     *             Exception thrown if any error occurs.
     */
    public void loadImage(ImageInput ii) throws FileOpException;

    /**
     * This DocuImage supports the loadSubImage operation.
     * 
     * @return boolean
     */
    public boolean isSubimageSupported();

    /**
     * Load only a subsampled region of the image file.
     * 
     * @param ii
     * @param region
     * @param subsample
     * @throws FileOpException
     */
    public void loadSubimage(ImageInput ii, Rectangle region, int subsample) throws FileOpException;

    /**
     * Writes the current image to an OutputStream.
     * 
     * The image is encoded to the mime-type <code>mt</code> and sent to the
     * output stream <code>ostream</code>.
     * 
     * Currently only mime-types "image/jpeg" and "image/png" are supported.
     * 
     * @param mt
     *            mime-type of the image to be sent.
     * @param ostream
     *            OutputStream where the image is sent.
     * @throws ImageOpException
     *             Exception in other cases.
     * @throws FileOpException
     *             Exception on sending data
     */
    public void writeImage(String mt, OutputStream ostream) throws ImageOpException, FileOpException;

    /**
     * The width of the current image in pixel.
     * 
     * @return Image width in pixels.
     */
    public int getWidth();

    /**
     * The height of the current image in pixel.
     * 
     * @return Image height in pixels.
     */
    public int getHeight();

    /**
     * The size of the current image in pixel.
     * 
     * @return
     */
    public ImageSize getSize();

    /**
     * The mime-type of the image, i.e. the mime-type of the input that was
     * read.
     * 
     * @return String the mime-type of this image.
     */
    public String getMimetype();

    /**
     * Crops the current image.
     * 
     * Cuts out a region of the size <code>width</code> x <code>height</code> at
     * the offset <code>xoff</code>, <code>yoff</code> from the current image
     * and replaces the current image with the result.
     * 
     * @param xoff
     *            X offset of crop region
     * @param yoff
     *            Y offset of crop region
     * @param width
     *            width of crop region
     * @param height
     *            height of crop region
     * @throws ImageOpException
     */
    public void crop(int xoff, int yoff, int width, int height) throws ImageOpException;

    /**
     * Scales the current image.
     * 
     * Replaces the current image with an image scaled by the factor
     * <code>scale</code>.
     * 
     * @param scale
     *            scaling factor
     * @throws ImageOpException
     */
    public void scale(double scaleX, double scaleY) throws ImageOpException;

    /**
     * Crops and scales the current image.
     * 
     * The current image is cropped to a rectangle of <code>width</code>,
     * <code>height</code> at position <code>x_off</code>, <code>y_off</code>.
     * The resulting image is scaled by the factor <code>scale</code> using the
     * interpolation quality <code>qual</code> (0=worst).
     * 
     * @param x_off
     *            x offset of the crop rectangle in pixel.
     * @param y_off
     *            y offset of the crop rectangle in pixel.
     * @param width
     *            width of the crop rectangle in pixel.
     * @param height
     *            height of the crop rectangle in pixel.
     * @param scale
     *            scaling factor.
     * @param qual
     *            interpolation quality (0=worst).
     * @throws ImageOpException
     *             exception thrown on any error.
     */
    public void cropAndScale(int x_off, int y_off, int width, int height, double scale, int qual) throws ImageOpException;

    /**
     * Rotates the current image.
     * 
     * Replaces the current image with a rotated image. The image is rotated
     * around the center by the <code>angle</code> given in degrees [0, 360]
     * clockwise. Image size and aspect ratio are likely to change.
     * 
     * @param angle
     *            rotation angle in degree
     */
    public void rotate(double angle) throws ImageOpException;

    /**
     * Mirrors the current image.
     * 
     * Replaces the current image with a mirrored image. The mirror axis goes
     * through the center of the image and is rotated by <code>angle</code>
     * degrees. Currently only horizontal and vertical mirroring (0 and 90
     * degree) are supported.
     * 
     * @param angle
     *            angle of mirror axis
     * @throws ImageOpException
     */
    public void mirror(double angle) throws ImageOpException;

    /**
     * Enhances brightness and contrast of the current image.
     * 
     * Replaces the current image with a brightness and contrast enhanced image.
     * Contrast is enhanced by multiplying the pixel value with the constant
     * <code>mult</code>. Brightness is enhanced by adding the constant
     * <code>add</code> to the pixel value. Operation: p1 = (p0*mult)+add.
     * 
     * @param mult
     *            multiplicative constant for contrast enhancement
     * @param add
     *            additive constant for brightness enhancement
     * @throws ImageOpException
     */
    public void enhance(float mult, float add) throws ImageOpException;

    /**
     * Manipulates the colors of the current image.
     * 
     * Replaces the current image with a color modified image. For the red,
     * green and blue color channels all pixel values are multiplied by the
     * constant <code>m</code> and added to the constant <code>a</code>.
     * Operation: p1 = (p0*m)+a.
     * 
     * @param rgbm
     *            multiplicative constants for red, green, blue
     * @param rgba
     *            additive constant for red, green, blue
     * @throws ImageOpException
     */
    public void enhanceRGB(float[] rgbm, float[] rgba) throws ImageOpException;

    /**
     * Operations for colorOps.
     * 
     * GRAYSCALE: cast color image to grayscale NTSC_GRAY: convert color image
     * to grayscale using NTSC formula INVERT: invert colors (every channel
     * separately) MAP_GRAY_BGR: false color image from grayscale (0: blue, 128:
     * green, 255: red)
     * 
     */
    public enum ColorOp {
        GRAYSCALE, NTSC_GRAY, INVERT, MAP_GRAY_BGR
    };

    /**
     * Changes the colors of the current image.
     * 
     * Changes the colors of the current image. Operations are instances of
     * ColorOp:
     * 
     * GRAYSCALE: cast color image to grayscale NTSC_GRAY: convert color image
     * to grayscale using NTSC formula INVERT: invert colors (every channel
     * separately) MAP_GRAY_BGR: false color image from grayscale (0: blue, 128:
     * green, 255: red)
     * 
     * @throws ImageOpException
     */
    public void colorOp(ColorOp op) throws ImageOpException;

    /**
     * Returns the interpolation quality.
     * 
     * @return int
     */
    public int getQuality();

    /**
     * Sets the interpolation quality.
     * 
     * @param quality
     *            The quality to set
     */
    public void setQuality(int quality);

    /**
     * Frees all resources bound to the DocuImage.
     * 
     * Things that should be freed are image objects and open files.
     * 
     */
    public void dispose();

    /**
     * Check image size and type and store in ImageInput ii
     */
    public ImageInput identify(ImageInput ii) throws IOException;

    /**
     * Returns a list of supported image formats
     */
    public Iterator<String> getSupportedFormats();

    /**
     * returns the underlying image as java.awt.Image (if possible, or null)
     * 
     * @return
     */
    public java.awt.Image getAwtImage();
    
    /**
     * returns the version of the DocuImage implementation.
     * @return
     */
    public String getVersion();

}