imageutils

Support tools for creating images and image resources.

This library defines an object, ImageUtils, which contains utility methods for working with images. It is mostly used by resource creation scripts. A resource creation script replaces a resource file with a script capable of generating that resource. The script must define a function, createResource() that returns the new resource.

One way to use an image resource creation scripts is to break a large image into smaller ones in such a way that they can be stored more efficiently. This reduces the download footprint of the program. A good example is an image that is mostly opaque with a small transparent area. Transparent images are not stored as efficiently as non-transparent ones, so it may be more efficient to split the image into two or more pieces and store each in a separate file. The pieces are then combined into the final image at runtime by the resource creation script.

Constants

`ImageUtils.STITCH_HORIZONTAL`	indicates that images should be stitched from left to right
`ImageUtils.STITCH_VERTICAL`	indicates that images should be stitched from top to bottom

ImageUtils.create( width, height, [hasTransparency] ) static

Create an image that is width pixels by height pixels. If hasTransparency is true, the image will have an alpha channel (allowing transparency and translucency), otherwise the image is opaque.

`width`	the image width, in pixels
`height`	the image height, in pixels
`hasTransparency`	if `true`, create an alpha channel for the image (default is `false`)

returns a BufferedImage with the requested parameters

ImageUtils.createForResolution( dpi, width, height, [hasTransparency] ) static

Create an image that is width points by height points. The conversion of points into pixels is determined by dpi, the number of dots (pixels) per inch. If hasTransparency is true, the image will have an alpha channel (allowing transparency and translucency), otherwise the image is opaque.

`dpi`	the image resolution, in dots (pixels) per inch
`width`	the image width, in points
`height`	the image height, in points
`hasTransparency`	if `true`, create an alpha channel for the image (default is `false`)

returns a BufferedImage with the requested parameters

ImageUtils.get( relativeURL, [cacheResult], [quietly] ) static

Obtain an image from the Strange Eons resources. If the image cannot be obtained, null is returned. Typically this indicates that the URL is incorrect.

`relativeURL`	a URL string relative to the `resources` folder
`cacheResult`	if `true`, the image may be cached to speed future requests (default is `true`)
`quietly`	if `true`, no error message is displayed if loading fails (default is `false`, i.e., display a message)

returns the image resource as a BufferedImage, or null

ImageUtils.getIcon( relativeURL, [unthemed] ) static

