com.bristle.javalib.awt
Class ImgUtil

java.lang.Object
  com.bristle.javalib.awt.ImgUtil

public class ImgUtil
extends Object

This class contains utility routines for manipulating images.

Usage:
   - The typical scenario for using this class is:
     - To convert an Image to a BufferedImage:
           BufferedImage bi = ImgUtil.toBufferedImage(image);
Assumptions:
Effects:
       - None.
Anticipated Changes:
Notes:
Implementation Notes:
Portability Issues:
Revision History:
   $Log$

Nested Class Summary

static class	ImgUtil.NoImageFoundException This exception is thrown when the specified data source (InputStream, file, etc) contains no image.
static class	ImgUtil.ScaleAlgorithm This class represents an enumerated type that specifies whether scaling of Images should be done with an emphasis on speed or image smoothness.
static class	ImgUtil.Tester Each class contains a Tester inner class with a main() for easier unit testing.

Field Summary

static boolean	blnPRESERVE_ASPECT_RATIO
static int	intMAX_SCALE_CURRENT_SIZE
static int	intMAX_SCALE_DOUBLE_CURRENT_SIZE
static int	intMAX_SCALE_NO_LIMIT
static int	intMAX_SCALE_TRIPLE_CURRENT_SIZE

Constructor Summary

ImgUtil()

Method Summary

static boolean	getAwtHeadless() Return true if AWT is set to run in headless mode.
static Image	getScaledImage(Image img, int intWidth, int intHeight, ImgUtil.ScaleAlgorithm algorithm) Returns a scaled copy of the specified Image.
static Image	readImageFromFile(String strFilename) Read an Image from the specified filename.
static Image	readImageFromInputStream(InputStream in) Read an Image from the specified InputStream.
static void	scaleImageToFileAsJPEG(String strFilenameIn, String strFilenameOut, int intScalePercent, ImgUtil.ScaleAlgorithm algorithm) Copy an image from the specified filename to the specified filename, converting it to a JPEG, and scaling it by the specified percent.
static void	scaleImageToFileAsJPEG(String strFilenameIn, String strFilenameOut, int intWidth, int intHeight, boolean blnPreserveAspectRatio, int intMaxScalePercent, ImgUtil.ScaleAlgorithm algorithm) Copy an image from the specified filename to the specified filename, converting it to a JPEG, and scaling it to the specified size.
static void	scaleImageToOutputStreamAsJPEG(Image img, OutputStream out, int intScalePercent, ImgUtil.ScaleAlgorithm algorithm) Write the specified Image to the specified OutputStream, converting it to a JPEG, and scaling it by the specified percent.
static void	scaleImageToOutputStreamAsJPEG(Image img, OutputStream out, int intWidth, int intHeight, boolean blnPreserveAspectRatio, int intMaxScalePercent, ImgUtil.ScaleAlgorithm algorithm) Write the specified Image to the specified OutputStream, converting it to a JPEG, and scaling it to the specified size.
static void	scaleImageToOutputStreamAsJPEG(InputStream in, OutputStream out, int intScalePercent, ImgUtil.ScaleAlgorithm algorithm) Copy an image from the specified InputStream to the specified OutputStream, converting it to a JPEG, and scaling it by the specified percent.
static void	scaleImageToOutputStreamAsJPEG(InputStream in, OutputStream out, int intWidth, int intHeight, boolean blnPreserveAspectRatio, int intMaxScalePercent, ImgUtil.ScaleAlgorithm algorithm) Copy an image from the specified InputStream to the specified OutputStream, converting it to a JPEG, and scaling it to the specified size.
static void	scaleImageToOutputStreamAsJPEG(String strFilename, OutputStream out, int intScalePercent, ImgUtil.ScaleAlgorithm algorithm) Copy an image from the specified filename to the specified OutputStream, converting it to a JPEG, and scaling it by the specified percent.
static void	scaleImageToOutputStreamAsJPEG(String strFilename, OutputStream out, int intWidth, int intHeight, boolean blnPreserveAspectRatio, int intMaxScalePercent, ImgUtil.ScaleAlgorithm algorithm) Copy an image from the specified filename to the specified OutputStream, converting it to a JPEG, and scaling it to the specified size.
static void	setAwtHeadless() Set AWT to run in headless mode, meaning there is no local graphical display on the server.
static BufferedImage	toBufferedImage(Image img) Returns a BufferedImage from the specified Image.
static void	writeImageToFileAsJPEG(Image img, String strFilename) Write the specified Image to the file with the specified name, converting it to a JPEG.
static void	writeImageToOutputStreamAsJPEG(Image img, OutputStream out) Write the specified Image to the specified OutputStream, converting it to a JPEG.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

