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:
This is an example of configuration:
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:
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:
Example of use of the Image Server 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.
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.