jaitools.jiffle
Class JiffleBuilder

java.lang.Object
  jaitools.jiffle.JiffleBuilder

public class JiffleBuilder
extends Object

A builder script which makes it easy to compile and run basic Jiffle scripts.

When working with Jiffle objects directly you end up writing a certain amount of boiler-plate code for image parameters etc. JiffleBuilder offers concise, chained methods to help you get the job done with fewer keystrokes.

For comparison, first look at this example of creating a Jiffle object and retrieving the runtime instance 'by hand':

 // A script to sum values from two source images
 String sumScript = "dest = foo + bar;" ;

 // Image parameters
 Map<String, Jiffle.ImageRole.SOURCE> imageParams = CollectionFactory.map();
 imageParams.put("dest", Jiffle.ImageRole.DEST);
 imageParams.put("foo", Jiffle.ImageRole.SOURCE);
 imageParams.put("bar", Jiffle.ImageRole.SOURCE);

 // Create a compiled Jiffle object
 Jiffle jiffle = new Jiffle(sumScript, imageParams);

 // Get the runtime object
 JiffleDirectRuntime runtime = jiffle.getRuntimeInstance();

 // Set the source images
 RenderedImage fooImg = ...
 RenderedImage barImg = ...
 runtime.setSourceImage("foo", fooImg);
 runtime.setSourceImage("bar", barImg);

 // Create an image for the results and submit it to
 // the runtime object
 WritableRenderedImage destImg = ImageUtils.createConstantImage(
         fooImg.getWidth(), fooImg.getHeight, 0d);
 runtime.setDestinationImage("dest", destImg);

 // Now run the script
 runtime.evaluateAll(null);
 

Now here is the same task done using JiffleBuilder:

 // A script to sum values from two source images
 String sumScript = "dest = foo + bar;" ;

 RenderedImage fooImg = ...
 RenderedImage barImg = ...

 JiffleBuilder jb = new JiffleBuilder();
 jb.script(sumScript).source("foo", fooImg).script("bar", barImg);

 // We can get the builder to create the destination image for us
 jb.dest("dest", fooImg.getWidth(), fooImg.getHeight());

 // Run the script
 jb.getRuntime().run();

 // Since we asked the builder to create the destination image we
 // now need to get a reference to it
 RenderedImage destImg = jb.getImage("dest");
 

When a script does not use any source images, JiffleBuilder makes for very concise code:

 String script = "waves = sin( 4 * M_PI * x() / width() );" ;
 JiffleBuilder jb = new JiffleBuilder();
 RenderedImage wavesImg = jb.script(script).dest("waves", 500, 200).run().getImage("waves");
 

Since:

1.1

Version:

$Id: JiffleBuilder.java 1512 2011-03-07 02:21:45Z michael.bedward $

Author:

Michael Bedward

Constructor Summary

JiffleBuilder()
Creates a new JiffleBuilder instance.

Method Summary

void	clear() Clears all attributes in this builder.
JiffleBuilder	dest(String varName, int width, int height) Creates a new destination image and associates it with a variable name in the script.
JiffleBuilder	dest(String varName, int minx, int miny, int width, int height) Creates a new destination image and associates it with a variable name in the script.
JiffleBuilder	dest(String varName, Rectangle destBounds) Creates a new destination image and associates it with a variable name in the script.
JiffleBuilder	dest(String varName, WritableRenderedImage destImage) Sets a destination image associated with a variable name in the script.
RenderedImage	getImage(String varName) Get an image associated with a script variable name.
JiffleDirectRuntime	getRuntime() Creates a runtime object for the currently set script and images.
RenderedImage	removeImage(String varName) Removes an image associated with a script variable name.
JiffleBuilder	run() Runs the script.
JiffleBuilder	script(File scriptFile) Reads the script from scriptFile.
JiffleBuilder	script(String script) Sets the script to be compiled.
JiffleBuilder	source(String varName, RenderedImage sourceImage) Associates a source image with a variable name in the script.

Methods inherited from class java.lang.Object

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

Constructor Detail

JiffleBuilder

public JiffleBuilder()

Creates a new JiffleBuilder instance.

Method Detail

clear

public void clear()

Clears all attributes in this builder. If destination images were created using the dest methods with image bounds arguments they will also be freed.

script

public JiffleBuilder script(String script)

Sets the script to be compiled.

Parameters:

script - the script

Returns:

