com.alkacon.simapi

Class Simapi

java.lang.Object

com.alkacon.simapi.Simapi

public class Simapi
extends java.lang.Object

SIMple IMage API (SIMAPI) that provides convenient access to commonly used imaging operations.

Author:

Alexander Kandzior

Field Summary

Fields

Modifier and Type	Field and Description
static java.awt.Color	COLOR_TRANSPARENT Constant to identify a transparent background fill color.
static int	POS_CENTER Position indicator: Center (default).
static int	POS_DOWN_LEFT Position indicator: Down left.
static int	POS_DOWN_RIGHT Position indicator: Down right.
static int	POS_STRAIGHT_DOWN Position indicator: Straight down.
static int	POS_STRAIGHT_LEFT Position indicator: Straight left.
static int	POS_STRAIGHT_RIGHT Position indicator: Straight right.
static int	POS_STRAIGHT_UP Position indicator: Straight up.
static int	POS_UP_LEFT Position indicator: Up left.
static int	POS_UP_RIGHT Position indicator: Up right.
static int	RENDER_MEDIUM Indicates to use the MEDIUM render settings.
static int	RENDER_QUALITY Indicates to use the QUALITY render settings (default).
static int	RENDER_SPEED Indicates to use the SPEED render settings.
static java.lang.String	TYPE_BMP Constant to identify the BMP image type.
static java.lang.String	TYPE_GIF Constant to identify the GIF image type.
static java.lang.String	TYPE_JPEG Constant to identify the JPEG image type.
static java.lang.String	TYPE_PNG Constant to identify the PNG image type.
static java.lang.String	TYPE_PNM Constant to identify the PNM image type.
static java.lang.String	TYPE_TIFF Constant to identify the TIFF image type.

Constructor Summary

Constructors

Constructor and Description
Simapi() Creates a new simapi instance using the default render settings (RENDER_QUALITY).
Simapi(RenderSettings renderSettings) Creates a new simapi instance with the specified render settings.

Method Summary

Methods