Create an Icon from an image resource, suitable for use with Swing components. If the icon cannot be obtained, null is returned. Typically, this indicates that the URL is incorrect. (Note that is usually safe to set a component's Icon to null, as it is interpreted as setting no icon.)

`relativeURL`	a URL string relative to the `resources` folder
`unthemed`	if `true`, then the current theme will not be allowed to substitute a different image (default is `false`)

returns the image resource as a javax.swing.ImageIcon, or null

ImageUtils.createIcon( image, [size] )

Creates an icon from an existing image. The icon will be resized to fit within size by size pixels.

`image`	the image to use in the icon
`size`	the target size for the icon (default is 16)

returns an icon that displays the image and is the requested size

ImageUtils.copy( image )

Returns a new copy of image. If you are going to draw on an image that you obtained from resources, it is important to work with a copy or you will corrupt the shared version stored in the image cache.

returns a copy of the source image

ImageUtils.stitch( image1, image2, stitchEdge ) static

Returns a new image that combines two source images by "stitching" them together along an edge. If stitchEdge is ImageUtils.STITCH_HORIZONTAL, then the right edge of image1 will be stitched to the left edge of image2. If stitchEdge is ImageUtils.STITCH_VERTICAL, then the bottom edge of image1 will be stitched to the top edge of image2 If either source image has transparency, then the returned image will also; otherwise it is opaque.

`image1`	the first `BufferedImage` to be stitched
`image2`	the second `BufferedImage` to be stitched
`stitchEdge`	a constant indicating which edges to join

returns a BufferedImage that joins the source images at their edges

ImageUtils.resize( image, width, height, [fast] ) static

Create a copy of a BufferedImage that is resampled at a new size, either smaller or larger in either dimension.

`image`	the image to create a resized copy of
`width`	the width of the new image, in pixels
`height`	the height of the new image, in pixels
`fast`	an optional hint; if `true`, lower quality but faster resampling is performed (default is `false`)

returns a resized copy of image

ImageUtils.fit( image, width, height, [fast] ) static

Ensures that image is as large as it can be and still fit within width and height pixels, without changing the aspect ratio. If the image already just fits, it is returned. Otherwise a new, resized image is returned.

`image`	the image to fit within the space
`width`	the maximum width of the resized image
`height`	the maximum height of the resized image
`fast`	if `true` a faster but lower quality algorithm is used (default is `false`)

ImageUtils.crop( image, x, y, width, height ) static

Create an image by cropping a source image. The resulting image will consist of the subimage of the source image that starts at pixel (x,y) in the source image and is width by height pixels in size. Either width or height (or both) may be less than 1, in which case the width will be set to the number of pixels from the upper-left corner of the crop to the edge.

`image`	the source image, which is not changed
`x`	the x-coordinate of the upper-left corner of the region to retain in the destination
`y`	the y-coordinate of the upper-left corner of the region to retain in the destination
`width`	the width of the region to retain in the destination
`height`	the height of the region to retain in the destination

ImageUtils.pad( image, top, [left, bottom, right] ) static

Returns a padded copy of the image that adds magins of the given sizes to the outside of the image. The margins may be negative, in which case rows or columns will be removed from the relevant edge. If only the top margin size is given, then the same margin will be used on all four sides.

`image`	a `BufferedImage` to pad
`top`	the number of pixels to add to the top edge
`left`	the number of pixels to add to the left edge
`bottom`	the number of pixels to add to the bottom edge
`right`	the number of pixels to add to the right edge

returns a padded copy of image

ImageUtils.tint( image, h, s, b ) static

Returns a tinted copy of an image. The value of h is a relative number of degrees. The hue of each pixel in the source image will be shifted by h degrees around the HSB colour wheel; a value of 0 leaves the hue unchanged. The value of s is a saturation factor; each pixel's saturation will be multiplied by this value. A value of 0 will convert the image to greyscale. A value of 1 will leave the saturation unchanged. The value of b is a brightness factor. Each pixel's brightness will be multiplied by this value. A value of 0 will set each pixel's brightness to 0, resulting in a black image. A value of 1 will leave the brightness unchanged.

`image`	the image to tint
`h`	the hue shift to apply
`s`	the saturation factor to apply
`b`	the brightness factor to apply

returns a tinted copy of image

ImageUtils.mirror( image, [horiz], [vert] ) static

Returns a new BufferedImage that is a mirror image of image.

`image`	a `BufferedImage` to mirror
`horiz`	if `true`, flip horizontally (default is `true`)
`vert`	if `true`, flip vertically (default is `false`)

returns a mirrored copy of image

ImageUtils.invert( image ) static

Returns a copy of the image with all of the pixels inverted.

image the image to invert

returns the inverse image

ImageUtils.desaturate( image ) static

Returns a copy of the image converted to greyscale.

image the image to desaturate

returns the desaturated image

ImageUtils.read( file ) static

Read and return an image from a file.

file the name of the file to read

returns the image, or throws an error if reading fails

ImageUtils.write( image, file, [format], [quality], [progressive], [dpi] ) static

Write an image to a file. The value of format is a string that describes the desired image format. The values "png", "jpg", or "jp2" are all acceptable and use one of the three standard Strange Eons image formats (PNG, JPEG, and JPEG 2000). In addition, the value "gif" will create a file in GIF89a format, while "bmp" will create a Windows BMP file. If format is not defined, it defaults to "png".

`image`	the image to write
`file`	the file to write to; either a file name string or a `File` object
`format`	a string describing the format to write the image in (default is `"png"`)
`quality`	a value between 0 and 1 (inclusive) to control compression quality (higher is better quality, -1 for default)
`progressive`	if `true` requests an image that can be displayed progressively as it downloads (default is `false`)
`ppi`	if supported by the image encoder, the image's metadata will indicate that this is the resolution of the image (in pixels per inch)

File Format Constants

Constants that can be passed as format values to ImageUtils.write.

`ImageUtils.FORMAT_PNG`	the PNG (png) image format
`ImageUtils.FORMAT_JPEG`	the JPEG (jpg) image format
`ImageUtils.FORMAT_JPEG2000`	the JPEG2000 (jp2) image format
`ImageUtils.FORMAT_BMP`	the BMP (bmp) image format
`ImageUtils.FORMAT_GIF`	the GIF89a (gif) image format

ImageUtils.save( image, [defaultFile], [parent] ) static

Prompts the user to choose a file, then saves image to the selected file. If no defaultFile is specified, then a default location is selected based on the last saved file, or if no image file has been saved previously, a platform-specific default location is used. The value of defaultFile may either be a java.io.File object, or else it can be another object whose string representation is a valid path on this platform.

`image`	the image to be written
`defaultFile`	an optional default location to save to
`parent`	an optional parent for the file chooser; defaults to the main application window

returns the java.io.File that was saved, or null if the user cancelled the save operation

ImageUtils.view( image, [title], [modal], [parent] ) static

Display an image in an image viewer window.

`image`	a `BufferedImage` to display
`title`	an optional title for the view window
`modal`	if `true`, the viewer should be modal (blocks the application until closed)
`parent`	an optional parent for the file chooser; defaults to the main application window

Contents