blnPRESERVE_ASPECT_RATIO

public static final boolean blnPRESERVE_ASPECT_RATIO

See Also:

Constant Field Values

intMAX_SCALE_CURRENT_SIZE

public static final int intMAX_SCALE_CURRENT_SIZE

See Also:

Constant Field Values

intMAX_SCALE_DOUBLE_CURRENT_SIZE

public static final int intMAX_SCALE_DOUBLE_CURRENT_SIZE

See Also:

Constant Field Values

intMAX_SCALE_TRIPLE_CURRENT_SIZE

public static final int intMAX_SCALE_TRIPLE_CURRENT_SIZE

See Also:

Constant Field Values

intMAX_SCALE_NO_LIMIT

public static final int intMAX_SCALE_NO_LIMIT

See Also:

Constant Field Values

Constructor Detail

ImgUtil

public ImgUtil()

Method Detail

setAwtHeadless

public static void setAwtHeadless()

Set AWT to run in headless mode, meaning there is no local graphical display on the server. This may be required to prevent some of the methods in this class from failing. For example, unless this method is called first, the method getScaledImage() fails with Java 1.4.2, on a Tomcat 4 Web server if there is no X11 server running on the Web server. To avoid the problem on such servers, do one of the following: 1. Call this method after the Web server is started and before any servlet attempts to call getScaledImage() or any other AWT method that has the same problem. Calling it from the init() method of each such servlet might be a good idea. Calling it after the error occurs, in an exception handler, for example, is too late and has no effect. Once the error has occurred, Tomcat must be restarted and this method must be called before the first attempt to call getScaledImage(). 2. Set the environment variable: setenv CATALINA_OPTS -Djava.awt.headless=true before starting the Tomcat server, or 3. In some other way, define java.awt.headless=true in the Java environment of the Tomcat Web server. When the error occurs, it reports either: java.lang.InternalError: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable. or: java.lang.NoClassDefFoundError Don't call this method unnecessarily, because it does the following internally: System.setProperty("java.awt.headless", "true"); which has a global effect on the entire JVM, including other Web apps running in the same Tomcat server. It is because of this global effect that this method is not called automatically by getScaledImage().

getAwtHeadless

public static boolean getAwtHeadless()

Return true if AWT is set to run in headless mode.

Returns:

True if headless; false otherwise.

See Also:

setAwtHeadless()

toBufferedImage

public static BufferedImage toBufferedImage(Image img)

Returns a BufferedImage from the specified Image.

Parameters:

img - The input Image

Returns:

The corresponding BufferedImage

getScaledImage

public static Image getScaledImage(Image img,
                                   int intWidth,
                                   int intHeight,
                                   ImgUtil.ScaleAlgorithm algorithm)

Returns a scaled copy of the specified Image.

Parameters:

img - The input Image

intWidth - The desired Image width, or negative number to maintain the original aspect ratio.

intHeight - The desired Image height, or negative number to maintain the original aspect ratio.

algorithm - Algorithm to use for scaling.

Returns:

The scaled Image

readImageFromInputStream

public static Image readImageFromInputStream(InputStream in)
                                      throws IOException,
                                             ImgUtil.NoImageFoundException

Read an Image from the specified InputStream.

Parameters:

in - The InputStream to read the Image from.

Returns:

The Image, or null if the InputStream was empty.

Throws:

IOException - When an error occurs reading the Image.

ImgUtil.NoImageFoundException - When the InputStream contains no Image.

readImageFromFile

public static Image readImageFromFile(String strFilename)
                               throws IOException,
                                      ImgUtil.NoImageFoundException

Read an Image from the specified filename.

Parameters:

strFilename - The name of the file to read the Image from.

Returns:

The Image, or null if the file was empty.

Throws:

IOException - When an error occurs reading the Image.

ImgUtil.NoImageFoundException - When the file contains no Image.

writeImageToOutputStreamAsJPEG

public static void writeImageToOutputStreamAsJPEG(Image img,
                                                  OutputStream out)
                                           throws IOException

