### Custom image converters

Image converters are used to convert images having a format not supported by Web browsers (TIFF, WMF, EMF, etc) to a format supported by Web browsers (SVG, PNG, JPEG).

Image converters are specified by interface `com.xmlmind.w2x.docx.image.ImageConverterFactory`. XMLmind Word To XML ships with 4 classes implementing this interface:

`com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl`
  Image converter factory used to convert TIFF images to PNG or JPEG.
`com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory`
  Image converter factory used to convert WMF/EMF graphics to SVG.
  `WMFConverterFactory` has one parameter called `maxsize`. Its value is an integer expressed in bytes. The default value of parameter `maxsize` is 4194304.
  For some WMF/EMF input files, `WMFConverterFactory` may generate very large or incorrect SVG output files. This generally depends on the software which was used to create these WMF/EMF files. Parameter `maxsize 4194304` limits the size of the SVG files `WMFConverterFactory` can create to`` 4194304 bytes.
  See below how to simply and quickly get rid of `WMFConverterFactory` in order to force the use of “more stable” `EMF2PNG` on Windows.
`com.xmlmind.w2x_ext.emf2png.EMF2PNG`
  This image converter factory is available only on Windows. It leverages Windows own GDI+ to convert EMF (in fact, Windows metafiles of any kind, including WMF) to PNG.
  Note that, unlike above `WMFConverterFactory` which converts WMF/EMF (Windows vector graphics formats) to SVG (standard vector graphics format), `EMF2PNG` converts a vector graphics format to a raster image format. However, having `EMF2PNG` is useful because it’s quick and reliable and on Windows, it will be automatically used as a fallback when `WMFConverterFactory` fails to convert an WMF/EMF file to SVG.
  `EMF2PNG` has one parameter called `resolution`. Its value is a real number expressed in Dot Per Inch (DPI). The default value of parameter `resolution` is `-300`.
  The `resolution` parameter specifies the resolution of the output PNG file. 0 means: same resolution as the one found input EMF/WMF file; a positive number means: use this value to override the resolution found in the input EMF/WMF file; a negative number means: use specified absolute value but only if this absolute value is greater than the resolution found in the input EMF/WMF file.
`com.xmlmind.w2x.docx.image.ExternalImageConverter`
  This image converter factory executes an external program to perform the conversion. See Specifying an external image converter.

If you want w2x to support more image formats, you’ll have to create your own `ImageConverterFactory` and register it with w2x using method `ImageConverterFactories.register`.

About thread-safety

A single instance of a class implementing `ImageConverterFactory` is used by all instances of `com.xmlmind.w2x.processor.Processor`. This implies that an implementation of `ImageConverterFactory` must be thread-safe.

See reference of package com.xmlmind.w2x.docx.image.

#### Specifying an external image converter

Examples of `W2X_IMAGE_CONVERSIONS` specifications (see Controlling how image files found in the input DOCX file are converted to standard formats):

- Convert EMF/WMF to SVG using OpenOffice/LibreOffice:

      .emf.svg.wmf.svg soffice --headless --convert-to svg -–outdir %~po %i

  Or equivalently using unoconv:

      .emf.svg.wmf.svg unoconv -f svg -o %o %i

- Convert EMF to SVG using Inkscape:

      .emf.svg inkscape -l -o %o %i

The command executed by an external image converter may contain the following variables:

