org.jaitools.jiffle
Class JiffleBuilder

java.lang.Object
  extended by org.jaitools.jiffle.JiffleBuilder

public class JiffleBuilder
extends java.lang.Object

A builder class which makes it easier 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.


 // 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");
 
JiffleBuilder also provides support for setting world units and coordinate transforms.

Since:
0.1
Version:
$Id: JiffleBuilder.java 1653 2011-06-16 10:23:02Z michael.bedward $
Author:
Michael Bedward

Constructor Summary
JiffleBuilder()
          Creates a new JiffleBuilder instance.
 
Method Summary
 void clear()
          Clears all attributes in this builder.
 JiffleBuilder defaultTransform(CoordinateTransform transform)
          Sets a default CoordinateTransform instance to use with all images that are passed to the builder without an explicit transform of their own.
 JiffleBuilder dest(java.lang.String varName, int width, int height)
          Creates a new destination image and associates it with a variable name in the script.
 JiffleBuilder dest(java.lang.String varName, int width, int height, CoordinateTransform transform)
          Creates a new destination image and associates it with a variable name in the script.
 JiffleBuilder dest(java.lang.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(java.lang.String varName, int minx, int miny, int width, int height, CoordinateTransform transform)
          Creates a new destination image and associates it with a variable name in the script.
 JiffleBuilder dest(java.lang.String varName, java.awt.Rectangle destBounds)
          Creates a new destination image and associates it with a variable name in the script.
 JiffleBuilder dest(java.lang.String varName, java.awt.Rectangle destBounds, CoordinateTransform transform)
          Creates a new destination image and associates it with a variable name in the script.
 JiffleBuilder dest(java.lang.String varName, java.awt.image.WritableRenderedImage destImage)
          Sets a destination image associated with a variable name in the script.
 JiffleBuilder dest(java.lang.String varName, java.awt.image.WritableRenderedImage destImage, CoordinateTransform transform)
          Sets a destination image associated with a variable name in the script.
 java.awt.image.RenderedImage getImage(java.lang.String varName)
          Get an image associated with a script variable name.
 JiffleDirectRuntime getRuntime()
          Creates a runtime object for the currently set script and images.
 java.lang.String getRuntimeSource()
          Gets the Java run-time class code generated from the compiled script.
 java.awt.image.RenderedImage removeImage(java.lang.String varName)
          Removes an image associated with a script variable name.
 JiffleBuilder run()
          Runs the script.
 JiffleBuilder script(java.io.File scriptFile)
          Reads the script from scriptFile.
 JiffleBuilder script(java.lang.String script)
          Sets the script to be compiled.
 JiffleBuilder source(java.lang.String varName, java.awt.image.RenderedImage sourceImage)
          Associates a variable name with a source image.
 JiffleBuilder source(java.lang.String varName, java.awt.image.RenderedImage sourceImage, CoordinateTransform transform)
          Associates a variable name with a source image and coordinate transform.
 JiffleBuilder worldAndNumPixels(java.awt.geom.Rectangle2D worldBounds, int numX, int numY)
          Sets the bound and resolution of the processing area.
 JiffleBuilder worldAndRes(java.awt.geom.Rectangle2D worldBounds, double xres, double yres)
          Sets the bound and resolution of the processing area.
 
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.


worldAndRes

public JiffleBuilder worldAndRes(java.awt.geom.Rectangle2D worldBounds,
                                 double xres,
                                 double yres)
Sets the bound and resolution of the processing area. If the client does not explicitly set the processing area the default is used (first destination or source image bounds and resolution).

Parameters:
worldBounds - bounds in world units
xres - pixel width in world units
yres - pixel height in world units
Returns:
the instance of this class to allow method chaining

worldAndNumPixels

public JiffleBuilder worldAndNumPixels(java.awt.geom.Rectangle2D worldBounds,
                                       int numX,
                                       int numY)
Sets the bound and resolution of the processing area. If the client does not explicitly set the processing area the default is used (first destination or source image bounds and resolution).

Parameters:
worldBounds - bounds in world units
numX - number of pixels in the X direction
numY - number of pixels in the Y direction
Returns:
the instance of this class to allow method chaining

script

public JiffleBuilder script(java.lang.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(java.io.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(java.lang.String varName,
                            java.awt.image.RenderedImage sourceImage)
Associates a variable name with a source image. The default coordinate system will be used for this image. 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

source

public JiffleBuilder source(java.lang.String varName,
                            java.awt.image.RenderedImage sourceImage,
                            CoordinateTransform transform)
Associates a variable name with a source image and coordinate transform. The image will be stored by the builder as a weak reference.

Parameters:
varName - variable name
sourceImage - the source image
transform - the transform to convert world coordinates to this image's pixel coordinates
Returns:
the instance of this class to allow method chaining

dest

public JiffleBuilder dest(java.lang.String varName,
                          java.awt.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(java.lang.String varName,
                          java.awt.Rectangle destBounds,
                          CoordinateTransform transform)
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
transform - the transform to convert world coordinates to this image's pixel coordinates
Returns:
the instance of this class to allow method chaining

dest

public JiffleBuilder dest(java.lang.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(java.lang.String varName,
                          int width,
                          int height,
                          CoordinateTransform transform)
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)
transform - the transform to convert world coordinates to this image's pixel coordinates
Returns:
the instance of this class to allow method chaining

dest

public JiffleBuilder dest(java.lang.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(java.lang.String varName,
                          int minx,
                          int miny,
                          int width,
                          int height,
                          CoordinateTransform transform)
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)
transform - the transform to convert world coordinates to this image's pixel coordinates
Returns:
the instance of this class to allow method chaining

dest

public JiffleBuilder dest(java.lang.String varName,
                          java.awt.image.WritableRenderedImage destImage)
Sets a destination image associated with a variable name in the script.

See dest(String, WritableRenderedImage, CoordinateTransform) for more details about this method.

Parameters:
varName - variable name
destImage - the destination image
Returns:
the instance of this class to allow method chaining

dest

public JiffleBuilder dest(java.lang.String varName,
                          java.awt.image.WritableRenderedImage destImage,
                          CoordinateTransform transform)
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), transform);

 // Later - oops, null is returned 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, transform);
 
Or use on of the dest methods with image bounds arguments to create it for you

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

 // Now, we can retrieve the image successfully
 RenderedImage img = builder.getImage("foo");
 

Parameters:
varName - variable name
destImage - the destination image
transform - the transform to convert world coordinates to this image's pixel coordinates
Returns:
the instance of this class to allow method chaining

defaultTransform

public JiffleBuilder defaultTransform(CoordinateTransform transform)
Sets a default CoordinateTransform instance to use with all images that are passed to the builder without an explicit transform of their own. If transform is null, the system default transform will be used for any such images.

Parameters:
transform - a transform to use as the default; or null for the system default transform
Returns:
the instance of this class to allow method chaining
See Also:
JiffleRuntime.setDefaultTransform(CoordinateTransform)

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

getRuntimeSource

public java.lang.String getRuntimeSource()
                                  throws JiffleException
Gets the Java run-time class code generated from the compiled script.

Returns:
the run-time source code
Throws:
JiffleException - if the script has not been set yet or if compilation errors occur

getImage

public java.awt.image.RenderedImage getImage(java.lang.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 java.awt.image.RenderedImage removeImage(java.lang.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.

Note: Thie method also removes any CoordinateTransform associated with the image.

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


Copyright © 2011. All Rights Reserved.