image

Overview

the image resource-type allows to resize, crop, watermark, rotate an image.

Name:
image
Namespace:
http://www.litwan.com/yanel/resource/1.0
Universal Name:
<{http://www.litwan.com/yanel/resource/1.0}image/>
Description:
resizes, crops, watermarks requested images on the fly (also cacheable) (jpeg, png, gif).
Java Class:
com.litwan.yanel.impl.resources.image.ImageResource

Resource Configuration

yanel-path
Path to the image source. (allows yanelrepo: and yanelresource:). if set yanel-path-matcher and yanel-path-template are ignored
yanel-path-matcher
wildcard path matcher pattern e.g. /*/**.*
yanel-path-template
wildcard replace tokens e.g. /{2}.{3}
preserve-alpha
true or false. by default it looks if the original image has alpha.
target-width
configured image target width. if only width exists, height will be calculated.
target-height
configured image target height. if only height exists, width will be calculated.
crop-x
the x coordinate where the subimage starts
crop-y
the y coordinate where the subimage starts
crop-h
the height of the subimage
crop-w
the width og the subimage
target-percentage
configured image target size in percent. if percentage is used, width/height will be ignored.
allow-request-parameters
allow/deny overwriting height/width/percentage via request parameter. See request parameter. it's probably a good idea to disallow using request parameters in a open/public system , since one could cause heavy loady and memory consumption.
prohibit-up-scale
alternatively one can prohibit up-scale of an image to prevent producing huge data amount. it's probably a good idea ot prohibit up-scale if using request parameters is allowed.
background-color
configuration of the background color (used for transparent images to replace the the transparent part with the color configured within this property). don't set this property if you expect a transparent background.
disable-cache
do not cache images. always recalculate them.
cache-root-path
where the cache is created. default is '/cached-images'
watermark-path
path to a watermark image
watermark-position-x
x position of the watermark image
watermark-position-y
y position of the watermark image
watermark-transparency
transparency of the watermark
rotate
rotation of the image (0,90,180,270 degree)

Request Paramter

yanel.resource.image.width
overrides the configured target width. if only width exists, height will be calculated.
yanel.resource.image.height
overrides the configured target height. if only height exists, width will be calculated.
yanel.resource.image.percentage
overrides the configured target percentage. if percentage is used, width/height will be ignored.
yanel.resource.image.show.original
forces to ignore to current configuration and show the original image
yanel.resource.image.suppress.crop
suppresses the cropping
yanel.resource.image.suppress.resize
suppresses the resizing

Path Matcher/Template

yanel-path-matcher

the yanel-path-matcher tries to match a path and isolates tokens for further usage in the yanel-path-template.

Here is how the matching algorithm works:

The '*' character, meaning that zero or more characters (excluding the path separator '/') are to be matched.
The '**' sequence, meaning that zero or more characters (including the path separator '/') are to be matched.
The '\*' sequence is honored as a litteral '*' character, not a wildcard
When more than two '*' characters, not separated by another character, are found their value is

considered as '**' and immediate succeeding '*' are skipped.


The '**' wildcard is greedy and thus the following sample matches as {"foo/bar","baz","bug"}:

pattern
*,*,/,*,/,*,*
string
foo/bar/baz/bug

The first '**' in the pattern will suck up as much as possible without making the match fail.

yanel-path-template

with yanel-path-template you cunstruct the actual yanel-path where the original image is stored and the image resource will try to read the image from. use the pattern extractions matched by yanel-path-matcher to construct yanel-path-template. patterns are keys in a map of pattern extractionds from left to right beginning with "1" for te left most, "2" for the next, and so on. The key "0" is the string itself.

Image Formats

Supported image formats are jpg, png gif. wheras gif works only since java6. it should be easy to extend the code to allow bmp as well, maybe i will do this later on.

Basic Example:

To use the image resource type first you need to register the resource type as usual. add following line with the correct path to your (local.)resource-types.xml 

<resource-type src="/home/simon/src/3k3-yanel-contrib/resource-types/image/" compile="true"/>

after this you need to add a matcher to the map.rc-map file e.g. 

  <matcher pattern="/image/**.*" rcpath="/image.yanel-rc"/>

then you need to create an image.yanel-rc file with following content. 

<?xml version="1.0"?>

<yanel:resource-config xmlns:yanel="http://www.wyona.org/yanel/rti/1.0">
  <yanel:rti name="image" namespace="http://www.litwan.com/yanel/resource/1.0"/>

  <yanel:property name="target-width" value="200"/>
  <yanel:property name="target-height" value="100"/>
  <yanel:property name="yanel-path-matcher" value="/*/**.*"/>
  <yanel:property name="yanel-path-template" value="/{2}.{3}"/>
</yanel:resource-config>

now if you have an image on http://localhost:8080/realm/img/group_1020.jpg you can view a resized version under http://localhost:8080/realm/image/img/group_1020.jpg

Watermark Example:

<?xml version="1.0"?>
<yanel:resource-config xmlns:yanel="http://www.wyona.org/yanel/rti/1.0">
  <yanel:rti name="image" namespace="http://www.litwan.com/yanel/resource/1.0"/>
  <yanel:property name="preserve-alpha" value="true"/>
  <yanel:property name="allow-request-parameters" value="true"/>
  <yanel:property name="prohibit-up-scale" value="true"/>
  <yanel:property name="target-percentage" value="50"/>
  <yanel:property name="watermark-path" value="/images/3k3-logo-transp.png"/>
  <yanel:property name="watermark-transparency" value="0.5"/>
  <yanel:property name="yanel-path-matcher" value="/*/**.*"/>
  <yanel:property name="yanel-path-template" value="/{2}.{3}"/>
</yanel:resource-config>

IMPORTANT

if you use this resource-type in a headless environement set Djava.awt.headless=true

Demo

http://demo.yanel-contribution.3k3.org/image-resource.html

Source

browse svn repo: http://trac.yanel-contribution.3k3.org/browser/resource-types/image
checkout source: 

svn co https://svn.3k3.org/repos/public/yanel/resource-types/image

License

apache license 2.0