10. imageToolkit
Prev | Chapter 7. Configuration elements | Next

## 10. 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 or the Jimi 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 `imageToolkit`s 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).

Example:

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

Variable | Description
--- | ---
`%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.
`%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\XMLEditor4\addon`. `%c` is the URL of the above directory. Example: `file:///C:/Documents%20and%20Settings/john/Application%20 Data/XMLmind/XMLEditor4/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"

Prev | Up | Next
9. help | Home | 11. include