ImageTools documentation.html

h1. Installation and usage

This is a very basic plugin, that so far encapsulates JAI calls for operations such as image loading, saving, cropping, masking and thumbnail creation.

From the root of your application, call

{code}
grails install-plugin http://www.arquetipos.co.cr/blog/files/grails-image-tools-1.0.5.zip
{code}

All plugin dependencies - two JAI libraries - will be included.  You can also find the plugin repository at [its new home on Github|http://github.com/ricardojmendez/grails-imagetools/].

Once the plugin has been installed in your project you'll have a new class at your disposal, called ImageTool.   You can use an instance of this class to load an image, operate on it, and save the result.  

{code}
// To load an image from a buffer
def imageTool = new ImageTool()
imageTool.load(f.getBytes())

// To load an image from a path
imageTool.load("/path/to/image.jpg")
{code}

You can save an in-memory snapshot of the image before applying any operations.

{code}
imageTool.saveOriginal()
{code}

Once loaded, the image can be resized by calling:

{code}
imageTool.thumbnail(640)  // With the desired thumbnail size
{code}

And then the resulting image can be saved to a file calling

{code}
imageTool.writeResult("smaller.640.jpg", "JPEG")
{code}

Starting on 1.0.4, it can also be saved as a byte array, courtesy of code sent in by Paul Bowler:

{code}
var arr = imageTool.getBytes("JPEG")
{code}


An important note is that the loaded image is never explicitly replaced after an operation - instead, a resulting image is created in the object. If you wish to apply more operations to the result, you should swap it with the originally loaded image.

{code}
imageTool.swapSource()
{code}

There are three functions that you use in order to apply an alpha mask to an image: first you load the alpha and the mask, and then apply them.

{code}
imageTool.loadAlpha("alpha.jpg")
imageTool.loadMask("mask.jpg")
imageTool.applyMask()
{code}

Easy enough, isn't it?  Let's go for a more complex example.  Suppose you want to load an image, reduce it to a maximum size of 640, crop it to a square, then create thumbnails in several sizes and apply masks that have the name "Alpha_XYZ.jpg" and "Mask_XYZ.jpg", where XYZ is the thumbnail size.  This is how you would do it:

{code}
def imageTool = new ImageTool()
imageTool.load("/path/to/image.jpg")
// Reduces the image size
imageTool.thumbnail(640)
// Saves the result
imageTool.writeResult("image_smaller.jpg", "JPEG")
// Crops it to a square
imageTool.square()
/* 
 * Swaps the resulting image with the main one, so that we continue to
 * operate on the square crop.
 */
imageTool.swapSource()
// Creates a copy of the original for later restore
imageTool.saveOriginal()
/* 
 * Iterate through the thumbnail sizes that we want
 *
 */
[178, 133, 69].each {
    def tempName = "image.${it}.jpg"
    /*
     * Creates and saves the thumbnail. It needs to be temporarily saved
     * and re-loaded before applying the masking operation, because of 
     * something that seems to be a JAI glitch.
     * See the following link for details:
     * http://ricardo.strangevistas.net/jai-and-masking-operations.html
     */
    imageTool.thumbnail(it)
    imageTool.writeResult(tempName, "JPEG")
    imageTool.load(tempName)
    // Loads the alpha and mask, and applies them
    imageTool.loadAlpha("Alpha_${it}.jpg")
    imageTool.loadMask("Mask_${it}.jpg")
    
	imageTool.applyMask()
	// Finally, save it and restore the original so that we can continue
	// to operate on the unmodified image
    imageTool.writeResult(tempname, "JPEG")
    imageTool.restoreOriginal()
}
{code}

That's all for now, folks.  Grab me on the Grails list or at ricardo at arquetipos dot co dot cr if you need any more pointers.  Good luck!



h1. FAQs


h2. mediaLib accelerator

ImageTools uses [JAI|http://java.sun.com/javase/technologies/desktop/media/] for its image-handling operations.  JAI can use an optional native library for extra performance, or can work in pure Java mode, but if the native library is not present you might get an exception like the following:.
{code}
Error: Could not find mediaLib accelerator wrapper classes. Continuing in pure Java mode
Occurs in: com.sun.media.jai.mlib.MediaLibAccessor
java.lang.NoClassDefFoundError: com/sun/medialib/mlib/Image
at com.sun.media.jai.mlib.MediaLibAccessor$1.run(MediaLibAccessor.java:248)
{code}
This only means that the native libraries weren't found, and you can still use the ImageTools plugin like you would expect.  To see how to get rid of this error, or learn more about JAI's native support, [read this thread|http://www.nabble.com/get-rid-of-%22Could-not-find-mediaLib-accelerator-wrapper-classes%22-t3889554.html].


h2. License

Copyright (c) 2009 Ricardo J. Méndez

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.