Variable | Definition
`%I` | Absolute path of the input image file.
`%O` | Absolute path of the output image file.
`%i` | Same as `%I` but quoted, that is, equivalent to `“%I”`.
`%o` | Same as `%O` but quoted, that is, equivalent to `“%O”`.
`%S` | File separator: “`\`” on Windows, “`/`” on Mac/Linux.

The following modifiers may be applied to the `%I`, `%O`, `%i`, `%o` variables:

Modifier | Definition
`~p` | Absolute path of the parent directory of the file. For example, if `%I` is “`C:\temp\doc_files\logo.wmf`”, then `%~pI` is “`C:\temp\doc_files`”.
`~n` | Basename of the file. For example, if `%I` is “`C:\temp\doc_files\logo.wmf`”, then `%~nI` is “`logo.wmf`”.
`~r` | Basename of the file without any extension. For example, if `%I` is “`C:\temp\doc_files\logo.wmf`”, then `%~rI` is “`logo`”.
`~e` | Extension of the file. For example, if `%I` is “`C:\temp\doc_files\logo.wmf`”, then `%~eI` is “`wmf`”.

Also note that “`%%`” may be used to escape character “`%`”. More generally, just like in an URL, an `%HH` UTF-8 sequence may be used to escape any character. Example: “`%3B`” is “`;`” (semi colon), “`%C3%A9`” is “`é`” (“e” with acute accent).

#### Controlling how image files found in the input DOCX file are converted to standard formats

Conversion of images found in the DOCX file (TIFF, WMF, EMF, etc) to standard formats (SVG, PNG, JPEG) may be controlled using environment variable (or Java™ property) `W2X_IMAGE_CONVERSIONS`.

The default value of this variable is (all specifications on a single line):

    .emf.svg.wmf.svg¬
     java:com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory maxsize 4194304;
    .tiff.png java:com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl

On Windows, the default value of `W2X_IMAGE_CONVERSIONS` is (all specifications on a single line):

    .emf.svg.wmf.svg¬
     java:com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory maxsize 4194304;
    .emf.png.wmf.png java:com.xmlmind.w2x_ext.emf2png.EMF2PNG resolution -300;
    .tiff.png java:com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl

The syntax of `W2X_IMAGE_CONVERSIONS` is:

    specifications -> “-” | specification_list

    specification_list -> specification [ “;” specification ]+

    specification -> “+” | image_conversion

    image_conversion -> extensions S ( java_image_conversion | external_image_conversion )

    extensions -> [ “.” input_file_extension “.” output_file_extension ]+

    java_image_conversion -> “java:” fully_qualified_java_class_name parameters

    parameters -> [ S parameter_name S possibly_quoted_parameter_value ]*

    external_image_conversion -> command_line

About this syntax:

- “`-`” means: no specifications; hence no image conversions at all.
- “`+`” means: insert default value of `W2X_IMAGE_CONVERSIONS` at this point. Example:

      set W2X_IMAGE_CONVERSIONS=.emf.svg inkscape -l -o %o %i;+

  where default value of `W2X_IMAGE_CONVERSIONS` is (on Windows):

      .emf.svg.wmf.svg¬
       java:com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory maxsize 4194304;
      .emf.png.wmf.png java:com.xmlmind.w2x_ext.emf2png.EMF2PNG resolution -300;
      .tiff.png java:com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl

- Note that the image conversion specifications are considered in the order of their declarations in variable `W2X_IMAGE_CONVERSIONS`. In the case of the above example, it’s custom “`inkscape -l -o %o %i`” which is used to convert EMF to SVG and not the following converter in the list which is “`java:com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory maxsize 4194304`”.

  However if an image converter fails (e.g. if `inkscape` fails) then the following converters (e.g. `WMFConverterFactory` and then `EMF2PNG`) found in the `W2X_IMAGE_CONVERSIONS` list will be automatically considered.

- A simple way to change the default value of `W2X_IMAGE_CONVERSIONS` is to delete or rename the `.jar` file of an image converter. For example, if you delete or rename `W2X_INSTALL_DIR\lib\wmf_converter.jar` (which contains `WMFConverterFactory`) on Windows in order to force the use of “more stable” `EMF2PNG`, the default value of `W2X_IMAGE_CONVERSIONS` becomes automatically:

      .emf.png.wmf.png java:com.xmlmind.w2x_ext.emf2png.EMF2PNG resolution -300;
      .tiff.png java:com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl