Image Server
1. Image Server
The Image Server processor serves images stored locally or remotely (for example
through HTTP) to a Web browser. Only the JPEG format is supported at the moment.
Before sending or transforming a resource, the Image Server checks that the
resource is a JPEG image. The Image Server is able to perform simple
transformations such as scaling and cropping, in which case it also handles a cache
of transformed images.
1.1 Configuration
The config input must follow this Relax NG schema:
<element name="config" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <interleave> <element name="image-directory"> </element> <element name="default-quality"> </element> <optional> <element name="use-sandbox"> </element> </optional> <optional> <element name="cache"> <element name="directory"> </element> <optional> <element name="path-encoding"> <choice> <value>flat</value>
<value>hierarchical</value>
</choice> </element> </optional> </element> </optional> </interleave> </element>
This is an example of configuration:
<config> <image-directory>file:C:/images</image-directory>
<default-quality>0.8</default-quality>
<cache> <directory>c:/oxf-image-cache</directory>
</cache> </config>
The image-directory element specifies the root of the directory
containing all the images. Note that a protocol must be specified. If the
directory is local, use the file protocol. You can also use the
http or oxf protocols.
The default-quality element specifies the JPEG quality factor
(between 0.0 and 1.0) to use when encoding JPEG images. If not specified, it
defaults to 0.5.
The use-sandbox element is optional. If set to false,
it disables checking that the images served are strictly under the
image-directory hierarchy. It defaults to true.
Warning
Disabling the sandbox can be a security hazard and should be used at your own
risk. If the image paths come from untrustworthy sources, for example the URL
entered by a user in a Web browser, you have to make sure that they do not
access protected content. Ideally, only paths coming from trusted sources, such
as your database or XML configuration files, should be used when the sandbox is
disabled.
The cache element is optional. If it is not specified, no caching
of transformations takes place. If it is specified, at least the
directory element is required. This element specifies the local
directory that contains the cached transformed images.
The cache element can contain an optional
path-encoding element specifying how cache file names are computed.
By default, the hierarchical format is used. In this case, the
cache builds a hierarchy of directories. A directory is created for each part
of the image path separated by either a "/", a "\" or a ":". The benefit of this
encoding is that in most cases, the cache directory hierarchy will mirror the
hierarchy of the image directory. If different images can be accessed with paths
differing only by the "/", a "\" or a ":", this scheme should not be used.
If the flat cache path encoding scheme is selected, the cache will
store all files directly under the cache directory. File names will be
URL-encoded. This guaranties the uniqueness of the file names in the cache.
1.2 Image Input
Once the Image Server is configured, its image input can receive
processing information. This input must follow this Relax NG schema:
<grammar datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <define name="image"> <element name="image"> <interleave> <element name="url"> </element> <optional> <element name="quality"> </element> </optional> <optional> <element name="use-cache"> </element> </optional> </interleave> <zeroOrMore> <choice> <element name="transform"> <attribute name="type"> </attribute> <optional> <element name="quality"> <choice> <value>high</value>
<value>low</value>
</choice> </element> </optional> <optional> <element name="scale-up"> </element> </optional> <choice> <ref name="width-height"/>
<ref name="max-size"/>
</choice> </element> <element name="transform"> <attribute name="type"> </attribute> <interleave> <optional> <element name="x"> <data type="nonNegativeInteger"/>
</element> </optional> <optional> <element name="y"> <data type="nonNegativeInteger"/>
</element> </optional> <optional> <element name="width"> <data type="positiveInteger"/>
</element> </optional> <optional> <element name="height"> <data type="positiveInteger"/>
</element> </optional> </interleave> </element> <element name="transform"> <attribute name="type"> </attribute> <oneOrMore> <choice> <element name="rect"> <attribute name="x"> <data type="nonNegativeInteger"/>
</attribute> <attribute name="y"> <data type="nonNegativeInteger"/>
</attribute> <attribute name="width"> <data type="positiveInteger"/>
</attribute> <attribute name="height"> <data type="positiveInteger"/>
</attribute> </element> <element name="fill"> <attribute name="x"> <data type="nonNegativeInteger"/>
</attribute> <attribute name="y"> <data type="nonNegativeInteger"/>
</attribute> <attribute name="width"> <data type="positiveInteger"/>
</attribute> <attribute name="height"> <data type="positiveInteger"/>
</attribute> </element> <element name="line"> <attribute name="x1"> </attribute> <attribute name="y1"> </attribute> <attribute name="x2"> </attribute> <attribute name="y2"> </attribute> </element> </choice> </oneOrMore> </element> </choice> </zeroOrMore> </element> </define> <define name="width-height"> <interleave> <element name="width"> <data type="positiveInteger"/>
</element> <element name="height"> <data type="positiveInteger"/>
</element> </interleave> </define> <define name="max-size"> <choice> <element name="max-size"> <data type="positiveInteger"/>
</element> <element name="max-width"> <data type="positiveInteger"/>
</element> <element name="max-height"> <data type="positiveInteger"/>
</element> </choice> </define> <define name="color"> <element name="color"> <choice> <attribute name="name"> <choice> <value>white</value>
<value>lightGray</value>
<value>gray</value>
<value>darkGray</value>
<value>black</value>
<value>red</value>
<value>pink</value>
<value>orange</value>
<value>yellow</value>
<value>green</value>
<value>magenta</value>
<value>cyan</value>
<value>blue</value>
</choice> </attribute> <attribute name="rgb"> <data type="string"> <param name="pattern">#[0-9A-Fa-f]{6}</param>
</data> </attribute> </choice> <optional> <attribute name="alpha"/>
</optional> </element> </define> </grammar>
The only required element is the url element. This is interpreted
as a URL relative to the image directory.
If use-sandbox is not set to false and the resulting
path is not in the sandbox, the processor returns a 404 error code
to the Web browser. If the resource does not exist, the processor also returns a
404 error code to the Web browser.
The cache can be disabled by setting the use-cache element to
false. It defaults to true.
If only the url element is set, no transformation takes place.
Zero or more transformations can be specified with the transform
element. Each transformation is identified by a type attribute
that identifies the type of transformation. Each transformation is performed
sequentially. If at least one transformation is specified, the
quality element can be used to override the configuration's default
JPEG quality setting.
1.2.1 Scaling
If the type attribute is set to scale, a scaling
operation is performed. It is possible to either specify a width and height
to scale the image to, or one of max-size,
max-width or max-height. If scale-up
is set to false, no scaling takes place if the specified
parameters produce an image larger than the original image. The
quality element can be set to low to use a faster
but lower-quality algorithm. The default is high.
1.2.2 Cropping
If the type attribute is set to crop, a cropping
operation is performed. All parameters are optional: x,
y, width and height. x
and y specify the top left corner of the cropping rectangle.
They default to 0. width and height specify the
size of the cropping rectangle. They default to covering the rest of the
image to the right and bottom sides.
Example of image input that will make sure that the maximum size
of the image is 100 pixels, without scaling up:
<image> <url>relative-path/to/my/image.jpg</url>
<transform type="scale"> <scale-up>false</scale-up>
<max-size>100</max-size>
</transform> </image>
Example of use of the Image Server processor:
<p:processor name="oxf:image-server" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="image"> <image> <url>relative-path/to/my/image.jpg</url>
<transform type="scale"> <scale-up>false</scale-up>
<max-size>100</max-size>
</transform> </image> </p:input> <p:input name="config"> <config> <image-directory>file:C:/images</image-directory>
<default-quality>0.8</default-quality>
<cache> <directory>c:/oxf-image-cache</directory>
</cache> </config> </p:input> </p:processor>
In this example, the image file that is accessed is:
C:/images/path/to/my/image.jpg. The cached image is stored under
c:/oxf-image-cache/path/to/my/.
The image input can be be generated dynamically, for example with
an XSLT transformation.
Warning
Image transformations can take a lot of memory depending on the size of the
source and transformed images. Be sure to set your memory settings accordingly.
Concurrent transformations can also yield to higher memory consumption.
1.3 Drawing
The Image Server also supports drawing basic shapes on an image. Empty and
filled rectangles, and lines are supported. Each shape may have a color
element.
<image> <url>ca-coast.jpg</url>
<quality>0.7</quality>
<use-cache>false</use-cache>
<rect x="10" y="10" height="100" width="100"> <color rgb="#ff0000" alpha="ff"/>
</rect> <fill x="100" y="100" height="200" width="200"> <color rgb="#00ff00" alpha="55"/>
</fill> <line x1="200" y1="200" x2="300" y2="300"> <color rgb="#0000ff" alpha="ff"/>
</line> </image>