Modifier and Type	Method and Description
java.awt.image.BufferedImage	applyFilter(java.awt.image.BufferedImage image, java.awt.image.ImageFilter filter) Applies the given filter to the image.
java.awt.Rectangle	applyFilterDimensions(int width, int height) Calculates the image size for an image after all filters returned by RenderSettings.getImageFilters() have been applied.
java.awt.image.BufferedImage	applyFilters(java.awt.image.BufferedImage image) Applies all filters returned by RenderSettings.getImageFilters() to the given image.
protected java.awt.image.BufferedImage	createImage(java.awt.image.ColorModel colorModel, int width, int height) Creates a buffered image that has the given dimensions and uses the given color model.
java.awt.image.BufferedImage	crop(java.awt.image.BufferedImage image, int width, int height, int cropPosition) Crops an image according to the width and height specified.
java.awt.image.BufferedImage	crop(java.awt.image.BufferedImage image, int x, int y, int width, int height) Crops a part of the given image from the specified x,y point to the given width,height.
java.awt.image.BufferedImage	crop(java.awt.image.BufferedImage image, int x, int y, int width, int height, java.awt.Color backgroundColor) Crops a part of the given image from the specified x,y point to the given width,height.
java.awt.image.BufferedImage	cropToSize(java.awt.image.BufferedImage image, int x, int y, int width, int height, int targetWidth, int targetHeight) Crops a part of the given image from the specified x,y point to the given width,height, and then resizes this cropped image to the dimensions specified in targetWidth,targetHeight.
java.awt.image.BufferedImage	cropToSize(java.awt.image.BufferedImage image, int x, int y, int width, int height, int targetWidth, int targetHeight, java.awt.Color backgroundColor) Crops a part of the given image from the specified x,y point to the given width,height, and then resizes this cropped image to the dimensions specified in targetWidth,targetHeight.
protected static java.awt.image.BufferedImage	ensureImageIsSystemType(java.awt.image.BufferedImage image, boolean allowTransparent) Returns an image that is ensured the be of either BufferedImage.TYPE_INT_RGB or BufferedImage.TYPE_INT_ARGB.
byte[]	getBytes(java.awt.image.BufferedImage image, java.lang.String type) Returns the byte contents of the given image.
static java.lang.String	getImageType(java.lang.String filename) Returns the image type from the given file name based on the file suffix (extension) and the available image writers.
static java.awt.image.BufferedImage	read(byte[] source) Loads an image from a byte array
static java.awt.image.BufferedImage	read(java.io.File source) Loads an image from a local file.
static java.awt.image.BufferedImage	read(java.io.InputStream source) Loads an image from an InputStream.
static java.awt.image.BufferedImage	read(java.lang.String source) Loads an image from a local file whose path is supplied as a String
static java.awt.image.BufferedImage	read(java.net.URL source) Loads an image from a URL.
java.awt.image.BufferedImage	reduceColors(java.awt.image.BufferedImage image, int maxColors, boolean alphaToBitmask) Reduces the colors in the given image to the given maximum color number.
java.awt.image.BufferedImage	resize(java.awt.image.BufferedImage image, int width, int height) Resizes an image according to the width and height specified.
java.awt.image.BufferedImage	resize(java.awt.image.BufferedImage image, int width, int height, boolean bestfit) Resizes an image according to the width and height specified, keeping the aspect ratio if required.
java.awt.image.BufferedImage	resize(java.awt.image.BufferedImage image, int width, int height, boolean bestfit, boolean blowup) Resizes an image according to the width and height specified, keeping the aspect ratio if required.
java.awt.image.BufferedImage	resize(java.awt.image.BufferedImage image, int width, int height, java.awt.Color backgroundColor, int position) Resizes the given image to best fit into the given dimensions (only if it does not already fit in the dimensions), placing the scaled image at the indicated position on a background with the given color.
java.awt.image.BufferedImage	resize(java.awt.image.BufferedImage image, int width, int height, java.awt.Color backgroundColor, int position, boolean blowup) Resizes the given image to best fit into the given dimensions (only if it does not already fit in the dimensions), placing the scaled image at the indicated position on a background with the given color.
java.awt.image.BufferedImage	resize(java.awt.image.BufferedImage image, int width, int height, int position) Resizes an image according to the width and height specified, cropping the image along the sides in case the required height and width can not be reached without changing the apsect ratio of the image.
java.awt.image.BufferedImage	scale(java.awt.image.BufferedImage image, float scale) Scales an image according to the given scale factor.
java.awt.image.BufferedImage	scale(java.awt.image.BufferedImage image, float widthScale, float heightScale) Scale the image with different ratios along the width and height.
java.awt.image.BufferedImage	scale(java.awt.image.BufferedImage image, float widthScale, float heightScale, int targetWidth, int targetHeight) Scale the image with different ratios along the width and height to the given target dimensions.
java.awt.image.BufferedImage	scale(java.awt.image.BufferedImage image, int targetWidth, int targetHeight) Scale the image to the width and height to the given target dimensions.
void	write(java.awt.image.BufferedImage image, java.io.File destination, java.lang.String type) Writes an image to a local file.
protected void	write(java.awt.image.BufferedImage im, java.lang.Object output, java.lang.String formatName) Writes an image to the given output object, using the the given quality.
void	write(java.awt.image.BufferedImage image, java.io.OutputStream destination, java.lang.String type) Writes an image to an output stream.
void	write(java.awt.image.BufferedImage image, java.lang.String destination, java.lang.String type) Writes an image to a local file.

Methods inherited from class java.lang.Object

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

Field Detail

COLOR_TRANSPARENT

public static final java.awt.Color COLOR_TRANSPARENT

Constant to identify a transparent background fill color.

POS_CENTER

public static final int POS_CENTER

Position indicator: Center (default).

See Also:

Constant Field Values

POS_DOWN_LEFT

public static final int POS_DOWN_LEFT

Position indicator: Down left.

See Also:

Constant Field Values

POS_DOWN_RIGHT

public static final int POS_DOWN_RIGHT

Position indicator: Down right.

See Also:

Constant Field Values

POS_STRAIGHT_DOWN

public static final int POS_STRAIGHT_DOWN

Position indicator: Straight down.

See Also:

Constant Field Values

POS_STRAIGHT_LEFT

