15. imageToolkit

15. imageToolkit
	Chapter 6. Configuration elements

<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
  mimeTypes = non empty list of strings
  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, PNG, SVG, etc, 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.

Simple example:

<imageToolkit name="ImageMagick TIFF to JPEG">
  <description>Converts TIFF to JPEG.</description>

  <converter>
    <input extensions="tif tiff" mimeTypes="image/tiff" magicStrings="MM II"/>
    <output extensions="jpg jpeg"/>

    <shell command='convert %A "%I" "%O"' />
  </converter>
</imageToolkit>

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 Help → About dialog box.

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 input format (input child element) to one output format (output child element).

If you want an image to rendered in XXE's styled view, you must specify a converter supporting the input format of this image and one of the GIF, JPEG or PNG output formats. That is, specifying a converter supporting the input format of this image and, for example, the SVG output format is fine but then, this converter cannot be used to render the image in XXE's styled view.

Attribute extensions is required In the input and output elements and specifies the file name extensions of the supported image format. If several file name extensions are specified, these extensions must be strictly equivalent^[9] and the most commonly used one should be specified first.

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

"data:" URLs

Attribute mimeTypes contains one or more strictly equivalent MIME types. The most commonly used one should be specified first. Example: mimeTypes="application/x-tex text/x-tex".

Binary images

Attribute magicNumbers contains one or more 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="474946" is equivalent to magicStrings="GIF".

ASCII character "?" or 3F, its code in hexadecimal format, may be used as a wildcard matching any byte. Example: WebP “magic string” is "RIFF????WEBP".

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 one or more of QNames (Qualified Names).

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 converts XML images.

<imageToolkit name="Batik as an external SVG toolkit">
  <description>Converts SVG to PNG.</description>

  <converter>
    <input extensions="svg svgz" mimeTypes="image/svg+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: macOSX.
GenericUnix: A Unix which is not macOSX, typically Linux.
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.


	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\XMLEditor11\addon.

%c is the URL of the above directory. Example: file:///C:/Documents%20and%20Settings/john/Application%20 Data/XMLmind/XMLEditor11/addon.

Note that this URL does not end with a '/'.

The add-on called "A sample customize.xxe " (download and install it using Options → Install Add-ons) contains a number of useful imageToolkits from which the examples below are taken.

Example 6.3. Convert EPS and PDF to PNG using Ghostscript

<imageToolkit name="Ghostscript">
  <description>Converts EPS graphics to PNG or PDF.
  Converts PDF graphics to PNG.
  Important: requires Ghostscript 8+.</description>

  <converter>
    <input extensions="eps epsf epsi" magicStrings="%!PS"
           mimeTypes="application/postscript" />
    <output extensions="png"/>

    <shell command='gs -q -dBATCH -dNOPAUSE -sDEVICE=png16m
                    -r120 -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -dEPSCrop
                    %A "-sOutputFile=%O" "%I"'
           platform="Unix"/>

    <shell command='gswin32c -q -dBATCH -dNOPAUSE -sDEVICE=png16m
                    -r120 -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -dEPSCrop
                    %A "-sOutputFile=%O" "%I"'
           platform="Windows"/>
  </converter>

  <converter>
    <input extensions="pdf" magicStrings="%PDF" mimeTypes="application/pdf" />
    <output extensions="png"/>

    <shell command='gs -q -dBATCH -dNOPAUSE -sDEVICE=png16m
                    -r120 -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -dEPSCrop
                    %A "-sOutputFile=%O" "%I"'
           platform="Unix"/>

    <shell command='gswin32c -q -dBATCH -dNOPAUSE -sDEVICE=png16m
                    -r120 -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"

Example 6.4. Convert WMF and EMF pictures to SVG or PNG using Inkscape

<imageToolkit name="Inkscape WMF">
  <description>Converts WMF and EMF pictures to SVG or PNG.
  Important: requires Inkscape.</description>

  <converter>
    <input extensions="wmf" magicNumbers="D7CDC69A" mimeTypes="image/x-wmf" />
    <output extensions="svg" />

    <shell command='inkscape --export-type=svg -l -o "%O" "%I"' />
  </converter>

  <converter>
    <input extensions="wmf" magicNumbers="D7CDC69A" mimeTypes="image/x-wmf" />
    <output extensions="png" />

    <shell command='inkscape --export-type=png -d 96 -o "%O" "%I"' />
  </converter>

  <converter>
    <input extensions="emf" magicNumbers="01000000" mimeTypes="image/x-emf" />
    <output extensions="svg" />

    <shell command='inkscape --export-type=svg -l -o "%O" "%I"' />
  </converter>

  <converter>
    <input extensions="emf" magicNumbers="01000000" mimeTypes="image/x-emf" />
    <output extensions="png" />

    <shell command='inkscape --export-type=png -d 96 -o "%O" "%I"' />
  </converter>
</imageToolkit>

^[9]The following specification is incorrect extensions="jpg jpeg jp2" as "jp2" is used for JPEG 2000 images and not for JPEG images.


14. help		16. include