1.3. Element `convertImage`
Prev | 1. Reference | Next

### 1.3. Element `convertImage`

    <convertImage
      from = Glob pattern
      skip = List of file name extensions
      to = Path
      format = List of file name extensions
      lenient = boolean : false
    >
      Content: [ parameter | parameterGroup ]*
    </convertImage>

    <parameter
      name = Non empty token
      url = boolean
    >
      Content: Parameter value
    </parameter>

    <parameterGroup
      name = Non empty token
    />

Converts between image formats using any of the image toolkit plug-ins[2] loaded by XXE.

Attributes:

from

  Specifies which image files are to be converted. If the value of this attribute is a directory, all the files contained in the directory are to be converted.

skip

  The value of this attribute is a list of file name extensions. All the images specified using attribute `from` having any of these extensions must not be converted.

  Example:

      <convertImage from="resources" skip="gif jpeg jpg png"
                    to="resources" format="png" />

  The following case is, of course, not considered to be an error: after evaluating attributes `from` and `skip`, no image at all needs to be converted. (In fact, this is a very common case.)

to

  Specifies the output image file. May be a file name or a directory name.

  If a directory name is used, the `format` attribute must be specified too (because without a file base name, there is no other way to know the target image format).

  If after evaluating attributes `from` and `skip`, several images needs to be converted, the value of the `to` attribute must be a directory name.

  Examples:

      <convertImage from="resources/logo.tiff" to="resources/pixware.jpeg" />

      <convertImage from="resources/*.svg" to="resources" format="png" />

format

  The value of this attribute is a list of file name extensions. It specifies all the possible output formats in the order of preference. Ignored unless attribute `to` specifies a directory name.

  Example: the document needs to be converted to PostScript. Converting images to EPS (Encapsulated PostScript) is tried before trying to convert images to PNG.

      <convertImage from="raw" to="resources" format="eps png" />

lenient

  Unless this attribute is specified with value `true`, a error (a crash of the image toolkit or simply the fact that the image converter needed is not available) during the image conversion step is fatal to the whole process command.

`Parameter`s and `parameterGroup`s may be used to fine tune the conversion. Example:

    <convertImage from="raw/*.svg" to="resources" format="jpeg">
      <parameter name="quality">0.95</parameter>
    </convertImage>

Which parameters are supported depend on the image toolkit used for the conversion. The parameters supported by the built-in Java image toolkit are documented below. The documentation of the parameters supported by other image toolkits is displayed in the documentation pane of the dialog box of Options → Install Add-ons.

Which image toolkit is used for the conversion is often obvious. In the above example, no image toolkit other than Batik can convert SVG graphics to PNG.

When several image toolkits can do the same job, suffice to remember that they are tried in the order given in the dialog box displayed by menu entry Help → Plug-ins.

#### 1.3.1. Parameters supported by the built-in Java image toolkit

Parameter | Applies to output format | Value | Description
--- | --- | --- | ---
quality | JPEG | Number between 0 and 1. | Controls the tradeoff between file size and image quality .
progressive | PNG, JPEG | true | false | If true, the toolkit is to write the image in a progressive mode such that the stream will contain a series of scans of increasing quality.

[2] Image toolkit plug-ins are generally written in the Java™ programming language. However, the `imageToolkit` configuration element (see Section 12, “imageToolkit” in XMLmind XML Editor - Configuration and Deployment) may be used 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.

Prev | Up | Next
1.2. Element `copyDocument` | Home | 1.4. Element `copyProcessResources`