the instance of this class to allow method chaining

script

public JiffleBuilder script(File scriptFile)
                     throws JiffleException

Reads the script from scriptFile.

Parameters:

scriptFile - file containing the script

Returns:

the instance of this class to allow method chaining

Throws:

JiffleException - if there were problems reading the file

source

public JiffleBuilder source(String varName,
                            RenderedImage sourceImage)

Associates a source image with a variable name in the script. The image will be stored by the builder as a weak reference.

Parameters:

varName - variable name

sourceImage - the source image

Returns:

the instance of this class to allow method chaining

dest

public JiffleBuilder dest(String varName,
                          Rectangle destBounds)

Creates a new destination image and associates it with a variable name in the script.

Note: a JiffleBuilder maintains only WeakReferences to all source images and any destination images passed to it via the dest(String, WritableRenderedImage) method. However, a strong reference is stored to any destination images created with this method. This can be freed later by calling clear() or removeImage(String varName).

Parameters:

varName - variable name

destBounds - the bounds of the new destination image

Returns:

the instance of this class to allow method chaining

dest

public JiffleBuilder dest(String varName,
                          int width,
                          int height)

Creates a new destination image and associates it with a variable name in the script. The minimum pixel X and Y ordinates of the destination image will be 0.

Note: a JiffleBuilder maintains only WeakReferences to all source images and any destination images passed to it via the dest(String, WritableRenderedImage) method. However, a strong reference is stored to any destination images created with this method. This can be freed later by calling clear() or removeImage(String varName).

Parameters:

varName - variable name

width - image width (pixels)

height - image height (pixels)

Returns:

the instance of this class to allow method chaining

dest

public JiffleBuilder dest(String varName,
                          int minx,
                          int miny,
                          int width,
                          int height)

Creates a new destination image and associates it with a variable name in the script.

Note: a JiffleBuilder maintains only WeakReferences to all source images and any destination images passed to it via the dest(String, WritableRenderedImage) method. However, a strong reference is stored to any destination images created with this method. This can be freed later by calling clear() or removeImage(String varName).

Parameters:

varName - variable name

minx - minimum pixel X ordinate

miny - minimum pixel Y ordinate

width - image width (pixels)

height - image height (pixels)

Returns:

the instance of this class to allow method chaining

dest

public JiffleBuilder dest(String varName,
                          WritableRenderedImage destImage)

Sets a destination image associated with a variable name in the script.

Note: The builder will only hold a Weak reference to destImg so it's not a good idea to create an image on the fly when calling this method...

 // creating image on the fly
 builder.dest("foo", ImageUtils.createConstantImage(width, height, 0d));

 // later... img will be null here
 RenderedImage img = builder.getImage("foo");
 

To avoid this problem, create your image locally...

 WritableRenderedImage img = ImageUtils.createConstantImage(width, height, 0d);
 builder.dest("foo", img);
 

Or use on of the dest methods with image bounds arguments to create it for you

 builder.dest("foo", width, height);

 // later... we will get a valid reference to the image
 RenderedImage img = builder.getImage("foo");
 

Parameters:

varName - variable name

destImage - the destination image

Returns:

the instance of this class to allow method chaining

run

public JiffleBuilder run()
                  throws JiffleException

Runs the script. Equivalent to calling builder.getRuntime().evaluateAll(null).

Returns:

the instance of this class to allow method chaining

Throws:

JiffleException - if the script has not been set yet or if compilation errors occur

getRuntime

public JiffleDirectRuntime getRuntime()
                               throws JiffleException

Creates a runtime object for the currently set script and images.

Returns:

an instance of JiffleDirectRuntime

Throws:

JiffleException - if the script has not been set yet or if compilation errors occur

getImage

public RenderedImage getImage(String varName)

Get an image associated with a script variable name. The image must have been previously suppolied to the builder using the (@code source} method or one of the dest methods.

In the case of a destination image the object returned can be cast to WritableRenderedImage.

Parameters:

varName - variable name

Returns:

the associated image or null if the variable name is not recognized or the image has since been garbage collected

removeImage

public RenderedImage removeImage(String varName)

Removes an image associated with a script variable name. The image should have been previously suppolied to the builder using the (@code source} method or one of the dest methods.

In the case of a destination image the object returned can be cast to WritableRenderedImage.

Parameters:

varName - variable name

Returns:

the associated image or null if the variable name is not recognized or the image has since been garbage collected