Write the specified Image to the specified OutputStream, converting it to a JPEG.

Parameters:

img - The input Image

out - The OutputStream

Throws:

IOException - When an error occurs writing the Image.

scaleImageToOutputStreamAsJPEG

public static void scaleImageToOutputStreamAsJPEG(Image img,
                                                  OutputStream out,
                                                  int intWidth,
                                                  int intHeight,
                                                  boolean blnPreserveAspectRatio,
                                                  int intMaxScalePercent,
                                                  ImgUtil.ScaleAlgorithm algorithm)
                                           throws IOException

Write the specified Image to the specified OutputStream, converting it to a JPEG, and scaling it to the specified size.

Parameters:

img - The input Image

out - The OutputStream

intWidth - The desired Image width, or negative number to maintain the original aspect ratio.

intHeight - The desired Image height, or negative number to maintain the original aspect ratio.

blnPreserveAspectRatio - If true, preserve the aspect ratio of the Image even if neither intWidth nor intHeight is negative. Scale to the largest size that will fit within both specified dimensions.

intMaxScalePercent - Max percent to scale the image, or negative number for no limit. This is useful to avoid scaling images too much and having them become grainy when scaling to a fixed size. It may be better to be less than the intended size than to be too grainy. Common values are: intMAX_SCALE_CURRENT_SIZE (100%) intMAX_SCALE_DOUBLE_CURRENT_SIZE (200%) intMAX_SCALE_TRIPLE_CURRENT_SIZE (300%) intMAX_SCALE_NO_LIMIT (-1)

algorithm - Algorithm to use for scaling.

Throws:

IOException - When an error occurs reading or writing the Image.

scaleImageToOutputStreamAsJPEG

public static void scaleImageToOutputStreamAsJPEG(InputStream in,
                                                  OutputStream out,
                                                  int intWidth,
                                                  int intHeight,
                                                  boolean blnPreserveAspectRatio,
                                                  int intMaxScalePercent,
                                                  ImgUtil.ScaleAlgorithm algorithm)
                                           throws IOException,
                                                  ImgUtil.NoImageFoundException

Copy an image from the specified InputStream to the specified OutputStream, converting it to a JPEG, and scaling it to the specified size.

Parameters:

in - The InputStream

out - The OutputStream

intWidth - The desired Image width, or negative number to maintain the original aspect ratio.

intHeight - The desired Image height, or negative number to maintain the original aspect ratio.

blnPreserveAspectRatio - If true, preserve the aspect ratio of the Image even if neither intWidth nor intHeight is negative. Scale to the largest size that will fit within both specified dimensions.

intMaxScalePercent - Max percent to scale the image, or negative number for no limit. See scaleImageToOutputStreamAsJPEG(Image, OutputStream, int, int, boolean, int, ScaleAlgorithm)

algorithm - Algorithm to use for scaling.

Throws:

IOException - When an error occurs reading or writing the image.

ImgUtil.NoImageFoundException - When the InputStream contains no Image.

scaleImageToOutputStreamAsJPEG

public static void scaleImageToOutputStreamAsJPEG(String strFilename,
                                                  OutputStream out,
                                                  int intWidth,
                                                  int intHeight,
                                                  boolean blnPreserveAspectRatio,
                                                  int intMaxScalePercent,
                                                  ImgUtil.ScaleAlgorithm algorithm)
                                           throws IOException,
                                                  ImgUtil.NoImageFoundException

Copy an image from the specified filename to the specified OutputStream, converting it to a JPEG, and scaling it to the specified size.

Parameters:

strFilename - The input filename

out - The OutputStream

intWidth - The desired Image width, or negative number to maintain the original aspect ratio.

intHeight - The desired Image height, or negative number to maintain the original aspect ratio.

blnPreserveAspectRatio - If true, preserve the aspect ratio of the Image even if neither intWidth nor intHeight is negative. Scale to the largest size that will fit within both specified dimensions.

intMaxScalePercent - Max percent to scale the image, or negative number for no limit. See scaleImageToOutputStreamAsJPEG(Image, OutputStream, int, int, boolean, int, ScaleAlgorithm)

algorithm - Algorithm to use for scaling.

Throws:

IOException - When an error occurs reading or writing the image.

ImgUtil.NoImageFoundException - When the file contains no Image.

scaleImageToOutputStreamAsJPEG