public static final int POS_STRAIGHT_LEFT

Position indicator: Straight left.

See Also:

Constant Field Values

POS_STRAIGHT_RIGHT

public static final int POS_STRAIGHT_RIGHT

Position indicator: Straight right.

See Also:

Constant Field Values

POS_STRAIGHT_UP

public static final int POS_STRAIGHT_UP

Position indicator: Straight up.

See Also:

Constant Field Values

POS_UP_LEFT

public static final int POS_UP_LEFT

Position indicator: Up left.

See Also:

Constant Field Values

POS_UP_RIGHT

public static final int POS_UP_RIGHT

Position indicator: Up right.

See Also:

Constant Field Values

RENDER_MEDIUM

public static final int RENDER_MEDIUM

Indicates to use the MEDIUM render settings.

See Also:

Constant Field Values

RENDER_QUALITY

public static final int RENDER_QUALITY

Indicates to use the QUALITY render settings (default).

See Also:

Constant Field Values

RENDER_SPEED

public static final int RENDER_SPEED

Indicates to use the SPEED render settings.

See Also:

Constant Field Values

TYPE_BMP

public static final java.lang.String TYPE_BMP

Constant to identify the BMP image type.

See Also:

Constant Field Values

TYPE_GIF

public static final java.lang.String TYPE_GIF

Constant to identify the GIF image type.

See Also:

Constant Field Values

TYPE_JPEG

public static final java.lang.String TYPE_JPEG

Constant to identify the JPEG image type.

See Also:

Constant Field Values

TYPE_PNG

public static final java.lang.String TYPE_PNG

Constant to identify the PNG image type.

See Also:

Constant Field Values

TYPE_PNM

public static final java.lang.String TYPE_PNM

Constant to identify the PNM image type.

See Also:

Constant Field Values

TYPE_TIFF

public static final java.lang.String TYPE_TIFF

Constant to identify the TIFF image type.

See Also:

Constant Field Values

Constructor Detail

Simapi

public Simapi()

Creates a new simapi instance using the default render settings (RENDER_QUALITY).

*

Simapi

public Simapi(RenderSettings renderSettings)

Creates a new simapi instance with the specified render settings.

Parameters:

renderSettings - the render settings to use

Method Detail

getImageType

public static java.lang.String getImageType(java.lang.String filename)

Returns the image type from the given file name based on the file suffix (extension) and the available image writers.

For example, for the file name "alkacon.gif" the type is GIF, for "alkacon.jpeg" is is "JPEG" etc.

In case the input filename has no suffix, or there is no known image writer for the format defined by the suffix, null is returned.

Any non-null result can be used if an image type input value is required.

Parameters:

filename - the file name to get the type for

Returns:

the image type from the given file name based on the suffix and the available image writers, or null if no image writer is available for the format

read

public static java.awt.image.BufferedImage read(byte[] source)
                                         throws java.io.IOException

Loads an image from a byte array

Parameters:

source - the byte array to read the image from

Returns:

the loaded image

Throws:

java.io.IOException - in case the image could not be loaded

read

public static java.awt.image.BufferedImage read(java.io.File source)
                                         throws java.io.IOException

Loads an image from a local file.

Parameters:

source - the file to read the input image from

Returns:

the loaded image

Throws:

java.io.IOException - in case the image could not be loaded

read

public static java.awt.image.BufferedImage read(java.io.InputStream source)
                                         throws java.io.IOException

Loads an image from an InputStream.

Parameters:

source - the input stream to read the input image from

Returns:

the loaded image

Throws:

java.io.IOException - in case the image could not be loaded

read

public static java.awt.image.BufferedImage read(java.lang.String source)
                                         throws java.io.IOException

Loads an image from a local file whose path is supplied as a String

Parameters:

source - the path to the local file to read the input image from

Returns:

the loaded image

Throws:

java.io.IOException - in case the image could not be loaded

read

public static java.awt.image.BufferedImage read(java.net.URL source)
                                         throws java.io.IOException

Loads an image from a URL.

Parameters:

source - the URL to read the input image from

Returns:

the loaded image

Throws:

java.io.IOException - in case the image could not be loaded

ensureImageIsSystemType

