Package gamedata

Class SymbolVariantUtilities

java.lang.Object

gamedata.SymbolVariantUtilities

public final class SymbolVariantUtilities
extends java.lang.Object

This class provides some static utility methods that can aid plug-in developers when implementing ExpansionSymbolTemplate.generateVariant(java.awt.image.BufferedImage, int). Much of the functionality in this class is also available from other parts of the Strange Eons API, but this class gathers it in one place and provides a consistent interface, making it easier to think it terms of the higher-level steps needed to achieve the desired effect.

Since:

3.0

Author:

Chris Jennings

See Also:

ExpansionSymbolTemplate.canGenerateVariantsAutomatically()

Method Summary

Modifier and Type	Method	Description
static java.awt.image.BufferedImage	copy(java.awt.image.BufferedImage source)	Returns a copy of the source image.
static javax.swing.Icon	createDefaultVariantIcon(int rgb)	Creates an icon that can be returned from ExpansionSymbolTemplate.getVariantIcon(int).
static javax.swing.Icon	createDefaultVariantIcon(java.awt.Paint characteristicPaint)	Creates an icon that can be returned from ExpansionSymbolTemplate.getVariantIcon(int).
static java.awt.image.BufferedImage	desaturate(java.awt.image.BufferedImage source)	Returns a greyscale version of an image.
static java.awt.image.BufferedImage	extractSymbol(java.awt.image.BufferedImage source)	Creates a base symbol to be used as a starting point from an arbitrary image supplied by the user.
static boolean	isGreyscale(java.awt.image.BufferedImage source)	Returns true if and only if, for every pixel in the source image, that pixel has identical red, green and blue levels.
static boolean	isMonochrome(java.awt.image.BufferedImage source)	Returns true if and only if every pixel in the source image has the same RGB value (the alpha channel may vary).
static java.awt.image.BufferedImage	outline(java.awt.image.BufferedImage source, int outlineColor, int outlineWidth)	Returns a stroked version of the source image.
static java.awt.image.BufferedImage	outline(java.awt.image.BufferedImage source, java.awt.Color outlineColor, int outlineWidth)	Returns a stroked version of the source image.
static java.awt.image.BufferedImage	pad(java.awt.image.BufferedImage source, int paddingSize)	Adds transparent padding to each edge of the image equal to paddingSize.
static java.awt.image.BufferedImage	pad(java.awt.image.BufferedImage source, int top, int left, int bottom, int right)	Adds transparent padding to each edge of the image equal.
static java.awt.image.BufferedImage	recolor(java.awt.image.BufferedImage source, int color)	Recolours an image with a single colour.
static java.awt.image.BufferedImage	recolor(java.awt.image.BufferedImage source, int color1, int color2)	Recolours an image.
static java.awt.image.BufferedImage	recolor(java.awt.image.BufferedImage source, java.awt.Color color)	Recolours an image with a single colour.
static java.awt.image.BufferedImage	recolor(java.awt.image.BufferedImage source, java.awt.Color color1, java.awt.Color color2)	Recolours an image.
static java.awt.image.BufferedImage	shadow(java.awt.image.BufferedImage source, double angle, int distance, int shadowColor, int size, int strength)	Returns a version of the image with a drop shadow.
static java.awt.image.BufferedImage	shadow(java.awt.image.BufferedImage source, double angle, int distance, java.awt.Color shadowColor, int size, int strength)	Returns a version of the image with a drop shadow.
static java.awt.image.BufferedImage	standardizeSize(java.awt.image.BufferedImage source, int size)	Converts the image to a standard size.
static java.awt.image.BufferedImage	trim(java.awt.image.BufferedImage source)	Trims off any completely transparent edges, ensuring that the border of the image contains at least one pixel with a non-zero alpha.

Methods inherited from class java.lang.Object

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

Method Detail

extractSymbol

