<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)
/>

The 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 Options → Install Add-ons) contains three useful imageToolkits from which the examples used here are taken.

An 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 Help → Plug-ins.

An 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.

<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" &gt; "%O"' />
  </converter>
</imageToolkit>

In the input and output elements, attribute extensions is required and specifies the file name extensions of the supported image formats. For the output elements, extensions other than png, gif, jpg and jpeg (case-insensitive) are currently ignored.

The input elements have means other than file name extensions to detect the format of images embedded in the XML document:

A 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).

If the platform attribute is not specified, the shell command is executed whatever is the platform running XXE.

If the platform attribute is specified, the shell command is executed only if the platform running XXE matches the value of this attribute:

The command template must contain at least the %I and %O variables but may also contain the following variables:

Variable	Description
%I	Input image file to be converted by the imageToolkit. The file names contained in %I and %O often contain whitespaces. Do not forget to properly quote these variables in the command template.
%O	Output image file.
%A	Extra command line arguments taken from the convertImage/parameter elements of a process command (see Chapter 5, Process commands in XMLmind XML Editor - Commands). See example below.
%S	%S is the native path component separator of the platform. Example: '\' on Windows.
%C, %c	%C is the name of the directory containing the XXE configuration file from which the imageToolkit element has been loaded. Example: C:\Documents and Settings\john\Application Data\XMLmind\XMLEditor10\addon. %c is the URL of the above directory. Example: file:///C:/Documents%20and%20Settings/john/Application%20 Data/XMLmind/XMLEditor10/addon. Note that this URL does not end with a '/'.

Example:

<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>

About the %A variable. Let's suppose a process command contains the following convertImage element:

<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"