1.3. Element convertImage

1.3. Element `convertImage`
	1. Reference

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^[1] 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/xmlmind.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.

Parameters and parameterGroups 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.

^[1]Image toolkit plug-ins are generally written in the Java™ programming language. However, the imageToolkit configuration element (see Section 15, “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.


1.2. Element `copyDocument`		1.4. Element `copyProcessResources`