protected static java.awt.image.BufferedImage ensureImageIsSystemType(java.awt.image.BufferedImage image,
                                                   boolean allowTransparent)

Returns an image that is ensured the be of either BufferedImage.TYPE_INT_RGB or BufferedImage.TYPE_INT_ARGB.

Ensuring the image is of one of the possible return types is done before applying an image filter transformation since if the image is of a different (not native) type, the transformation can take very long and consume a lot of resources.

Parameters:

image - the original image

allowTransparent - if true, transparent (alpha layer) pixels is allowed

Returns:

an image that is ensured the be of a system type

applyFilter

public java.awt.image.BufferedImage applyFilter(java.awt.image.BufferedImage image,
                                       java.awt.image.ImageFilter filter)

Applies the given filter to the image.

Parameters:

image - the image to apply the filter to

filter - the filter to apply

Returns:

the image with the filter applied

applyFilterDimensions

public java.awt.Rectangle applyFilterDimensions(int width,
                                       int height)

Calculates the image size for an image after all filters returned by RenderSettings.getImageFilters() have been applied.

Parameters:

width - the image width

height - the image height

Returns:

the image size after all filters have been applied

applyFilters

public java.awt.image.BufferedImage applyFilters(java.awt.image.BufferedImage image)

Applies all filters returned by RenderSettings.getImageFilters() to the given image.

Parameters:

image - the image to apply the filters to

Returns:

the image with the filters applied

crop

public java.awt.image.BufferedImage crop(java.awt.image.BufferedImage image,
                                int width,
                                int height,
                                int cropPosition)

Crops an image according to the width and height specified.

Use the constants POS_CENTER etc. to indicate the crop position.

Parameters:

image - the image to crop

width - the width of the target image

height - the height of the target image

cropPosition - the position to crop the image at

Returns:

the transformed image

crop

public java.awt.image.BufferedImage crop(java.awt.image.BufferedImage image,
                                int x,
                                int y,
                                int width,
                                int height)

Crops a part of the given image from the specified x,y point to the given width,height. Should the target image rectangle be outside of the source image, the source image is enlarged and the transparent color is used for the additional background pixels. If the image does not support transparent pixels, the transparent replacement color (whit by default) will be used.

Parameters:

image - the image to crop

x - the x position where the crop starts

y - the y position where the crop starts

width - the width of the cropped target image

height - the height of the cropped target image

Returns:

a cropped part of the given image from the specified x,y point to the given width,height

See Also:

crop(BufferedImage, int, int, int, int, Color)

crop

public java.awt.image.BufferedImage crop(java.awt.image.BufferedImage image,
                                int x,
                                int y,
                                int width,
                                int height,
                                java.awt.Color backgroundColor)

Crops a part of the given image from the specified x,y point to the given width,height. Should the target image rectangle be outside of the source image, the source image is enlarged and the given background replace color is used for the additional pixels.

Parameters:

image - the image to crop

x - the x position where the crop starts

y - the y position where the crop starts

width - the width of the cropped target image

height - the height of the cropped target image

backgroundColor - the color to use if the background must be enlarged

Returns:

a cropped part of the given image from the specified x,y point to the given width,height

See Also:

crop(BufferedImage, int, int, int, int)

cropToSize

public java.awt.image.BufferedImage cropToSize(java.awt.image.BufferedImage image,
                                      int x,
                                      int y,
                                      int width,
                                      int height,
                                      int targetWidth,
                                      int targetHeight)

Crops a part of the given image from the specified x,y point to the given width,height, and then resizes this cropped image to the dimensions specified in targetWidth,targetHeight. Should the target image rectangle be outside of the source image, the source image is enlarged and the transparent color is used for the additional background pixels. If the image does not support transparent pixels, the transparent replacement color (whit by default) will be used.

The aspect ratio of the target image is not kept.

Parameters:

image - the image to crop

x - the x position where the crop starts

y - the y position where the crop starts

width - the width of the cropped area from the source image

height - the height of the cropped area from the source image

targetWidth - the width of the target image

targetHeight - the width of the target image

Returns:

a cropped part of the given image from the specified x,y point to the given width,height, resized to the dimensions specified in targetWidth,targetHeight

