15. imageToolkit

<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 OptionsInstall 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 HelpPlug-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:

Binary images

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

Example: magicNumbers="5034 5035" is equivalent to magicStrings="P4 P5".

XML images (typically SVG images)

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="&lt;?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>

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:

Windows

Any version of Windows.

Mac

Mac OS X.

GenericUnix

A Unix which is not Mac OS X (Linux, Solaris, etc).

Unix

GenericUnix or Mac.

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

VariableDescription
%I

Input image file to be converted by the imageToolkit.

[Warning]

The file names contained in %I and %O often contain whitespaces. Do not forget to properly quote these variables in the command template.

%OOutput image file.
%AExtra 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"