artofillusion.util
Class IconGenerator

java.lang.Object
  extended by artofillusion.util.IconGenerator

public class IconGenerator
extends java.lang.Object

Apply editing functions to icon image(s). IconGenerator supports a number of basic image operations such as overlay, blend, add, multiply, etc, and can apply these to the pixels of one or more images. IconGenerator implements a basic macro processor, and the ability to execute a macro in source (string) form, or to compile source and to execute the compiled version. IconGenerator supports a default syntax for macros, but the symbols mapped to each operation can be overridden by the caller.
The editing macro consists of one of more instructions, each separated by a delimiter. Each instruction can perform a single operation which can be modified in various ways. Each operation and each of the modifiers are specified by an operator each of which is specified by some token in the macro "language". All other words are either the pathname of an image or an object in the execution namespace. The operators and the tokens that specify them in the default language binding are:


Examples (using default language):
  "BackgroundIcon; {icon}"
  an image file called BackgroundIcon, overlaid with an image resolved from the namespace 
  with the name "{icon}".
    
  "SelectedBackgroundIcon; {icon} + 0x200000 @(x+1,y+1) [-1,-1]"
  an image file called SelectedBackgroundIcon overlaid with an image resolved from the namespace with the name "{icon}"
  which has had 0x200000 added to each pixel (red increased) and has been offset by x+1, y+1
  and has been reduced in size by 1 pixel on x and y axes.
  
  "0x121212 [32,32]; {icon}; @(z+3)"
  the colour 0x121212 sized to a 32x32 image overlaid with the {icon} image
  with the result of that offset on the z-axis by +3 (this results in a 3D "popped out" effect)
   
  "0x080808 [32,32]; {icon} * #(r=0.6,g=0.6,b=0.6) @(x+1,y+1); @(z-3)"
  the colour 0x080808 sized to a 32x32 image, overlaid with the {icon} image
  which has been multiplied by 0.6 on red, green and blue (made darker)
  and offset x+1,y+1 (down 1, right 1);
  the result of that is then positioned -3 on the Z-axis (which results in a 3D "pressed in" effect).

  "{widget}.getBackground() [32,32]; {icon} * #(r=1.0,g=0.5,b=0.5)"
  The colour returned by calling getBackground() on the object in the
  namespace called "{widget}"; overlaid with the {icon} image which has been
  multiplied by 1.0 on red, and 0.5 on green and blue (made redder).

  "BackgroundIcon; {icon} ~(0.5)"
  The image named BackgroundIcom overlaid with the {icon} image in the
  namespace which has had antialiasing applied using alpha=50% for dark AA
  pixels, and light AA pixels having a alpha calculated from the dark pixels.
  
  "BackgroundIcon; {icon} ~(0.5, 0.66)"
  The image named BackgroundIcom overlaid with the {icon} image in the
  namespace which has had antialiasing applied using alpha=50% for the
  darkest AA pixels, with successively lighter pixels being 66% as dark.
  
  "BackgroundIcon; {icon} ~[3,3]"
  The image named BackgroundIcon overlaid with the {icon} image in the
  namespace which has had it edges feathered to transparent over an area
  3 pixels wide on each side (x-axis) and 3 pixels wide on top and bottom
  (y-axis).
  
  "BackgroundIcon; {icon}; 0xa0804040 ~[-6,-6]"
  The image named BackgroundIcom overlaid with the {icon} image in the
  namespace which has then been overlaid with a region of the specified
  colour (translucent red) which has had its centre feathered to transparent
  from the 6th pixel from the edge into the centre.
  
  "BackgroundIcon; {icon}; 0xa0804040 [-4, -4, ~3]"
  The image named BackgroundIcom overlaid with the {icon} image in the
  namespace, overlaid with a a region of the specified colour
  (translucent red) which is 4 pixels smaller than the current image in both
  X and Y axes, and which has had the outer 3 pixels feathered to trasnparent.
  


Field Summary
static byte FEATHER_IN_DIR
           
static byte FEATHER_OUT_DIR
           
 
Constructor Summary
IconGenerator(java.lang.String macro)
          create a new IconGenerator for the specified macro using the default delims.
IconGenerator(java.lang.String macro, java.lang.String[] delims)
          create a new IconGenerator for the specified macro and delims.
 
Method Summary
static void add(java.awt.image.BufferedImage image, int red, int green, int blue)
          add the color components to each pixel in the image.
static void add(java.awt.image.BufferedImage image, int red, int green, int blue, java.awt.Rectangle clip)
          add the colour components to each pixel in a rectangle within the image.
static void antialias(java.awt.image.BufferedImage image, float dark)
          antialias the diagonal lines in image
static void antialias(java.awt.image.BufferedImage image, float alpha, float attenuate, java.awt.Rectangle clip)
          antialias the diagonal lines a rectangular area of image.