See Also:

cropToSize(BufferedImage, int, int, int, int, int, int, Color)

cropToSize

public java.awt.image.BufferedImage cropToSize(java.awt.image.BufferedImage image,
                                      int x,
                                      int y,
                                      int width,
                                      int height,
                                      int targetWidth,
                                      int targetHeight,
                                      java.awt.Color backgroundColor)

Crops a part of the given image from the specified x,y point to the given width,height, and then resizes this cropped image to the dimensions specified in targetWidth,targetHeight. Should the target image rectangle be outside of the source image, the source image is enlarged and the given background replace color is used for the additional pixels.

The aspect ratio of the target image is not kept.

Parameters:

image - the image to crop

x - the x position where the crop starts

y - the y position where the crop starts

width - the width of the cropped area from the source image

height - the height of the cropped area from the source image

targetWidth - the width of the target image

targetHeight - the width of the target image

backgroundColor - the color to use if the background must be enlarged

Returns:

a cropped part of the given image from the specified x,y point to the given width,height, resized to the dimensions specified in targetWidth,targetHeight

See Also:

cropToSize(BufferedImage, int, int, int, int, int, int)

getBytes

public byte[] getBytes(java.awt.image.BufferedImage image,
              java.lang.String type)
                throws java.io.IOException

Returns the byte contents of the given image.

Parameters:

image - the image to get the byte contents for

type - the type of the image to get the byte contents for

Returns:

the byte contents of the given image

Throws:

java.io.IOException - in case the image could not be converted to bytes

reduceColors

public java.awt.image.BufferedImage reduceColors(java.awt.image.BufferedImage image,
                                        int maxColors,
                                        boolean alphaToBitmask)

Reduces the colors in the given image to the given maximum color number.

Parameters:

image - the image to reduce the colors from

maxColors - the maximum number of allowed colors in the output image (usually 256)

alphaToBitmask - indicates if alpha information should be converted

Returns:

the transformed image

resize

public java.awt.image.BufferedImage resize(java.awt.image.BufferedImage image,
                                  int width,
                                  int height)

Resizes an image according to the width and height specified.

Parameters:

image - the image to resize

width - the width of the target image

height - the height of the target image

Returns:

the transformed image

resize

public java.awt.image.BufferedImage resize(java.awt.image.BufferedImage image,
                                  int width,
                                  int height,
                                  boolean bestfit)

Resizes an image according to the width and height specified, keeping the aspect ratio if required.

If set to true, the bestfit option will keep the image within the dimensions specified without losing the aspect ratio.

Parameters:

image - the image to resize

width - the width of the target image

height - the height of the target image

bestfit - if true, the aspect ratio of the image will be kept

Returns:

the transformed image

resize

public java.awt.image.BufferedImage resize(java.awt.image.BufferedImage image,
                                  int width,
                                  int height,
                                  boolean bestfit,
                                  boolean blowup)

Resizes an image according to the width and height specified, keeping the aspect ratio if required.

If set to true, the bestfit option will keep the image within the dimensions specified without losing the aspect ratio.

If set to false, the blowup option will not enlarge an image that is already smaller then the sepcified target dimensions.

Parameters:

image - the image to resize

width - the width of the target image

height - the height of the target image

bestfit - if true, the aspect ratio of the image will be kept

blowup - if false, smaller images will not be enlarged to fit in the target dimensions

Returns:

the transformed image

resize

public java.awt.image.BufferedImage resize(java.awt.image.BufferedImage image,
                                  int width,
                                  int height,
                                  java.awt.Color backgroundColor,
                                  int position)

Resizes the given image to best fit into the given dimensions (only if it does not already fit in the dimensions), placing the scaled image at the indicated position on a background with the given color.

Parameters:

image - the image to resize

width - the width of the target image

height - the height of the target image

backgroundColor - the background color to use

position - the position to place the scaled image at

Returns:

the transformed image

resize

public java.awt.image.BufferedImage resize(java.awt.image.BufferedImage image,
                                  int width,
                                  int height,
                                  java.awt.Color backgroundColor,
                                  int position,
                                  boolean blowup)

