Jakarta Project: Image Tag library
Version: 1.0
Table of Contents
Overview
This JSP tag library generates and transforms images dynamically.
It exposes the imaging capability available in Java2D, Java Advanced
Imaging, ImageIO, etc., as a set of tags.
One of the design objectives was to keep it as simple as possible.
It does not require the user to have an in-depth knowledge of the underlying
imaging APIs. Currently it includes the basic Java2D and Java
Advanced Imaging based implementations. The Java2D implementation uses
ImageIO if it is available or else defaults to AWT.
Requirements
This custom tag library can use optional software such as Java Advanced Imaging
(JAI), ImageIO, etc., other than a servlet container that supports the JavaServer
Pages Specification, version 1.1 or higher.
- It was tested on Tomcat 4.1 but any JSP 1.1 compliant servlet container
should do.
- Java 1.2 or above.
- Currently the tags use Java2D (with ImageIO or just AWT) OR Java
Advanced Imaging API (JAI). JAI or ImageIO support is loaded if the classes
are available. Absence of ImageIO and JAI classes will force the usage of
the AWT for loading and encoding/ saving. AWT currently supports only the
reading of GIF and JPEG files and encoding of JPEG only. Writing GIF is NOT
supported by any of the above mentioned libraries. ImageIO may be added
separately for Java versions prior to 1.4.
- On a server without a graphics environment (X-Windows or MS Windows), the
"
java.awt.headless=true" option should be set or a work-around
such as loading XVFB or so must be done.
- Since Java2D loads only GIF, JPEG and BMP images, the new ImageIO is used.
Hence now it needs: - J2SDK-1.4 and above OR J2SDK-1.2 and above with ImageIO
jar OR J2SDK-1.2 and above with JAI jars.
- This Tag library uses
"Poor Man's Imaging Wrapper" (PMIW), a simple imaging wrapper library.
This wrapper exposes a very simple interface for imaging operation using
Java2D, JAI, etc. It is distributed under the Apache software
license and the binary is included in this taglib distribution. The source
of PMIW can be obtained from
PMIW project home.
The source was not made part of this library because it is used for other projects
such as ANT image tasks, etc.
- You will need pjatools.jar from the
PJA Toolkit for GIF encoding support. This jar is NOT included in the taglib
distribution.
Configuration
Follow these steps to configure your web application with this tag
library:
To use the tags from this library in your JSP pages, add the following
directive at the top of each page:
<%@ taglib uri="http://jakarta.apache.org/taglibs/image-1.0" prefix="img" %>
where "img" is the tag
name prefix you wish to use for tags from this library. You can change
this value to any prefix you like.
Tag Summary
Image Tags
| image |
The parent tag that loads, saves and prints the HTML img tag.
It also serves as the nested tag for other tags such as overlay
tag that required to load images.
|
| resize |
This tag scales/ resizes an image loaded by an enclosing parent
tag. This can be used to generate thumbnails or to zoom into an image.
|
| overlay |
This tag overlays an image on the parent image. It can paint transparent
images. A color can be specified to make those pixels appear transparent.
|
| transparency |
This tag makes the image translucent. It supports 255 levels of tranparency.
|
| rotate |
This tag rotates the image through a certain degrees. The output image
dimensions are changed to accommodate the entire image.
|
| border |
This tag adds a border to an existing image. The thickness and color of the
border can be specified.
|
| grayscale |
This tag converts a color image to grayscale, i.e., only shades on gray.
|
| crop |
This tag can crop or cut-out a subImage of a bigger image.
|
| text |
This tag can write or paint a text/a string on the image.
|
| |
Tag Reference
| image |
Availability: 1.0 |
|
Image tag loads an image from a URL and lets its nested
tags to do transformations on it. The read is based on the
available Imaging capability. If Java Advanced Imaging classes or
ImageIO classes are available, numerous image formats can be
read. If not, the default Java-1.2 AWT supports only reading
JPEG or GIF. Encoding the output in the GIF format is not
supported. It avoids throwing errors whenever possible.
If it is used as a nested tag, it just loads and passes it to the
parent tag for immediate use and does not save it.
|
| Tag Body | JSP | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | src |
No
|
Yes
| 1.0 |
| |
An absolute or relative URL of the an image. The image is loaded
from this URL if the image file specified in the image attribute
is not available OR if the refresh option is set to true.
|
| | name |
No
|
Yes
| 1.0 |
| |
The file name for the output image. The format/ encoding of the output
image is decided from the extension on this name. The extention can be
jpeg, jpg, png, gif, etc. The default is the same as the src image.
Java2d supports only jpeg. JAI supports jpeg, png, tiff, bmp, etc. but
not gif. For gif encoding pja-tools.jar must be included in the
classpath. The tag searches for an image file with this name and loads
it if it exists UNLESS the refresh attribute is set to true. Just the
output filename without the path is expected.
|
| | usingImageNameInSession |
No
|
No
| 1.0 |
| |
Indicates that the servlet uses the name of the image stored in the session.
|
| | dir |
No
|
Yes
| 1.0 |
| |
The output file is generated in and reloaded from this directory. If
specified it is expected to be relative to the context path. The generated
images are saved into this directory and the img url is set appropriately.
If the dir attribute is not set, the images are saved to the context temp
directory and a servlet is used to serve them later. The servlet name/ mapping
can be specified as a context parameter in the web.xml (see the web.xml in
the image-examples.war)
|
| | refresh |
No
|
Yes
| 1.0 |
| |
If this value is set to true, the image is generated on every access.
If it is set to false (default) the dynamic image is generated only
when the output image (already generated) is absent (first access).
|
| | display |
No
|
Yes
| 1.0 |
| |
If this attribute is set to true, the HTML img tag is not generated,
eventhough the image is generated and saved.
|
| | attributes |
No
|
Yes
| 1.0 |
| |
All the attributes that needs to be included in the HTML img tag can
be included in this attribute. It is just a direct copy of the String
specified here. If this value does not contain the width and height
attributes, they are added by the tag.
|
| | imagingType |
No
|
Yes
| 1.0 |
| |
The imaging library used is specified by this attribute. It could be
JAVA2D or JAI. By default it will look for JAI and if those classes are
not available it will load Java2D imaging support.
|
| | quality |
No
|
Yes
| 1.0 |
| |
The quality of the output image file. The value must be between
0.0 and 1.0. The default is 0.6.
|
| Variables | None |
| Examples |
This just loads an image and displays it. It does not do anything
else unless nested transformation tags (give below) are included.
This will print an img tag with the width
and height attributes as well, like
<img src="http://yourdomain.com/generated/splash-new.jpg" width="300"
height="200" alt='A sample image' />
|
| |
<img:image
src="/images/splash.jpg"
dir="generated"
name="splash-new.jpg"
attributes="alt='A sample image'"
refresh="false"
quality="0.8">
</img:image>
|
| resize |
Availability: 1.0 |
|
This nested/ child tag of the <image> tag
can be used to scale an image to a percentage (both width and height)
or can be scaled to a specific width and height. If either width or
height is present while the other is missing, the other value is
calculated keeping the aspect-ratio. Either scale OR
width OR height OR both width
and height can be specified.
|
| Tag Body | empty | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | scale |
No
|
Yes
| 1.0 |
| |
The scale is specified as a percentage of the image's dimensions, for eg.,
"50%" means that the width and height of the image will be
reduced to half its current values. This also means that the aspect-ratio
of the image is maintained in this case. The scale percentage cannot be
zero or less. When this attribute is specified, the width and height
attributes, if specified, are ignored.
|
| | width |
No
|
Yes
| 1.0 |
| |
The width of the output image can be specified as number of pixels wide
OR as a percentage of the current width. In either case, if the height
attribute is not specified, it is calculated keeping the aspect ratio.
However if the scale attribute is specified, this attribute is ignored.
|
| | height |
No
|
Yes
| 1.0 |
| |
The height of the output image can be specified as number of pixels high
OR as a percentage of the current height. In either case, if the width
attribute is not specified, it is calculated keeping the aspect ratio.
However if the scale attribute is specified, this attribute is ignored.
|
| | bestfit |
No
|
Yes
| 1.0 |
| |
The image is scaled within the rectangled specified by the width and height
keeping the aspect ratio of the original image if this option is true. The
width and height MUST be specified if this option is set true.
|
| Variables | None |
| Examples |
This example loads an image, resizes it to 100 pixels.
Since only the width is specified the appropriate height
is calculated by the tag itself. The img tag it prints out
after generating the image is like <img
src="http://yourdomain.com/gen-images/splash-thumb.jpg"
width="100" height="67" alt='A thumbnail' />.
The width or height may also be specified as a percentage "40%"
|
| |
<img:image
src="images/splash.jpg"
name="splash-thumb.jpg"
attributes="alt='A thumbnail'">
<img:resize width="100" />
</img:image>
|
|
This example loads an image, scales the total image to 50%.
The scale is specified in percentage. The <img> tag it prints out
after generating the image is like <img
src="http://yourdomain.com/generated/splash-thumb.jpg"
width="150" height="100" alt='A thumbnail' />
|
| |
<img:image
src="/images/splash.jpg"
dir="generated"
name="splash-thumb.jpg"
attributes="alt='A thumbnail'">
<img:resize scale="50%" />
</img:image>
|
| overlay |
Availability: 1.0 |
|
This nested/ child tag of the <image> tag can paint
another image on the parent image. The new image is specified by a nested
<image> tag. This image itself can undergo a set of
imaging operations before it is used. It can also refer to an existing
dynamically generated image (by a previous tag). Since this image is not
encoded but only used to overlay, even GIF images can be used.
|
| Tag Body | JSP | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | x |
No
|
Yes
| 1.0 |
| |
The horizontal distance from the top-left corner of the current image to the
point where the new image is painted (the top-left corner of the new image).
The value can be in the number of pixels OR as a percentage of the current width.
|
| | y |
No
|
Yes
| 1.0 |
| |
The vertical distance from the top-left corner of the current image to the
point where the new image is painted (the top-left corner of the new image).
The value can be in the number of pixels OR as a percentage of the current height.
|
| | color |
No
|
Yes
| 1.0 |
| |
A color can be specified to be made transparent. This is particularly useful to
remove/ignore the black/ white background of images that does not support transparency.
The color can be specified as an integer, for e.g., "0xff0000" for red.
This will be decoded to obtain the color. There is no default color.
|
| | tolerance |
No
|
Yes
| 1.0 |
| |
The tolerance value is used to specify the amount of variation in the color components
allowed of the color specified as transparent, i.e., if the difference of the
"red", "green" and "blue" components of the specified
"color" and a pixel on the overlaid image is within this tolerance value,
that pixel is considered transparent.
|
| Variables | None |
| Examples |
This example loads an image "splash.jpg".
It then loads another image "asf-logo", resizes it to "60%"
and overlays it on the parent image. The color "white" ("0xffffff") in the
"asf-logo.jpg" is treated as transparent while overlaying.
|
| |
<img:image
src="images/splash.jpg"
name="splash-thumb.jpg" >
<img:overlay x="10%" y="60%" color="0xffffff" tolerance="35">
<img:image src="/images/asf-logo.jpg">
<img:resize scale = "60%" />
</img:image>
</img:overlay>
</img:image>
|
| transparency |
Availability: 1.0 |
|
This nested/ child tag of the <image> tag can add
transparency to an image. This is usually useful if you want an overlaid image
to be translucent.
|
| Tag Body | JSP | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | level |
No
|
Yes
| 1.0 |
| |
The level value is used to specify the amount of transparency to be added. It can range from
0 (no change) to 255 (fully transparent). Note that the transparent pixels and semi-transparent
will also be affected.
|
| Variables | None |
| Examples |
This example loads an image "splash.jpg".
It then loads another image "asf-logo", adds transparency of "125"
(half opaque/ transparent) and overlays it on the parent image. The color "white"
("0xffffff") in the "asf-logo.jpg" is treated as transparent while
overlaying.
|
| |
<img:image
src="images/splash.jpg"
name="splash-thumb.jpg" >
<img:overlay x="10%" y="60%" color="0xffffff" tolerance="35">
<img:image src="/images/asf-logo.jpg">
<img:transparency level="125" />
</img:image>
</img:overlay>
</img:image>
|
| rotate |
Availability: 1.0 |
|
This nested/ child tag of the <image> tag can rotate an image through
a specified degrees. The background of the new image after rotation may depend on the type
of image such as transparent or otherwise. The new image is made large enough to accommodate
the entire image without any cropping.
|
| Tag Body | empty | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | degrees |
Yes
|
Yes
| 1.0 |
| |
The degrees through which the image is rotated. A negative value rotates
the image in the anti-clockwise direction.
|
| Variables | None |
| Examples |
This example loads an image "splash.jpg".
Then it is rotated in the anti-clockwise direction by 30 degrees.
The resultant image dimensions are larger so that no part of the rotated
image is cropped off.
|
| |
<img:image
src="images/splash.jpg"
name="splash-thumb.jpg" >
<img:rotate degrees="-30" />
</img:image>
|
| border |
Availability: 1.0 |
|
This nested/ child tag of the <image> tag adds a border
to the image. The color of the border can also be specified. The thickness
of the border at the sides and at the top and bottom of the image is specified
separately.
|
| Tag Body | empty | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | width |
Yes
|
Yes
| 1.0 |
| |
The width of the border on the left and right sides of the image can be
specified as number of pixels wide. If no value s specified, no border
on the left and right side is added.
|
| | height |
Yes
|
Yes
| 1.0 |
| |
The height of the border on the top and bottom sides of the image can be
specified as number of pixels wide. If no value s specified, no border
on the top and bottom is added.
|
| | color |
No
|
Yes
| 1.0 |
| |
The color of the border can be specified as an integer, for e.g.,
"0xff0000" for red. This will be decoded to obtain the color.
The default color is black.
|
| Variables | None |
| Examples |
This example loads an image "splash.jpg".
Then it adds a border that has a thickness of 5 pixels on the sides
and 3 pixels on the top and bottom in the color whose RGB values are
specified in hex values.
|
| |
<img:image
src="images/splash.jpg"
name="splash-thumb.jpg" >
<img:border width="5" height="3" color="0x44dd44"/>
</img:image>
|
| grayscale |
Availability: 1.0 |
|
This nested/ child tag of the <image> tag converts a
color image to a grayscale image.
|
| Tag Body | empty | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | brightness |
No
|
Yes
| 1.0 |
| |
This value between "0.00" and "9.99" specifies the
brightness factor of the grayscale image generated.
|
| Variables | None |
| Examples |
This example loads an image "splash.jpg".
Then it is converted to grayscale.
|
| |
<img:image
src="images/splash.jpg"
name="splash-thumb.jpg" >
<img:grayscale brightness="30" />
</img:image>
|
| crop |
Availability: 1.0 |
|
This nested/ child tag of the <image> tag can crop or
cut-out a subImage of a bigger image. The sub-image area is always specified
as a rectangular area whose top-left point and the width and height can be specified.
|
| Tag Body | empty | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | x |
No
|
Yes
| 1.0 |
| |
The horizontal distance from the top-left corner of the current image to the
point where the cropping begins. The value can be in the number of pixels OR
as a percentage of the current width.
|
| | y |
No
|
Yes
| 1.0 |
| |
The vertical distance from the top-left corner of the current image to the
point where the cropping begins. The value can be in the number of pixels OR
as a percentage of the current height.
|
| | width |
Yes
|
Yes
| 1.0 |
| |
The width of the output sub-image is specified relative to the "x"
attribute. The value can be in the number of pixels OR as a percentage of the
current width.
|
| | height |
Yes
|
Yes
| 1.0 |
| |
The height of the output sub-image is specified relative to the "y"
attribute. The value can be in the number of pixels OR as a percentage of the
current height.
|
| Variables | None |
| Examples |
This example loads an image "splash.jpg".
Then it crops off (removes) all the portions except a horizontal band at the
center of the image. The cropping starts from "25%" below the top edge
and continues till "75%" (= 25% + 50%).
|
| |
<img:image
src="images/splash.jpg"
name="splash-thumb.jpg" >
<img:crop x="0%" y="25%" width="100%" height="50%"/>
</img:image>
|
| text |
Availability: 1.0 |
|
This nested/ child tag of the <image> tag can add a line of text
on the image. It can be written from a point specified. The color and font can also be
specified.
|
| Tag Body | JSP | | | | |
| Restrictions |
None
|
| Attributes | Name | Required |
Runtime Expression Evaluation
| Availability |
| | x |
No
|
Yes
| 1.0 |
| |
The horizontal distance from the top-left corner of the current image to the
point where the text begins. The value can be in the number of pixels OR
as a percentage of the current width. The default value is "2"
|
| | y |
No
|
Yes
| 1.0 |
| |
The vertical distance from the top-left corner of the current image to the
point of the where the text begins. This point is the BASE of the font/text
and hence the text is painted above this point. If this value if zero, the
text is painted outside the bounds and hence is not visible. The value can be
in the number of pixels OR as a percentage of the current height. The default
value is "98%"
|
| | text |
No
|
Yes
| 1.0 |
| |
The String value that should be written/painted on the image. This may also be
specified in the body. If the text attribute is specified the body is ignored.
|
| | font |
No
|
Yes
| 1.0 |
| |
The name of the font in which the text has to appear. Make sure that this font
is available. The default font is "SanSerif"
|
| | size |
No
|
Yes
| 1.0 |
| |
The size of the font in which the text has to appear.The default size is
"10"
|
| | color |
No
|
Yes
| 1.0 |
| |
The color of the font (as an RGB integer) in which the text has to appear. The default
color value is "0x000000" (black)
|
| | bold |
No
|
Yes
| 1.0 |
| |
Specifies if the font needs to be bold. The default is "false"
|
| | italic |
No
|
Yes
| 1.0 |
| |
Specifies if the font needs to be italic. The default is "false"
|
| Variables | None |
| Examples |
This example loads an image "splash.jpg".
Then it writes/paints the given text/string on the image in bold "Arial".
font with size "12". The text is written "30%" towards the right and
"15" pixels towards the bottom from the top left corner of the image.
|
| |
<img:image
src="images/splash.jpg"
name="splash-thumb.jpg" >
<img:text
text="A part of the Jakarta Tag library"
x="30%"
y="15"
font="Arial"
bold="true"
size="12"
color="0xff0000"
/>
</img:image>
|
The "Mother" <image> tag
Tag structure and image loading
The <image> tag is the parent tag that can take any
number of child (transformation) tags. The <image> tag loads
the image from a URL src or from a previously generated image referenced
by its name. Each child tag does one transformation on the image
referenced by the parent <image> tag. The transformations
are done in the order of the child tags specified. The <image>
tag adds width and height attributes if it is not
specified already. All attributes and JavaScript required for the final HTML
<img> tag can be specified in the attributes
attribute. If the dynamic image (parameters) need not change for each request,
the image needn't be generated for each request. Hence the dynamic image is
generated only once (and saved) if the refresh attribute is "false"
(saving a lot of processing and memory). If the refresh is set
to "true" the image is re-generated for each request. The default
for the refresh attribute is "false". The dir
attribute lets you specify a directory to save the generated images within the context.
The generated images are saved into this directory and the img url is set appropriately.
If the dir attribute is not set, the images are saved to the context temp directory and
a servlet is used to serve them later. The servlet name/ mapping can be specified as a
context parameter in the web.xml (see the web.xml in the image-examples.war). The context
param to be set is "ImageServletMapping". The quality of the final image can
be specified as a float (0.0 to 1.0 - default 0.6) by the quality attribute.
Encoding, HTML generation and access of the images
After completing all the transformations, the <image>
tag saves the image to a file by the name attribute (explicitly
specified) OR a file generated using the source image filename/ URL. The image
type/ encoding is determined from the file's extension. However writing of "GIF"
files is supported ONLY if the pjatools.jar is available in the classpath (instead
of throwing an error, it writes a JPEG image and changes the extension). Then an HTML
<image> tag pointing to the newly created image is printed on to
the page (As we know, the image is accessed by a separate request sometime later).
Image Operations
The children of the <image> tag can be a set of transformation
tags such as: -
-
resize -- scale the image by a percentage or
to a specified width and height. Thus it supports
differential scaling (i.e., scaleX != scaleY). It also has a bestfit option.
-
grayscale -- convert a color image to grayscale.
-
rotate -- rotate the image by some degrees and enlarges it
to still accommodate the full image.
-
crop -- get a rectangular region specified as a percentage
or absolute pixels.
-
border -- add a border to the image in the color
specified. Color is specified as a number such as 0xff00ff (red)
or 0x0000ff(blue).
-
overlay -- overlays/ paints a new image specified by a nested
<image> tag, on the parent image at a specified point.
Transparency effect can be added by specifying a color The pixels
with the color will be considered as transparent.
-
text -- writes a string/ text on the image in the color
and font at a given point.
-
transparency -- adds transparency to the image.
These tags can be combined and used in any order to get the desired effect.
The overlay is useful to add tags like "SOLD", "NEW", etc., to a product image.
Text can be used to add copyright information to images. Grayscale and Resize
can be used to generate thumbnail images. There are numerous ways to use them
in combination. Take a look at the example.
A Sample
Overlay a Rotated transparent image on a Grayscaled image and then Resize
it (GIF on JPEG).
<img:image src="/images/splash.jpg"
dir="generated"
name="splash-new-gray.jpg"
refresh="true"
attributes="border='0' alt='a sample dynamic image'">
<img:grayscale/>
<img:overlay x="55%" y="60%">
<img:image src="/images/new.gif" >
<img:rotate degrees="-30" />
<img:resize scale="80%" />
<img:transparency level="125" />
</img:image>
</img:overlay>
<img:border width="5" height="3"
color="0x005d00"/>
<img:resize bestfit="true" width="200" height="400"/>
</img:image>
The output image of the tag given above:
The sequence of operations to generate the output image: -
- The image file "splash.jpg" is loaded (each time since the "refresh"
is set to "true"). Otherwise it checks for "splash-new-gray.jpg"
in the "generated" directory and loads it.
- The image is converted to grayscale.
- The "new.gif" is overlaid/ painted on the base image at location 5% right
and 60% below (percentages of base image's current "width" and "height"
respectively) the top-left corner. The image for overlay is generated by the following steps: -
- The nested image tag loads the "new.gif"
- The image is rotated by "-30" degrees
- The resulting image is resize/scaled to its "80%"
- A colored border with "5" pixels thickness at the sides and "3" pixels at the top
and bottom is added.
- The whole image is resized/ scaled to fit within a "200" x "400" rectangle.
- The image is saved as "splash-new-gray.jpg" in the "generated"
directory.
- An
<img> tag similar to <img border='0' alt='a sample dynamic image'
src="/generated/splash-new-gray.jpg" width="200" height="132">
is written. The "width" and "height" are that of the resulting image.
On the radar
- Loading Scalable Vector Graphics (SVG) files using Batik.
- Shape overlay and transformation operations such as "ShapeOverlay", "Circle",
"Rectangle", etc.
- Operations such as "Brightness", "Contrast", "Threshold", "Posterize", etc.
- Special operations such as "Tile", "Bevel border", etc.
- The various ways of deleting the image files need to be implemented such
as
deleteOnExit, deleteAfterRequest, deleteAferSession,
etc.
- Implementations based on Standard Windowing Toolkit (SWT).
- Improve the WebColorFilter in GIF encoding.
- Logging support.
Examples
See the example application
image-examples.war for examples of the usage
of the tags from this custom tag library.
Java Docs
Java programmers can view the java class documentation for this tag
library as javadocs.
Revision History
Review the complete revision history of
this tag library.