public static java.awt.image.BufferedImage extractSymbol(java.awt.image.BufferedImage source)

Creates a base symbol to be used as a starting point from an arbitrary image supplied by the user. The resulting image is guaranteed to:

1. support transparency (have an alpha channel)
2. have a greyscale colour palette

This method uses a set of heuristics to infer how the user meant the image to be used as a symbol while still fulfilling the restrictions above. It operates as follows:

1. Desaturate the image (convert it to greyscale).
2. If the image does not have an alpha channel, then it is assumed that the image consists of a dark symbol drawn on a light background. An alpha channel will be created by setting each pixel's alpha value according to the pixel's brightness (light pixels are more transparent). The brightness of each pixel will the be set to 0. (The result is this a black symbol with transparent areas.)
3. If the image already has an alpha channel, then that alpha channel is retained. If the image is greyscale, then the red, green, and blue channels are also retained. Otherwise, the RGB portion of each pixel is converted to black (use recolor(java.awt.image.BufferedImage, int) if you require a different base colour).
4. The alpha channel of the resulting image has some noise removed by driving alpha values that are very close to 0 down to 0. (Noise in the alpha channel will tend to be amplified by other effects that may be applied.)
5. The final, noise-cleaned image is then returned.

Parameters:

source - the source image to convert into an image suitable for use as a symbol

Returns:

the converted image

trim

public static java.awt.image.BufferedImage trim(java.awt.image.BufferedImage source)

Trims off any completely transparent edges, ensuring that the border of the image contains at least one pixel with a non-zero alpha. It is a good idea to call this before scaling the image to its standardizeSize(java.awt.image.BufferedImage, int). Otherwise images with transparent edges will appear to be smaller than the standard size even though they are not.

Parameters:

source - the image to trim

Returns:

the image, with transparent sides cropped off

See Also:

ImageUtilities.trim(java.awt.image.BufferedImage)

desaturate

public static java.awt.image.BufferedImage desaturate(java.awt.image.BufferedImage source)

Returns a greyscale version of an image.

Parameters:

source - the image to desaturate

Returns:

a greyscale version of the source image

See Also:

ImageUtilities.desaturate(java.awt.image.BufferedImage)

standardizeSize

public static java.awt.image.BufferedImage standardizeSize(java.awt.image.BufferedImage source,
                                                           int size)

Converts the image to a standard size. It is best to choose a standard size for your symbols and covert the base image to that size before applying other effects. This is necessary because the image will be scaled to fit the expansion symbol region of the sheet it is painted on, and you want your effects to scale consistently. (For example, suppose that you did not standardize the size and you apply a 4-pixel wide outline to the base image. If one expansion symbol image is twice as wide as another, then when it is scaled to fit into the expansion symbol box it will be scaled to half the size, so it will look like you applied a 2-pixel wide outline.)

This method will produce a square image that is size by size pixels. The largest dimension will be scaled up or down as needed, and the opposite dimension will be padded with completely transparent pixels, if necessary, to fill it out.

The following is a good rule of thumb for choosing a standard size:

1. Choose the largest expansion symbol region on all of your components. Take this as the starting size, s. If the expansion symbol region isn't square, take the larger dimension (though a better idea would be to make it square, if possible).
2. To ensure that symbols look good when printed (assuming a large enough source image was provided), multiply s by 300/t, where t is the resolution of the template image for your components. (If you have not explicitly set a resolution, it will be 150, meaning that you should multiply by 2.) This is your standard size.

Parameters:

source - the base image to convert to standard size

size - the standard size

Returns:

a square image at the standard size, containing the same design as the source image

See Also:

ImageUtilities.resample(java.awt.image.BufferedImage, float), ImageUtilities.center(java.awt.image.BufferedImage, int, int)

pad

public static java.awt.image.BufferedImage pad(java.awt.image.BufferedImage source,
                                               int paddingSize)