Resizes the given image to best fit into the given dimensions (only if it does not already fit in the dimensions), placing the scaled image at the indicated position on a background with the given color.

Parameters:

image - the image to resize

width - the width of the target image

height - the height of the target image

backgroundColor - the background color to use

position - the position to place the scaled image at

blowup - if false, smaller images will not be enlarged to fit in the target dimensions

Returns:

the transformed image

resize

public java.awt.image.BufferedImage resize(java.awt.image.BufferedImage image,
                                  int width,
                                  int height,
                                  int position)

Resizes an image according to the width and height specified, cropping the image along the sides in case the required height and width can not be reached without changing the apsect ratio of the image.

Use the constants POS_CENTER etc. to indicate the crop position.

Parameters:

image - the image to resize

width - the width of the target image

height - the height of the target image

position - the position to place the cropped image at

Returns:

the transformed image

scale

public java.awt.image.BufferedImage scale(java.awt.image.BufferedImage image,
                                 float scale)

Scales an image according to the given scale factor.

If the scale is 2.0, the result image will be twice as large as the original, if the scale is 0.5, the result image will be half as large as the original.

Parameters:

image - the image to scale

scale - the scale factor

Returns:

the transformed image

scale

public java.awt.image.BufferedImage scale(java.awt.image.BufferedImage image,
                                 float widthScale,
                                 float heightScale)

Scale the image with different ratios along the width and height.

Parameters:

image - the image to scale

widthScale - the scale factor for the width

heightScale - the scale factor for the height

Returns:

the transformed image

scale

public java.awt.image.BufferedImage scale(java.awt.image.BufferedImage image,
                                 float widthScale,
                                 float heightScale,
                                 int targetWidth,
                                 int targetHeight)

Scale the image with different ratios along the width and height to the given target dimensions.

Giving both scale factor and target dimensions is required to avoid rounding errors that lead to the "missing line" issue.

Parameters:

image - the image to scale

widthScale - the scale factor for the width

heightScale - the scale factor for the height

targetWidth - the width of the target image

targetHeight - the height of the target image

Returns:

the transformed image

scale

public java.awt.image.BufferedImage scale(java.awt.image.BufferedImage image,
                                 int targetWidth,
                                 int targetHeight)

Scale the image to the width and height to the given target dimensions.

Parameters:

image - the image to scale

targetWidth - the width of the target image

targetHeight - the height of the target image

Returns:

the transformed image

write

public void write(java.awt.image.BufferedImage image,
         java.io.File destination,
         java.lang.String type)
           throws java.io.IOException

Writes an image to a local file.

Parameters:

image - the image to write

destination - the destination file

type - the type of the image to write

Throws:

java.io.IOException - in case the image could not be written

write

public void write(java.awt.image.BufferedImage image,
         java.io.OutputStream destination,
         java.lang.String type)
           throws java.io.IOException

Writes an image to an output stream.

Parameters:

image - the image to write

destination - the output stream to write the image to

type - the type of the image to write

Throws:

java.io.IOException - in case the image could not be written

write

public void write(java.awt.image.BufferedImage image,
         java.lang.String destination,
         java.lang.String type)
           throws java.io.IOException

Writes an image to a local file.

Parameters:

image - the image to write

destination - the destination file name

type - the type of the image to write

Throws:

java.io.IOException - in case the image could not be written

createImage

protected java.awt.image.BufferedImage createImage(java.awt.image.ColorModel colorModel,
                                       int width,
                                       int height)

Creates a buffered image that has the given dimensions and uses the given color model.

Parameters:

colorModel - the color model to use

width - the width of the image to create

height - the height of the image to create

Returns:

a new image with the given dimensions and uses the given color model

write

protected void write(java.awt.image.BufferedImage im,
         java.lang.Object output,
         java.lang.String formatName)
              throws java.io.IOException

Writes an image to the given output object, using the the given quality.

The quality is used only if the image type supports different qualities. For example, this it is used when writing JPEG images. A quality of 0.1 is very poor, 0.75 is ok, 1.0 is maximum.

Parameters:

im - the image to write

output - the destination to write the image to

formatName - the type of the image to write

Throws:

java.io.IOException - in case the image could not be written