apache > xml > graphics
Apache Batik
 

SVG Rasterizer

This page describes the features of the SVG Rasterizer utility that comes with the Batik distribution. The SVG Rasterizer is a utility that can convert SVG files to a raster format. The tool can convert individual files or sets of files, making it easy to convert entire directories of SVG files. The provided formats are JPEG, PNG and TIFF, however the design allows new formats to be added easily. In addition, the rasterizer can (despite its name) transcode to PDF.

Downloading the rasterizer

Refer to the install page and the download area to find out what to download and how to install it. Remember that you can get either the source or binary distribution.

Rasterizing one or several SVG files

The method for starting the rasterizer depends on the distribution of Batik that you chose to download. The following describes how to start the viewer for each distribution.

Using the binary distribution

If you downloaded the binary distribution of Batik, you should have a file called batik-1.6.zip (or similar), and, after expanding that file, a jar file called batik-rasterizer.jar. To start the rasterizer, open a console, go to the directory where you expanded the distribution (and where batik-rasterizer.jar is located) and simply type the following at the command prompt: 

java -jar batik-rasterizer.jar FILES

For example, if you type: 

java -jar batik-rasterizer.jar samples/batikFX.svg

you will see the following printout: 

Converting file: samples/BatikFX.svg to samples/BatikFX.png

Once the conversion is complete, you will find a batikFX.png file in the samples directory.

You can pass options on the command line: 

java -jar batik-rasterizer.jar [OPTIONS] FILES

where, as options:

-d dir|file

specifies the output directory, or the output file if there is only a single input file,

-m mime-type

specifies the output MIME type, which must be one of image/png, image/jpeg, image/tiff or application/pdf,

-w width

specifies the output width as a floating point value,

-h height

specifies the output height as a floating point value,

-maxw width

specifies the maximum output width as a floating point value,

-maxh height

specifies the maximum output height as a floating point value,

-a x,y,width,height

specifies the area of interest (as floating point values) of the SVG file to rasterize (and if not specified, will be determined by the width/height/viewBox attributes if specified in the document, and be 0,0,400,400 otherwise),

-bg alpha.red.green.blue

specifies the background fill color as an ARGB quadruple, where each component is an integer in the range 0—255,

-cssMedia media

specifies the CSS media type used for matching CSS rules,

-cssAlternate file|uri

specifies the CSS alternate stylesheet to use,

-cssUser file|uri

specifies the CSS user stylesheet to use in addition to any other referenced or embedded stylesheets,

-lang language-code

specifies the RFC 3066 language code to use,

-q quality

specifies the quality of the output image, as a floating point number in the range 0 < quality < 1 when generating JPEG images,

-dpi resolution

specifies the resolution of the output image in dots per inch,

-validate

specifies that the source SVG files must be validated against their DTDs,

-onload

specifies that the SVG files should be rasterized after dispatching the SVG load event,

-scriptSecurityOff

specifies that any security checks on the scripts running as a result of dispatching the SVG load event will be bypassed, and

-scripts allowed-script-types

specifies a list of script types (i.e., values for the type attribute on script elements) that should be loaded.

For example: 

