<imageToolkit name = non empty token > Content: [ description ]? [ converter ]+ </imageToolkit> <description> Content: string </description> <converter> Content: input output [ shell ]+ </converter> <input extensions = non empty list of file name extensions magicStrings = non empty list of strings magicNumbers = non empty list of hexBinaries rootNames = non empty list of QNames /> <output extensions = non empty list of file name extensions /> <shell command = Shell command platform = (Unix | Windows | Mac | GenericUnix) />
imageToolkit configuration element allows to turn any command line tool generating GIF, JPEG or PNG images (example: ImageMagick's convert) to a fully functional image toolkit plug-in for XXE. Without this mechanism, image toolkit plug-ins such as the Batik plug-in need to be written in the Java™ programming language.
The add-on called "A sample customize.xxe " (download and install it using
imageToolkits from which the examples used here are taken.
imageToolkit has a required
name attribute which is used to register the plug-in and an optional
description child element which is displayed in the dialog box opened by menu entry → .
imageToolkit contains one or more
converter child elements. A converter mainly contains a command template (
shell child element) which can be used to convert from one or more input formats (
input child element) to one or more output formats (
output child element).
The following example is not useful because PNM support is provided by the plug-in called "JAI Image I/O Tools". However, this example shows how to declare a simple
<imageToolkit name="netpbm"> <description>Converts PBM, PGM, PPM images to PNG.</description> <converter> <input extensions="pnm pbm pgm ppm" magicStrings="P4 P5 P6 P1 P2 P3"/> <output extensions="png"/> <shell command='pnmtopng %A "%I" > "%O"' /> </converter> </imageToolkit>
output elements, attribute
extensions is required and specifies the file name extensions of the supported image formats. For the
output elements, extensions other than
jpeg (case-insensitive) are currently ignored.
input elements have means other than file name extensions to detect the format of images embedded in the XML document:
magicNumbers contains a list of numbers in hexadecimal format. These numbers are possible values for the first bytes found in the image file.
These first bytes are often ASCII characters (even for binary images such as PNG or TIFF), that's why it is often more convenient to use attribute
magicStrings rather than attribute
magicNumbers="5034 5035" is equivalent to
The format of an XML image embedded in an XML document can be detected by examining the name of its root element. Attribute
rootNames contains a list of such
QNames (qualified names: data type which is part of the W3C XML Schema standard).
The following example is not useful because Batik is available as a plug-in written in Java™. However, this example shows how to declare an
imageToolkit which handles XML images.
<imageToolkit name="Batik as an external SVG toolkit"> <description>Converts SVG to PNG.</description> <converter> <input extensions="svg svgz" magicStrings="<?xml" rootNames="svg:svg" xmlns:svg="http://www.w3.org/2000/svg" /> <output extensions="png"/> <shell command='java -jar /opt/batik/batik-rasterizer.jar %A "%I" -d "%O"' /> </converter> </imageToolkit>
converter element contains one or more
shell elements. Each
shell element contains a command template usable on a given platform. That is, a single shell command is executed when the
imageToolkit is used to convert between image formats.
After substituting the variables contained in the template (see below), the command is executed the using the native shell of the machine running XXE: cmd.exe on Windows and /bin/sh on Unix (Mac OS X is considered to be a Unix platform).
platform attribute is not specified, the shell command is executed whatever is the platform running XXE.
platform attribute is specified, the shell command is executed only if the platform running XXE matches the value of this attribute:
Any version of Windows.
Mac OS X.
A Unix which is not Mac OS X (Linux, Solaris, etc).
GenericUnix or Mac.
command template must contain at least the
%O variables but may also contain the following variables:
Input image file to be converted by the imageToolkit.
The file names contained in
|Output image file.|
|Extra command line arguments taken from the |
Note that this URL does not end with a '
<imageToolkit name="Ghostscript"> <description>Converts EPS and PDF graphics to PNG. Important: requires Ghostscript 8+.</description> <converter> <input extensions="eps epsf ps pdf" magicStrings="%!PS %PDF"/> <output extensions="png"/> <shell command='gs -q -dBATCH -dNOPAUSE -sDEVICE=png16m -r96 -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -dEPSCrop %A "-sOutputFile=%O" "%I"' platform="Unix"/> <shell command='gswin32c -q -dBATCH -dNOPAUSE -sDEVICE=png16m -r96 -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -dEPSCrop %A "-sOutputFile=%O" "%I"' platform="Windows"/> </converter> </imageToolkit>
%A variable. Let's suppose a
process command contains the following
<convertImage from="raw/*.eps" to="resources" format="png"> <parameter name="-r">120</parameter> <parameter name="-dDOINTERPOLATE" /> </convertImage>
When the above
convertImage is executed, the command template is equivalent to:
gs -q -dBATCH -dNOPAUSE -sDEVICE=png16m \ -r96 -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -dEPSCrop \ -r "120" -dDOINTERPOLATE "-sOutputFile=%O" "%I"