SVG Rasterizer

Batik’s SVG Rasterizer is an application you can use to convert one or more SVG files into raster file format. Doing so allows you to use SVG to describe images that can be viewed without requiring SVG rendering capabilities. You can use the rasterizer two ways: as a command-line application or as an Ant build task.

Command Line

To use the rasterizer as a command-line tool, you need to execute the following command:

java –jar batik-rasterizer.jar [options] [files]

This assumes that the batik-rasterizer.jar is in the current directory, but you can specify the path to the jar file if necessary. The possible options for the rasterizer are

• -d <dir | file>—Output directory, which can be an output file if there is a single input file.

• -m <mimeType>—Output mime type: image/png, image/jpeg, image/tiff, or application/pdf (requires FOP to be installed).

• -w <width>—Output width (floating point).

• -h <height>—Output height (floating point).

• -maxw <width>—Maximum output width (floating point).

• -maxh <height>—Maximum output height (floating point).

• -a <x,y,w,h>—Output area: x and y followed by w(idth) and h(eight).

• -bg <a.r.g.b>—Output color (a, r, g, and b are integer values).

• -cssMedia <media>—Convert the SVG file for this CSS media type.

• -cssAlternate <alternate>—Alternate CSS stylesheet URI to use when converting SVG documents.

• -cssUser <userStylesheet>—Apply the CSS stylesheet specified by this URI in addition to any other stylesheets.

• -lang <userLanguage>—The language to use when converting SVG documents.

• -q <quality>—For image/jpeg only: the JPEG quality.

• -dpi <resolution>—Output resolution.

• -validate—Validate the SVG documents against the SVG DTD.

• -onload—Execute the onload event handler before rasterizing.

• -scriptSecurityOff—Don’t do any security checks on scripts that run due to execution of the onload event handler.

• -scripts <listOfAllowedScriptTypes>—List script types that should not be loaded. The list of valid types is the set of valid values for the <script> tag’s type attribute.

ANT Task

Using the Batik rasterizer as an Ant task is less straightforward than it should be, because the ANT task doesn’t come pre-built in the Batik binary distribution. Here are the steps you need to go through to build the rasterizer task:

1. Download the Batik source distribution and unpack it.

2. Go to the directory xml-batik/contrib/rasterizertask.

3. Make sure batik-rasterizer.jar, batik-transcoder.jar, and batik-util.jar are on the classpath.

4. Type "ant-jar".

5. RasterizerTask.jar will be in xml-batik/contrib/rasterizertask/build/lib.

Once you’ve built the rasterizer task, you need to set up the classpath for Ant with both RasterizerTask.jar and batik-rasterizer.jar. Here’s a sample Ant build file that uses the rasterizer.

The first thing that you need is to define the rasterizer task:

  1: <project name="Batik Rasterizer Task" default="rasterize"   2:          basedir=".">   3:  <taskdef name="rasterize"    4: classname="org.apache.tools.ant.taskdefs.optional.RasterizerTask"   5:   />

You want JPEG files:

  6:  <target name="rasterize">   7:   <rasterize    8:    result="image/jpeg"

They’re stored in /tmp:

  9:    destdir="/tmp">

The input to the rasterizer is a fileset that includes all files in /tmp that end with .svg:

 10:    <fileset dir="/tmp">  11:     <include name="**/*.svg" />  12:    </fileset>  13:   </rasterize>  14:  </target>  15: </project>

The rasterizer task takes most of the same options as the command-line task, but they’re specified using attributes of the rasterize task:

• result—The result image type. Must be image/jpeg, image/png, image/tiff, or application/pdf (FOP must be installed).

• height—Height of the result image in pixels. The height will be calculated if this attribute isn’t set. The rasterizer preserves the aspect ratio of the SVG file no matter what.

• width—Width of the result image in pixels. The width will be calculated if this attribute isn’t set. The rasterizer preserves the aspect ration of the SVG file no matter what.

• maxheight—Maximum height of the image in pixels. The image can’t be taller than this value.

• maxwidth—Maximum width of the image in pixels. The image can’t be wider than this value.

• quality—For JPEG images only. A quality value between 0 an 1, where larger numbers mean better quality.

• area—An area within the SVG file to be rasterized. The area is specified via "x, y, w, h", where x and y are the coordinates of the upper-left corner of the area, and w and h are the width and height.

• bg—The background color of the result. You can specify three or four values, all of which are integers between 0 and 255 and separated by commas. If you specify four values, they’e alpha channel, red, green, and blue. If you specify three values, they’re red, green, and blue (the alpha channel is set to 255).

• media—CSS media type used to select a CSS stylesheet. The default value is screen.

• dpi—Resolution for the result image. The default value is 96.

• lang—Language used to select language-specific areas of the SVG file during rasterization. Valid values are defined in RFC 3066. The default value is en.

• src—Name of a single input file. Must be used with dest.

• dest—Name of a single output file, including the directory if desired. Must be used with src.

• srcdir—Name of the input directory. Optional if you use a <fileset>; otherwise must be used if src isn’t used.

• destdir—Name of the output directory. Use this with srcdir or an embedded <fileset>.

• classname—Java class name of the XML parser being used to parse the SVG. You can also specify "jaxp" to indicate any JAXP-compatible parser in the classpath. The default value is org.apache.xerces.parsers.SAXParser.

As you’ve seen in the example, the rasterizer task can use nested Ant <fileset> elements to specify the set of SVG files to rasterize. This gives you the ability to specify multiple files and include or exclude specific files.