Adds transparent padding to each edge of the image equal to paddingSize. This is useful when you are about to apply an effect that grows from the edge of the original image.

Parameters:

source - the original image

paddingSize - the number of rows or columns to add to each side of the image

Returns:

an image that is larger in both dimensions by twice the padding size

pad

public static java.awt.image.BufferedImage pad(java.awt.image.BufferedImage source,
                                               int top,
                                               int left,
                                               int bottom,
                                               int right)

Adds transparent padding to each edge of the image equal. This is useful when you are about to apply an effect that grows from the edge of the original image.

Parameters:

source - the original image

top - the number of transparent rows to add to the top edge

left - the number of transparent columns to add to the left edge

bottom - the number of transparent rows to add to the bottom edge

right - the number of transparent columns to add to the right edge

Returns:

an image that is larger in both dimensions by twice the padding size

outline

public static java.awt.image.BufferedImage outline(java.awt.image.BufferedImage source,
                                                   int outlineColor,
                                                   int outlineWidth)

Returns a stroked version of the source image. Note that the outline colour includes an alpha value; if you pass a colour with an alpha value of zero then the outline will be invisible.

This method automatically pads the source image to add enough space to stroke the pixels at th edge of the image.

Parameters:

source - the image to outline

outlineColor - the colour of the outline (including an alpha value)

outlineWidth - the width of the outline, in pixels

Returns:

an outlined version of the source image

See Also:

StrokeFilter

outline

public static java.awt.image.BufferedImage outline(java.awt.image.BufferedImage source,
                                                   java.awt.Color outlineColor,
                                                   int outlineWidth)

Returns a stroked version of the source image. This is identical to outline(java.awt.image.BufferedImage, int, int) except that it takes a Color instance for the outline colour.

Parameters:

source - the image to outline

outlineColor - the colour of the outline

outlineWidth - the width of the outline, in pixels

Returns:

an outlined version of the source image

See Also:

StrokeFilter

shadow

public static java.awt.image.BufferedImage shadow(java.awt.image.BufferedImage source,
                                                  double angle,
                                                  int distance,
                                                  int shadowColor,
                                                  int size,
                                                  int strength)

Returns a version of the image with a drop shadow. Note that the shadow colour includes an alpha value; if you pass a colour value with an alpha of zero the shadow will be invisible.

This method automatically pads the source image to make enough space for the shadow.

Parameters:

source - the image to shade

angle - the anti-clockwise angle from the x-axis, in degrees

distance - the distance from the source image to the shadow; use zero for a glow effect

shadowColor - the shadow colour (including an alpha value)

size - the shadow size; the higher this value, the fuzzier the shadow edge will be

strength - the strength of the shadow effect (must be positive; 1 is standard)

Returns:

an image depicting the source image floating over a drop shadow with the given parameters

See Also:

ColorOverlayFilter, BlurFilter, GlowFilter

shadow

public static java.awt.image.BufferedImage shadow(java.awt.image.BufferedImage source,
                                                  double angle,
                                                  int distance,
                                                  java.awt.Color shadowColor,
                                                  int size,
                                                  int strength)

Returns a version of the image with a drop shadow. This is identical to shadow(java.awt.image.BufferedImage, double, int, int, int, int) except that it takes a Color instance for the shadow colour.

Parameters:

source - the image to shade

angle - the anti-clockwise angle from the x-axis, in degrees

distance - the distance from the source image to the shadow; use zero for a glow effect

shadowColor - the shadow colour

size - the shadow size; the higher this value, the fuzzier the shadow edge will be

strength - the strength of the shadow effect (must be positive; 1 is standard)

Returns:

an image depicting the source image floating over a drop shadow with the given parameters

recolor

public static java.awt.image.BufferedImage recolor(java.awt.image.BufferedImage source,
                                                   int color)

Recolours an image with a single colour. Every pixel will be set to this colour; the alpha channel will not be affected, so the shape will remain the same.