public static void scaleImageToOutputStreamAsJPEG(Image img,
                                                  OutputStream out,
                                                  int intScalePercent,
                                                  ImgUtil.ScaleAlgorithm algorithm)
                                           throws IOException

Write the specified Image to the specified OutputStream, converting it to a JPEG, and scaling it by the specified percent.

Parameters:

img - The input Image

out - The OutputStream

intScalePercent - The desired scale percent

algorithm - Algorithm to use for scaling.

Throws:

IOException - When an error occurs reading or writing the Image.

scaleImageToOutputStreamAsJPEG

public static void scaleImageToOutputStreamAsJPEG(InputStream in,
                                                  OutputStream out,
                                                  int intScalePercent,
                                                  ImgUtil.ScaleAlgorithm algorithm)
                                           throws IOException,
                                                  ImgUtil.NoImageFoundException

Copy an image from the specified InputStream to the specified OutputStream, converting it to a JPEG, and scaling it by the specified percent.

Parameters:

in - The InputStream

out - The OutputStream

intScalePercent - The desired scale percent

algorithm - Algorithm to use for scaling.

Throws:

IOException - When an error occurs reading or writing the Image.

ImgUtil.NoImageFoundException - When the InputStream contains no Image.

scaleImageToOutputStreamAsJPEG

public static void scaleImageToOutputStreamAsJPEG(String strFilename,
                                                  OutputStream out,
                                                  int intScalePercent,
                                                  ImgUtil.ScaleAlgorithm algorithm)
                                           throws IOException,
                                                  ImgUtil.NoImageFoundException

Copy an image from the specified filename to the specified OutputStream, converting it to a JPEG, and scaling it by the specified percent.

Parameters:

strFilename - The input filename

out - The OutputStream

intScalePercent - The desired scale percent

algorithm - Algorithm to use for scaling.

Throws:

IOException - When an error occurs reading or writing the Image.

ImgUtil.NoImageFoundException - When the file contains no Image.

writeImageToFileAsJPEG

public static void writeImageToFileAsJPEG(Image img,
                                          String strFilename)
                                   throws IOException

Write the specified Image to the file with the specified name, converting it to a JPEG.

Parameters:

img - The input Image

strFilename - The name of the file to write to.

Throws:

IOException - When an error occurs writing the Image.

scaleImageToFileAsJPEG

public static void scaleImageToFileAsJPEG(String strFilenameIn,
                                          String strFilenameOut,
                                          int intWidth,
                                          int intHeight,
                                          boolean blnPreserveAspectRatio,
                                          int intMaxScalePercent,
                                          ImgUtil.ScaleAlgorithm algorithm)
                                   throws IOException,
                                          ImgUtil.NoImageFoundException

Copy an image from the specified filename to the specified filename, converting it to a JPEG, and scaling it to the specified size.

Parameters:

strFilenameIn - The input filename

strFilenameOut - The name of the file to write to.

intWidth - The desired Image width, or negative number to maintain the original aspect ratio.

intHeight - The desired Image height, or negative number to maintain the original aspect ratio.

blnPreserveAspectRatio - If true, preserve the aspect ratio of the Image even if neither intWidth nor intHeight is negative. Scale to the largest size that will fit within both specified dimensions.

intMaxScalePercent - Max percent to scale the image, or negative number for no limit. See scaleImageToOutputStreamAsJPEG(Image, OutputStream, int, int, boolean, int, ScaleAlgorithm)

algorithm - Algorithm to use for scaling.

Throws:

IOException - When an error occurs reading or writing the image.

ImgUtil.NoImageFoundException - When the file contains no Image.

scaleImageToFileAsJPEG

public static void scaleImageToFileAsJPEG(String strFilenameIn,
                                          String strFilenameOut,
                                          int intScalePercent,
                                          ImgUtil.ScaleAlgorithm algorithm)
                                   throws IOException,
                                          ImgUtil.NoImageFoundException

Copy an image from the specified filename to the specified filename, converting it to a JPEG, and scaling it by the specified percent.

Parameters:

strFilenameIn - The input filename

strFilenameOut - The name of the file to write to.

intScalePercent - The desired scale percent

algorithm - Algorithm to use for scaling.

Throws:

IOException - When an error occurs reading or writing the image.

ImgUtil.NoImageFoundException - When the file contains no Image.