java -jar batik-rasterizer.jar -d myDir -m image/jpeg samples/*.svg

will generate JPEG images for all the SVG files found in the samples directory.

Using the source distribution

If you downloaded the source distribution of Batik, you got a zip or tar file that expanded into a directory called xml-batik or batik-version. In that directory, you can find build scripts for the platform you are running on. For example, there is a build.bat script for users of the Windows platform and there is a build.sh script for UNIX users.

To start the rasterizer you should:

  • Make sure that your JAVA_HOME environment variable is set to your JDK installation directory.
  • Open a command line window and go to the xml-batik or batik-version directory where the Batik distribution was expanded.

  • For windows, type the following at the command prompt:

    build svgrasterizer

    and for Unix:

    ./build.sh svgrasterizer

    This will print out a help message for the rasterizer.

You can pass options to the rasterizer as follows, for Windows: 

build svgrasterizer [OPTIONS] FILES

and for Unix: 

./build.sh svgrasterizer [OPTIONS] FILES

Refer to “Using the binary distribution” for an explanation of the options.

Rasterizer Ant task

The Rasterizer task is an Ant version of the rasterizer utility. It fulfills the same basic purpose as the utility but has a different syntax and a slightly different set of features.

The task is able to produce four raster formats: PNG, JPEG, TIFF and PDF.

Using the rasterizer task

The first thing to do is to compile rasterizer task classes. Download the source distribution of Batik and see the README file in the contrib/rasterizertask directory for more instructions. The build procedure works the same way as when building Batik itself.

After building, ensure that the generated batik-rasterizer.jar and the classes (or jar file) of the rasterizer task are in your CLASSPATH.

Next you have to define the task in your Ant project. To do this, add the following line either after the project start tag or after the target start tag in the target you are using the rasterizer task: 

  <taskdef name="rasterize" 
           classname="org.apache.tools.ant.taskdefs.optional.RasterizerTask"/>

Now you can use the rasterizer task in your project. See the parameters section for an explanation of the available parameters or the examples section to see few usage examples.

Parameters of the Ant task

The following table lists the attributes that may be specified on the rasterize task element.

Attribute Description Required
result Sets the type of the result image. Only one of the following values must be used: image/png, image/jpeg, image/tiff and application/pdf. The value must be in lowercase letters. Yes
height Sets the height of the result image in pixels. The task calculates the height from the SVG file if this parameter has not been set. The rasterizer keeps the aspect ratio of the SVG file even if the both height and width have been set. No
width Sets the width of the result image in pixels. The task calculates the width from the SVG file if this parameter has not been set. The rasterizer keeps the aspect ratio of the SVG file even if the both height and width have been set. No
maxheight Sets the maximum height of the result image in pixels. The image won’t be higher than defined in this parameter, regardless of the size set in the image itself or in other parameters. This is a floating point value. No
maxwidth Sets the maximum width of the result image in pixels. The image won’t be wider than defined in this parameter, regardless of the size set in the image itself or in other parameters. This is a floating point value. No
quality Sets the quality of the produced image. The value must be greater than 0 but smaller than 1, larger numbers meaning higher quality. The quality value is used only with JPEG images. The default quality value is 0.99. No
area Defines the area in the SVG file which will be rasterized. Parts outside this area are discarded and don’t show in the result image. The area attribute value has four integers separated by commas. The first two integers set the x and y coordinates of the upper left corner of the area, respectively. The last two integers set the width and height of the area, respectively. For example, 10, 20, 100, 200 sets the rectangular area from point 10, 10 to point 110, 220. The specified area is applied to all images if more than one file is rasterized during one task. No
bg Sets the background color of the result image. The bg attribute value is either three or four integers separated with commas. The four values are alpha channel, red, green, and blue, respectively. If only three values are given, then the values are red, green, and blue and the alpha channel is automatically set to 255 (opaque). All values have to between 0 and 255. The default value is none which means that background is transparent and not filled with any color. No
media CSS media type that is used to select a CSS stylesheet. The selected stylesheet is then used to rasterize the SVG files. Only the visual media group is supported (see the CSS2 specification for more information about media groups). The default value is screen. No
dpi Resolution for the result image. The attribute value is used to compute the “pixel to millimeter” ratio used when processing SVG files. The default value is 96. No
lang Language which is used select language specific areas from the SVG file during the rasterizing process. The valid values are defined in RFC3066. The default value is en. No
src Name of a one input file. Use this parameter to convert just one file whose name and location are known. The dest parameter must also be given. One of the following is required: src attribute, srcdir attribute or fileset element(s).
dest Name of a one output file. Used this with src parameter only. The output directory is created if it doesn’t exist. Required if src is used.
srcdir Name of the input directory. srcdir and fileset elements can be combined and srcdir can be omitted if there is at least one fileset child element. srcdir file selection can be controlled with include, exclude, etc. child elements. Note that without control parameters the task tries to rasterize all files in the given directory. One of the following is required: src attribute, srcdir attribute or fileset element(s).
destdir Name of an output directory. Use this with the srcdir attribute or fileset elements. The task generates the names of the output images by changing the suffix of the input file names to correspond the result image type. A suffix is added if the input file doesn’t have one. Output directories are created if they don’t exist. Required if srcdir attribute or fileset elements are used.
classname Class name of the XML parser used to parse SVG images. The value can be either the complete classname with package information included or the special name jaxp, which means any available parser in the CLASSPATH that supports JAXP. See the Batik code for the default value. No

You can use fileset elements to select input files and directories. See the Ant documentation to learn how to use filesets.

Examples of using the rasterizer task

The following example is the complete Ant project that converts an SVG image (called input.svg) to a PNG image (called output.png): 

<?xml version="1.0"?>

<project name="RasterizerExample" default="main" basedir=".">

  <taskdef name="rasterize" 
           classname="org.apache.tools.ant.taskdefs.optional.RasterizerTask"/>

  <target name="main">
    <rasterize result="image/png" src="input.svg" dest="output.png"/>
  </target>
</project>

The next example is just one task in a project. It converts all files with a .svg suffix in the images directory and all files in the images2 directory to TIFF images. The resulting image files are placed in the results directory. 

  <rasterize result="image/tiff" destdir="results">
    <fileset dir="images">
      <include name="**/*.svg"/>
    </fileset>
    <fileset dir="images2"/>
  </rasterize>