Parameters:

source - the source image

color - the colour value (alpha is ignored)

Returns:

an image where every pixel takes on the given color but retains its original transparency

See Also:

ColorOverlayFilter

recolor

public static java.awt.image.BufferedImage recolor(java.awt.image.BufferedImage source,
                                                   java.awt.Color color)

Recolours an image with a single colour. This is identical to recolor(java.awt.image.BufferedImage, int) except that it takes a Color instance instead of an integer RGB value.

Parameters:

source - the source image

color - the colour value (alpha is ignored)

Returns:

an image where every pixel takes on the given color but retains its original transparency

See Also:

ColorOverlayFilter

isMonochrome

public static boolean isMonochrome(java.awt.image.BufferedImage source)

Returns true if and only if every pixel in the source image has the same RGB value (the alpha channel may vary). This can determine, for example, if extractSymbol(java.awt.image.BufferedImage) has converted the image to pure black or greyscale.

Parameters:

source - the image to check

Returns:

true if every pixel in the source is the same colour

isGreyscale

public static boolean isGreyscale(java.awt.image.BufferedImage source)

Returns true if and only if, for every pixel in the source image, that pixel has identical red, green and blue levels.

Parameters:

source - the image to check

Returns:

true if every pixel in the source is grey

recolor

public static java.awt.image.BufferedImage recolor(java.awt.image.BufferedImage source,
                                                   int color1,
                                                   int color2)

Recolours an image. The source image is assumed to be greyscale. The darkest pixels will be coloured with color1, the lightest pixels will be coloured with color2, and pixels whose brightness is in between will be interpolate between the two extremes. The interpolation is non-linear, leaving a margin around the brightest and darkest pixel values to allow for some noise in the image.

Note: This effect is applied in-place; the returned image is the same as the image that is passed in.

Parameters:

source - the source image

color1 - the dark pixel colour value (alpha is ignored)

color2 - the light pixel colour value (alpha is ignored)

Returns:

an image where every pixel is recoloured based on its brightness by interpolating between the two colours; transparency is unaffected.

See Also:

Interpolation.CubicSpline

recolor

public static java.awt.image.BufferedImage recolor(java.awt.image.BufferedImage source,
                                                   java.awt.Color color1,
                                                   java.awt.Color color2)

Recolours an image. This is identical to recolor(java.awt.image.BufferedImage, int, int) except that it takes Color instances instead of integer RGB values.

Note: This effect is applied in-place; the returned image is the same as the image that is passed in.

Parameters:

source - the source image

color1 - the dark pixel colour value (alpha is ignored)

color2 - the light pixel colour value (alpha is ignored)

Returns:

an image where every pixel is recoloured based on its brightness by interpolating between the two colours; transparency is unaffected.

copy

public static java.awt.image.BufferedImage copy(java.awt.image.BufferedImage source)

Returns a copy of the source image.

Parameters:

source - the image to copy

Returns:

a copy of the image

See Also:

ImageUtilities.copy(java.awt.image.BufferedImage)

createDefaultVariantIcon

public static javax.swing.Icon createDefaultVariantIcon(java.awt.Paint characteristicPaint)

Creates an icon that can be returned from ExpansionSymbolTemplate.getVariantIcon(int). The icon uses a standard design along with a characteristic Paint or Color to represent the style of the variant.

Parameters:

characteristicPaint - a key design element of the variant

Returns:

an icon that can be used to represent the variant visually

createDefaultVariantIcon

public static javax.swing.Icon createDefaultVariantIcon(int rgb)

Creates an icon that can be returned from ExpansionSymbolTemplate.getVariantIcon(int). This is a convenience method that creates an icon based on the colour specified by the given RGB value.

Parameters:

rgb - the 24-bit RGB colour value to create the icon for

Returns:

an icon that can be used to represent the variant visually

See Also:

createDefaultVariantIcon(java.awt.Paint)