extract-images

Extracts a specified image resolution from an image container. It can also transform SVG and MathML images to PNG for Apache FOP.

In the DITA CMS, multi-resolution images are assigned a collective ID and stored in a zip file with the extension .image. This .image container file is specific to the DITA CMS and cannot be sent directly to the transformation scenario. The extract-images task lets you extract from this container the image resolution that you need so that it can be processed by the transformation scenario.

This task processes all the image containers in a specified folder, as follows:
  • It makes a backup copy of each image container (that is, it copies <id>.image to <id>.zip)
  • It extracts from each container the image with the specified resolution (for example, HiRes, LowRes, etc.)
  • It replaces the container file with the extracted image
For example, consider the lar1369834664934.image container file; it includes the following images:
  • lar1369834664934_MedRes.png
  • lar1369834664934_HiRes.png

After calling the extract-images task and specifying the HiRes resolution, the lar1369834664934_HiRes.png file will be renamed lar1369834664934.image.

If the image container does not include an image with the specified resolution, the default resolution is used instead.

Converting SVG and MathML images to PNG (for FOP)

The Apache FOP formatter does not support SVG and MathML images. You can use the extract-images task to convert SVG and MathML images to PNG so that they can be processed by the FOP transformation scenarios.
Note: This step is only required for Apache FOP.

Syntax

<extract-images 
   indir="directory" 
   type="image_type" 
   extension=".image"/>

Parameters

Attribute Description Type Required
indir Input directory that contains the images to process. String Yes
type Type of images to process (for example, HiRes, MedRes, LowRes, etc.). Enter a resolution specified in multiimage.xml. String Yes
extension Extension of the image container file. String No. Default is ".image".

Contained elements

The extract-images task can also contain the following elements to convert MathML and SVG files to PNG before sending them to an FOP transformation scenario:

Element Attribute Description Type Required
<equation>        
  mime MIME type of the image to transform; valid values are:
  • application/mathml+xml
  • image/svg+xml
String Yes
  ratio Ratio used when converting the image. Enter a value between 0 and 1.
Note: Applies to MathML images only. This attribute is ignored for SVG.
String No. Default is "1".
One or more <param> elements   The <equation> element can include one or more <param> elements, which provide a set of name-value pairs to specify parameters for the conversion.    
  name For MathML, the parameter specified can be one of the parameters supported by the Jeuclid library, as follows:

http://jeuclid.sourceforge.net/jeuclid-core/ apidocs/net/sourceforge/jeuclid/context/ Parameter.html

For example:
<param name="DEBUG" value="0"/>
For SVG, the following values are supported:
  • KEY_WIDTH: Width of the image after the conversion
  • KEY_HEIGHT: Height of the image after the conversion
   
  value As appropriate for the parameter name.    

Example

For example, the following code extracts all the high resolution images from the image containers found in the input directory specified.

<extract-images 
   indir="${outgen.job.source.dir}" 
   type="HiRes" 
   extension=".image"/>

The following code shows the extract_HiRes_images target, which uses the extract-images task with the <equation> element. This target checks if the PDF formatter is fop; in this case, it extracts all the HiRes images and converts the MathML and SVG files to PNG files. For all other formatters, it simply extracts all the HiRes images.

<target name="extract_HiRes_images">

   <!-- Will process the multiple images container. -->
   <!-- If the image to extract is a SVG or MathML file
	   and the formatter is FOP, we need to generate a raster version
	   of the SVG or MathML otherwise FOP will throw errors for these images -->
   <if>
      <equals arg1="${outgen.job.default.pdf.formatter}" arg2="fop"/>
         <then>
            <extract-images indir="${outgen.job.source.dir}" type="HiRes" extension=".image">
               <equation mime="application/mathml+xml" ratio="1">
                  <param name="debug" value="0"/>
               </equation>
               <equation mime="image/svg+xml">
                  <param name="KEY_WIDTH" value="400"/>
               </equation>
            </extract-images>
      </then>
      <else>
         <extract-images indir="${outgen.job.source.dir}" type="HiRes" extension=".image"/>
      </else>
   </if>
</target>