static java.awt.Image apply(java.lang.String macro, java.util.Map<java.lang.String,java.lang.Object> namespace, java.lang.ClassLoader loader)
          apply (compile and execute) the specified macro.
static java.awt.Image apply(java.lang.String macro, java.lang.String[] delims, java.util.Map<java.lang.String,java.lang.Object> namespace, java.lang.ClassLoader loader)
          apply (compile and execute) the specified macro
static java.awt.Image apply(java.lang.String macro, java.lang.String[] delims, java.util.Map<java.lang.String,java.lang.Object> namespace, java.lang.ClassLoader loader, int width, int height)
          apply (compile and execute) the specified macro.
static void assign(java.awt.image.BufferedImage image, int alpha, int red, int green, int blue)
          assign the colour components to each pixel in the image.
static void assign(java.awt.image.BufferedImage image, int alpha, int red, int green, int blue, java.awt.Rectangle clip)
          assign the colour components to each pixel in a rectangle within the image.
static void bevel3D(java.awt.image.BufferedImage image, int depth)
          draw a 3d bevelled edge on a rectangular image
static void bevel3D(java.awt.image.BufferedImage image, int depth, java.awt.Rectangle clip)
          draw a 3d bevelled edge on or in the image, with the edges being those of the specified clip rectangle.
 void compile(java.lang.String macro)
          compile the specified macro using the delims defined for this IconGenerator.
static java.awt.image.BufferedImage copy(java.awt.Image orig)
          copy an image.
static java.awt.image.BufferedImage copy(java.awt.Image orig, int width, int height, float scale)
          copy the original image to a new image of the specified size (may be larger or smaller).
 java.awt.Image execute(java.util.Map<java.lang.String,java.lang.Object> namespace, java.lang.ClassLoader loader)
          execute a compiled IconGenerator.
static void feather(java.awt.image.BufferedImage image, int xsize, int ysize, byte dir)
          feather (fade to transparent) the image.
static void feather(java.awt.image.BufferedImage image, int xsize, int ysize, byte dir, java.awt.Rectangle clip)
          The XSIZE and YSIZE parameters determine how far from the edge of the image to start feathering, and the DIRection specifies whether to feather OUT (FEATHER_OUT_DIR) towards the edges, or IN (FEATHER_IN_DIR) towards the centre.
static void multiply(java.awt.image.BufferedImage image, float alpha, float red, float green, float blue)
          multiply the components of each pixel in the image
static void multiply(java.awt.image.BufferedImage image, float alpha, float red, float green, float blue, java.awt.Rectangle clip)
          multiply the components of each pixel in a rectangle within the image.
static void overlay(java.awt.image.BufferedImage image, java.awt.Image overlay)
           
static void overlay(java.awt.image.BufferedImage image, java.awt.Image overlay, java.awt.Rectangle clip)
          overlay one image over another.
static void overlay(java.awt.image.BufferedImage image, int alpha, int red, int green, int blue)
          overlay the specified image over a background of the specified colour.
static void overlay(java.awt.image.BufferedImage image, int alpha, int red, int green, int blue, java.awt.Rectangle clip)
          overlay the specified image over a rectangle of the specified colour.
 void setSize(int width, int height)
          set the default size for this IconGenerator.
static void subtract(java.awt.image.BufferedImage image, int red, int green, int blue)
          subtract the colour components from each pixel in image.
static void subtract(java.awt.image.BufferedImage image, int red, int green, int blue, java.awt.Rectangle clip)
          subtract the colour components from each pixel in a rectangle within the image.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FEATHER_OUT_DIR

public static final byte FEATHER_OUT_DIR
See Also:
Constant Field Values

FEATHER_IN_DIR

public static final byte FEATHER_IN_DIR
See Also:
Constant Field Values
Constructor Detail

IconGenerator

public IconGenerator(java.lang.String macro)
              throws java.lang.Exception
create a new IconGenerator for the specified macro using the default delims.

Parameters:
macro -
Throws:
java.lang.Exception

IconGenerator

public IconGenerator(java.lang.String macro,
                     java.lang.String[] delims)
              throws java.lang.Exception
create a new IconGenerator for the specified macro and delims.

Parameters:
macro -
delims -
Throws:
java.lang.Exception
Method Detail

compile

public void compile(java.lang.String macro)
             throws java.lang.Exception
compile the specified macro using the delims defined for this IconGenerator.

Parameters:
macro -
Throws:
java.lang.Exception

setSize

public void setSize(int width,
                    int height)
set the default size for this IconGenerator.

Parameters:
width -
height -

execute

public java.awt.Image execute(java.util.Map<java.lang.String,java.lang.Object> namespace,
                              java.lang.ClassLoader loader)
                       throws java.lang.Exception
execute a compiled IconGenerator.

Parameters:
namespace -
loader -
Returns:
Throws:
java.lang.Exception - if this IconGenerator is not compiled, or the compiled instructions throw and exception.

apply

public static java.awt.Image apply(java.lang.String macro,
                                   java.lang.String[] delims,
                                   java.util.Map<java.lang.String,java.lang.Object> namespace,
                                   java.lang.ClassLoader loader,
                                   int width,
                                   int height)
                            throws java.lang.Exception
apply (compile and execute) the specified macro.

Parameters:
macro - the macro to apply
delims - an array of 3 string, defining the operator and delimiter chars to use
namespace - a Map containing the named objects that can be resolved
loader - the ClassLoader to use for loading external image files.
width - the (initial) width of the icon
height - the (initial) height of the icon
Returns:
the resulting Image
Throws:
java.lang.Exception

apply

public static java.awt.Image apply(java.lang.String macro,
                                   java.lang.String[] delims,
                                   java.util.Map<java.lang.String,java.lang.Object> namespace,
                                   java.lang.ClassLoader loader)
                            throws java.lang.Exception
apply (compile and execute) the specified macro

Throws:
java.lang.Exception
See Also:
apply(String, String[], Map, ClassLoader, int, int)

apply

public static java.awt.Image apply(java.lang.String macro,
                                   java.util.Map<java.lang.String,java.lang.Object> namespace,
                                   java.lang.ClassLoader loader)
                            throws java.lang.Exception
apply (compile and execute) the specified macro.

Throws:
java.lang.Exception
See Also:
apply(String, String[], Map, ClassLoader, int, int)

copy

public static java.awt.image.BufferedImage copy(java.awt.Image orig)
copy an image. The result will be the same as the original, in both content and size.

See Also:
copy(Image, int, int, float)

copy

public static java.awt.image.BufferedImage copy(java.awt.Image orig,
                                                int width,
                                                int height,
                                                float scale)
copy the original image to a new image of the specified size (may be larger or smaller). The content of the orig image is centered within the new image.

Parameters:
orig - the image to copy from
width - the width of the new image
height - the height of the new image.
scale - the way to scale original when copying. scale == 0 means no scaling; scale > 0 means scale original to new dims * scale scale < 0 means scale original abs(scale) piselx smaller than new sims
Returns:
a newly allocated image of the specified ize containing the content of orig centered within it.

bevel3D

public static void bevel3D(java.awt.image.BufferedImage image,
                           int depth)
draw a 3d bevelled edge on a rectangular image

Parameters:
image - the image to modify
depth - the "size" and "direction" of the bevel, which results in the specified apparent "depth" or "height".
See Also:
bevel3D(BufferedImage, int, Rectangle)

bevel3D

public static void bevel3D(java.awt.image.BufferedImage image,
                           int depth,
                           java.awt.Rectangle clip)
draw a 3d bevelled edge on or in the image, with the edges being those of the specified clip rectangle.

Parameters:
image - the image to modify
depth - the size and "direction" of the bevelled edge. a positive value creates a "popped-out" effect by making the top and left edges lighter and the bottom and right edges darker. A negative value creates a "pressed-in" effect by doing the opposite. The absolute value determines the apparent depth or height of the 3d effect by determining the width in pixels of the bevelled edge. So 1 creates an edge 1 pixel wide, and 3 creates an edge 3 pixels wide.

add

public static void add(java.awt.image.BufferedImage image,
                       int red,
                       int green,
                       int blue)
add the color components to each pixel in the image.

See Also:
add(BufferedImage, int, int, int, Rectangle)

add

public static void add(java.awt.image.BufferedImage image,
                       int red,
                       int green,
                       int blue,
                       java.awt.Rectangle clip)
add the colour components to each pixel in a rectangle within the image.

Parameters:
image - the image to modify
red - the red component to add. 0 <= red <= 255
green - the green component to add. 0 <= green <= 255
blue - the blue component to add. 0 <= blue <= 255
clip - the area within which the modification is applied.

subtract

public static void subtract(java.awt.image.BufferedImage image,
                            int red,
                            int green,
                            int blue)
subtract the colour components from each pixel in image.

See Also:
subtract(BufferedImage, int, int, int, Rectangle)

subtract

public static void subtract(java.awt.image.BufferedImage image,
                            int red,
                            int green,
                            int blue,
                            java.awt.Rectangle clip)
subtract the colour components from each pixel in a rectangle within the image.

Parameters:
image - the image to modify
red - the red component to subtract. 0 <= red <= 255
green - the green component to subtract. 0 <= green <= 255
blue - the blue component to subtract. 0 <= blue <= 255
clip - the area within which the modification is applied.

multiply

public static void multiply(java.awt.image.BufferedImage image,
                            float alpha,
                            float red,
                            float green,
                            float blue)
multiply the components of each pixel in the image

See Also:
multiply(BufferedImage, float, float, float, float, Rectangle)

multiply

public static void multiply(java.awt.image.BufferedImage image,
                            float alpha,
                            float red,
                            float green,
                            float blue,
                            java.awt.Rectangle clip)
multiply the components of each pixel in a rectangle within the image.

Parameters:
image - the image to modify
alpha - the alpha component to multiply by. 0.0f <= alpha <= 1.0f
red - the red component to multiply by. 0.0f <= red <= 1.0f
green - the green component to multiply by. 0.0f <= green <= 1.0f
blue - the blue component to multiply by. 0.0f <= blue <= 1.0f
clip - the area within which the modification is applied.

assign

public static void assign(java.awt.image.BufferedImage image,
                          int alpha,
                          int red,
                          int green,
                          int blue)
assign the colour components to each pixel in the image.

See Also:
assign(BufferedImage, int, int, int, int, Rectangle)

assign

public static void assign(java.awt.image.BufferedImage image,
                          int alpha,
                          int red,
                          int green,
                          int blue,
                          java.awt.Rectangle clip)
assign the colour components to each pixel in a rectangle within the image. If any component value is negative, then that component is not modified.

Parameters:
image - the image to modify
alpha - the alpha component to assign. 0 <= alpha <= 255
red - the red component to assign. 0 <= red <= 255
green - the green component to assign. 0 <= green <= 255
blue - the blue component to assign. 0 <= blue <= 255
clip - the area within which the modification is applied.

overlay

public static void overlay(java.awt.image.BufferedImage image,
                           int alpha,
                           int red,
                           int green,
                           int blue)
overlay the specified image over a background of the specified colour.

See Also:
overlay(BufferedImage, int, int, int, int, Rectangle)

overlay

public static void overlay(java.awt.image.BufferedImage image,
                           int alpha,
                           int red,
                           int green,
                           int blue,
                           java.awt.Rectangle clip)
overlay the specified image over a rectangle of the specified colour.

Parameters:
image - the image to modify
alpha - the alpha component of the colour. 0 <= alpha <= 255
red - the red component of the colour. 0 <= red <= 255
green - the green component of the colour. 0 <= green <= 255
blue - the blue component of the colour. 0 <= blue <= 255
clip - the area within which the modification is applied.

overlay

public static void overlay(java.awt.image.BufferedImage image,
                           java.awt.Image overlay)

overlay

public static void overlay(java.awt.image.BufferedImage image,
                           java.awt.Image overlay,
                           java.awt.Rectangle clip)
overlay one image over another.

Parameters:
image - the image to modify
overlay - the image to overlay onto image
clip - the region of image to modify. If this is null, then overlay is centered on image.

antialias

public static void antialias(java.awt.image.BufferedImage image,
                             float dark)
antialias the diagonal lines in image

See Also:
antialias(BufferedImage, float, float, Rectangle)

antialias

public static void antialias(java.awt.image.BufferedImage image,
                             float alpha,
                             float attenuate,
                             java.awt.Rectangle clip)
antialias the diagonal lines a rectangular area of image.

Parameters:
image - the image to antialias
alpha - the alpha value to use for the antialias strongest AA (antialias) pixels. 0.0 < alpha < 1.0 The Strongest AA pixels are those with the most adjoining opaque pixels (currently 4 is the maximum).
attenuate - the scaling factor to apply for increasingly weaker AA pixels. 0.0 < attenuate. Lighter AA pixels are those that have fewer adjoining opaque pixels (currently 3 is the minimum).
clip - the rectangular area to modify

feather

public static void feather(java.awt.image.BufferedImage image,
                           int xsize,
                           int ysize,
                           byte dir)
feather (fade to transparent) the image.

See Also:
feather(BufferedImage, int, int, byte, Rectangle)

feather

public static void feather(java.awt.image.BufferedImage image,
                           int xsize,
                           int ysize,
                           byte dir,
                           java.awt.Rectangle clip)
The XSIZE and YSIZE parameters determine how far from the edge of the image to start feathering, and the DIRection specifies whether to feather OUT (FEATHER_OUT_DIR) towards the edges, or IN (FEATHER_IN_DIR) towards the centre.

Parameters:
image - the image to modify
xsize - start feathering at the nth pixel from the left and right edges.
ysize - start feathering at the nth pixel from the top and bottom edges.
dir - specifies whether to feather OUT towards the edges, or IN towards the centre. see FEATHER_OUT_DIR and FEATHER_IN_DIR
clip - defines the edges for feathering. If this is non-null, and specifies values other than (0, 0, image.width, image.height), then the feathering is performed relative to the edges of this rectangle. This is useful if the feathered image is going to be overlaid on some other image using an identical clip region.


Copyright © 1999-2011 by Peter Eastman.