Tutorial

Project Documentation

What is JMAGE?

JMAGE is a Java imaging framework designed for runtime image modification in web applications.
Similar to WYSIWYG imaging apps, it defines layered image filters, which are then applied over image resources in your application on the server side.
JMAGE was created with ease of use in mind, allowing developers with no special skills in graphics software to perform simple image modification tasks programmatically.
For the more advanced user, it also allows for custom extensions. You can write your own image filters or script existing ones into macro style filter chains.
JMAGE is based on Sun's powerful JAI API, which has significant performance advantages over AWT. Combined with smart caching, this allows for efficient, dynamic
image delivery in almost real time out of your servlet container.

Why use it?

A lot of people have probably encountered the problem of having to modify an image while writing a web application. It is either too big, has the wrong
colors, or size. Some customers have more complicated demands and need thumbnail previews for products or a custom watermark with a copyright notice. This is
not too hard to do for a single image using standalone graphics software, however it suddenly becomes work overhead for a collection of images, i.e on a
product catalogue jsp page.

Frame image

Once business rules require your images to behave situative, you will start thinking of programmatic control. JMAGE was conceived to do exactly that
for J2EE web apps. It comes with a set of predefined filters which perform standard tasks such as resize, sharpen, greyscale and provides you with ways
to easily apply and configure them.

Greyscale icons

For more sophisticated transformations, You can arrange filters in chains to do something like like crop -> resize -> frame in one go.
If JMAGE doesn't have the filter you need, writing a custom one is easy. You can then either use that filter alone or put it in any position
of any existing filterchain you like.

Add copyright watermark

So how does it work?

The basic difference between using JMAGE and a standalone app is that if you are using the latter you are pre-rendering all your
images at compile time. With JMAGE, you will render the image inside your servlet container upon the first request for it, while the results will be
held in cache for subsequent requests. This also means that only the images actually loaded by users will get rendered and
there is no need to prepare a large collection of them in advance. Even better: you can use one base image in your application
and serve it to your customers differently, depending which context or page they request it from.

JMAGE follows a relatively simple workflow to achieve this. First the image is loaded from inside your web application as usual
(or even from other locations if you really wanted to), then JMAGE will perform filtering as requested, finally it will encode
your image in a particular format. That's right, you can also
use JMAGE to transcode your images from say high quality BMP to browser friendly JPG or GIF. It's good practice among graphics designers not
to use lossy formats such as JPG as a source for further modifications because of compression artefacts. So why should you have do that
in your app? Simply use high quality input material, even if it is not displayable in your favourite browser, and transcode it as needed
at runtime.

Let's have a look at the workflow again. This is to illustrate the three simple things JMAGE does to your image.

Load the image from your web application context, file system, or any URL.

Render the image through one or a sequence of filters.

Encode the final results in a specific image format

All JMAGE has to do then is give the requested image back to the browser. It basically acts as an intermediate between the servlet
container and the actual image resource.