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.
Image Server
- 1. Purpose
- 2. Configuration
- 3. Image Input
- 4. Drawing
1. Purpose
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.
2. Configuration
The config input must follow this Relax NG schema:
<element name="config" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes" xmlns="http://relaxng.org/ns/structure/1.0"><interleave><element name="image-directory"><text/></element><element name="default-quality"><data type="float"/></element><optional><element name="use-sandbox"><data type="boolean"/></element></optional><optional><element name="cache"><element name="directory"><text/></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>
| Element | Purpose | Format | Default |
|---|---|---|---|
image-directory
|
Specifies the root of the directory containing all the images. |
URL with a protocol specified. If the directory is local, use the
file protocol. You can also use the http or
oxf protocols.
|
None. |
default-quality
|
Specifies the JPEG quality factor to use when encoding JPEG images.. | Number between 0.0 and 1.0. | 0.5 |
use-sandbox
|
If set to Warning
|
true or false.
|
true
|
cache
|
Optional element. If it is not specified, no caching of transformations
takes place. If it is specified, at least the directory child
element is required.
|
N/A | None. |
cache/directory
|
Specifies the cache directory. | Path specifying the local filesystem directory that contains the cached transformed images. | None. |
cache/path-encoding
|
Specifies how cache file names are computed. 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 |
hierarchical or flat.
|
hierarchical
|
3. 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" xmlns="http://relaxng.org/ns/structure/1.0"><start><ref name="image"/></start><define name="image"><element name="image"><interleave><element name="url"><text/></element><optional><element name="quality"><data type="float"/></element></optional><optional><element name="use-cache"><data type="boolean"/></element></optional></interleave><zeroOrMore><choice><element name="transform"><attribute name="type"><value>scale</value></attribute><optional><element name="quality"><choice><value>high</value><value>low</value></choice></element></optional><optional><element name="scale-up"><data type="boolean"/></element></optional><choice><ref name="width-height"/><ref name="max-size"/></choice></element><element name="transform"><attribute name="type"><value>crop</value></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"><value>draw</value></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><optional><ref name="color"/></optional></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><optional><ref name="color"/></optional></element><element name="line"><attribute name="x1"><data type="int"/></attribute><attribute name="y1"><data type="int"/></attribute><attribute name="x2"><data type="int"/></attribute><attribute name="y2"><data type="int"/></attribute><optional><ref name="color"/></optional></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.
3.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.
3.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"><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.
4. 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>