| <?xml version="1.0"?> |
| <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd"> |
| |
| <!-- |
| |
| Copyright 2000-2003 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| |
| --> |
| <!-- ========================================================================= --> |
| <!-- author vincent.hardy@eng.sun.com --> |
| <!-- version $Id$ --> |
| <!-- ========================================================================= --> |
| |
| <document> |
| <header> |
| <title>Batik - SVG Rasterizer</title> |
| <subtitle>A cross platform SVG Rasterizer</subtitle> |
| <authors> |
| <person name="Vincent Hardy" email="vincent.hardy@eng.sun.com"/> |
| <person name="Henri Ruini" email="ruini@iki.fi"/> |
| </authors> |
| </header> |
| |
| <body> |
| <s1 title="Introduction"> |
| |
| <!-- <figure src="images/rasterizerBanner.jpg" alt="Batik SVG Rasterizer" /> --> |
| |
| <p> |
| This page describes the features of the SVG Rasterizer utility that |
| comes with the Batik distribution. It discusses the following:</p> |
| <ul> |
| <li><link href="#downloading">Downloading the rasterizer</link></li> |
| <li><link href="#using">Rasterizing one or several SVG files</link></li> |
| <li><link href="#task">The rasterizer Ant task</link></li> |
| </ul> |
| <p> |
| 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. |
| </p> |
| |
| </s1> |
| |
| <anchor id="downloading" /> |
| <s1 title="Downloading the rasterizer"> |
| |
| <p>Refer to the <link href="install.html">install |
| page</link> and the <link |
| href="http://www.apache.org/dyn/closer.cgi/xml/batik">download |
| area</link> to find out what to download and how to |
| install it. Remember that you can get either the <link |
| href="install.html#distributions">source |
| distribution</link> or the <link |
| href="install.html#distributions">binary |
| distribution</link>.</p> |
| </s1> |
| |
| <anchor id="using" /> |
| <s1 title="Rasterizing one or several SVG files"> |
| <p>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.</p> |
| |
| <anchor id="usingBinary" /> |
| <s2 title="Using the binary distribution" > |
| |
| <p>If you downloaded the binary distribution of Batik, you should have |
| gotten a file called <em>batik-1.5beta4.zip</em>, and, after expanding that |
| file, a JAR (Java ARchive) file called <code>batik-rasterizer.jar</code>. |
| To start the rasterizer, open a console, go to the directory where you |
| expanded the distribution (and where <code>batik-rasterizer.jar</code> is located) and |
| simply type the following at the command prompt :</p> |
| <p><code>java -jar batik-rasterizer.jar </code><em>[@files]</em></p> |
| <p>For example, if you type:</p> |
| <p><code>java -jar batik-rasterizer.jar samples/batikFX.svg</code></p> |
| <p>you will see the following printout:</p> |
| <p><code>Converting file: samples/BatikFX.svg to samples/BatikFX.png</code></p> |
| <p>Once the conversion is complete, you will find a <code>batikFX.png</code> file in the samples |
| directory</p> |
| <p>You can pass options to the command line:</p> |
| <p><code>java -jar batik-rasterizer.jar </code><em>[options] [@files]</em></p> |
| <p>Where the options are:</p> |
| <ul> |
| <li><code>-d</code><em> <dir|file></em>. Output directory. If there is a single input file, this can be a file.</li> |
| <li><code>-m</code><em> <mimeType></em>. Output mime type, one of image/png, image/jpeg, application/pdf, image/tiff.</li> |
| <li><code>-w</code><em> <width></em>. Output width. This is a floating point value.</li> |
| <li><code>-h</code><em> <height></em>. Output height. This is a floating point value.</li> |
| <li><code>-maxw</code><em> <width></em>. Maximum output width. This is a floating point value.</li> |
| <li><code>-maxh</code><em> <height></em>. Maximum output height. This is a floating point value.</li> |
| <li><code>-a</code><em> <area></em>. Output area. The format for <area> is x,y,w,h, where x, y, w and h |
| are floating point values.</li> |
| <li><code>-bg</code><em> <color></em>. Uuput color. The format for <color> is a.r.g.b, where a, r, g and b |
| are integer values.</li> |
| <li><code>-cssMedia</code><em> <media></em>.CSS media type for which the source SVG files should be |
| converted.</li> |
| <li><code>-cssAlternate</code><em> <alternate></em>. CSS alternate stylesheet to use when converting the source |
| SVG files.</li> |
| <li><code>-cssUser</code><em><userStylesheet></em>. CSS user stylesheet URI to apply to converted SVG documents |
| in addition to any other referened or embeded stylesheets.</li> |
| <li><code>-lang</code><em> <userLanguage></em>. User language to use when converting SVG documents.</li> |
| <li><code>-q</code><em> <quality></em>. Quality for the output image. This is only relevant for the |
| image/jpeg mime type.</li> |
| <li><code>-dpi</code><em> <resolution></em>. Resolution for the ouptut image.</li> |
| <li><code>-validate</code> Controls whether the source SVG files should be validated.</li> |
| <li><code>-onload</code> Controls if the source SVG files must be rasterize after dispatching the 'onload' event.</li> |
| <li><code>-scriptSecurityOff</code> Removes any security check on the scripts running as a result of dispatching the onload event.</li> |
| <li><code>-scripts</code><em><listOfAllowedScripts></em> List of script types (i.e., values for the type attribute in the <code><script></code> tag) which should be loaded.</li> |
| </ul> |
| |
| <p>For example:</p> |
| <ul> |
| <li><code>java -jar batik-rasterizer.jar -d myDir -m image/jpeg samples/*.svg</code> will generate JPEG images |
| for all the SVG files found in the samples directory.</li> |
| </ul> |
| <p><strong>NOTE:</strong> to run MIME type <code>application/pdf</code> need to have (see <link href="http://xml.apache.org/fop/index.html">FOP</link>) installed.</p> |
| </s2> |
| |
| <s2 title="Using the source distribution"> |
| |
| <p>If you downloaded the <link href="install.html#distributions">source distribution</link> |
| of Batik, you |
| got a zip or tar file that expanded into a directory called <code>xml-batik</code> directory. |
| In that directory, you can find <code>build</code> 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 |
| <code>build.sh</code> script |
| for UNIX users.</p> |
| <p>To start the rasterizer you should:</p><ul> |
| <li>Make sure the <code>xml-batik</code> directory is in your PATH environment variable</li> |
| <li>Make sure the <code>ANT_HOME</code> environment variable is set to the xml-batik directory</li> |
| <li>Make sure that your <code>JAVA_HOME</code> environment variable is set to your JDK installation |
| directory</li> |
| <li>Open a command line window and go to the <code>xml-batik</code> directory where the Batik |
| distribution was expanded</li> |
| <li>At the command prompt, type: <br /> |
| <strong>Windows: </strong><code>build svgrasterizer</code>.<br /> |
| <strong>UNIX: </strong><code>build.sh svgrasterizer</code>.<br /> |
| This will printout a |
| help message for the rasterizer</li> |
| </ul> |
| <p>You can pass options to the rasterizer as follows:</p> |
| <p><strong>Windows: </strong><code>build svgrasterizer </code><em>[options] [@files]</em></p> |
| <p><strong>UNIX: </strong><code>build.sh svgrasterizer </code><em>[options] [@files]</em></p> |
| <p>Refer to <link href="#usingBinary">"Using the binary distribution" </link>for an explanation of these |
| options</p> |
| </s2> |
| |
| </s1> |
| |
| |
| <anchor id="task" /> |
| <s1 title="Rasterizer Ant Task"> |
| <p>Rasterizer task is an |
| <link href="http://jakarta.apache.org/ant/index.html">Ant</link> |
| version of the rasterizer utility. It fulfills the same basic |
| purpose as the utility but has a different syntax and a |
| little different set of features.</p> |
| |
| <p>The task is able to produce four raster formats: PNG, JPEG, Tiff |
| and PDF. You need to have |
| <link href="http://xml.apache.org/fop/">FOP</link> installed (versions after |
| 0.20.2 should work) in your <em>CLASSPATH</em> if you want to |
| produce result images in PDF format.</p> |
| |
| <anchor id="initTask" /> |
| <s2 title="Taking rasterizer task in use"> |
| |
| <p>The first thing to do is to compile rasterizer task classes. |
| Download <link href="install.html#distributions">source distribution</link> |
| of Batik and see <code>README</code> file in <code>xml-batik\contrib\rasterizertask</code> |
| directory for more instructions. The build procedure works the same way as when building |
| Batik itself.</p> |
| |
| <p> After building set <code>batik-rasterizer.jar</code> and |
| classes (or JAR) of the rasterizer task to your |
| <em>CLASSPATH</em>.</p> |
| |
| <p>Next you have to define the task in your Ant |
| project. To do this, add the following line either after the |
| <code>project</code> start tag or after the <code>target</code> |
| start tag in the target you are using the rasterizer task:</p> |
| |
| <source> |
| <taskdef name="rasterize" |
| classname="org.apache.tools.ant.taskdefs.optional.RasterizerTask" /> |
| </source> |
| |
| <p>Now you can use the rasterizer task in your project! See the |
| <link href="taskParameters">parameters section</link> for an |
| explanation of the available parameters or |
| <link href="taskExamples">examples section</link> to see few |
| usage examples.</p> |
| </s2> |
| |
| <anchor id="taskParameters" /> |
| <s2 title="Parameters of the task"> |
| <table> |
| <tr> |
| <th>Attribute</th> |
| <th>Description</th> |
| <th>Required</th> |
| </tr> |
| <tr> |
| <td>result</td> |
| <td>Sets the type of the result image. Only one the |
| following values are allowed: <code>image/png</code>, |
| <code>image/jpeg</code>, <code>image/tiff</code> or |
| <code>application/pdf</code>. The value have to be in |
| lowercase letters.</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>height</td> |
| <td>Sets the height of the result image in pixels. 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 |
| <code>height</code> and <code>width</code> has been set. |
| </td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>width</td> |
| <td>Sets the width of the result image in pixels. 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 |
| <code>height</code> and <code>width</code> has been set. |
| </td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>maxheight</td> |
| <td>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.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>maxwidth</td> |
| <td>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.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>quality</td> |
| <td>Sets the quality of the produced image. The value |
| have to be greater than 0 but smaller than 1. A bigger |
| number means better quality. Quality value is used |
| only with JPEG images. |
| The default quality value is 0.99.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>area</td> |
| <td>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 with 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, |
| <code>"10, 20, 100, 200"</code> 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.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>bg</td> |
| <td>Sets the background color of the result image. |
| The <code>bg</code> 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.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>media</td> |
| <td>CSS media type which is used to select CSS |
| stylesheet. The selected stylesheet is then used to |
| rasterize the SVG files. Only visual media group is |
| supported (see |
| <link href="http://www.w3.org/TR/REC-CSS2/">CSS2 specification</link> |
| for more information about media groups). |
| The default value is <code>screen</code>.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>dpi</td> |
| <td>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.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>lang</td> |
| <td>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 <code>en</code>.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>src</td> |
| <td>Name of a one input file. Use this parameter to |
| convert just one file which name and location are known. |
| <code>dest</code> parameter have to be set, too.</td> |
| <td>One of the following is required: <code>src</code> |
| attribute, <code>srcdir</code> attribute or |
| <code>fileset</code> element(s).</td> |
| </tr> |
| <tr> |
| <td>dest</td> |
| <td>Name of a one output file. Use this with |
| <code>src</code> parameter only. Output directory is |
| created if it doesn't exist.</td> |
| <td>Required if <code>src</code> is used.</td> |
| </tr> |
| <tr> |
| <td>srcdir</td> |
| <td>Name of the input directory. <code>srcdir</code> and |
| <code>fileset</code> elements can be combined and |
| <code>srcdir</code> can be left out if there are at |
| least one <code>fileset</code> child element. |
| <code>srcdir</code> file selection can be controlled |
| with <code>include</code>, <code>exclude</code>, etc. |
| child elements. Note that without control parameters |
| the task tries to rasterize <em>all</em> files in |
| the given directory.</td> |
| <td>One of the following is required: <code>src</code> |
| attribute, <code>srcdir</code> attribute or |
| <code>fileset</code> element(s).</td> |
| </tr> |
| <tr> |
| <td>destdir</td> |
| <td>Name of an output directory. Use this with |
| <code>srcdir</code> parameter or <code>fileset</code> |
| 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.</td> |
| <td>Required if <code>srcdir</code> attribute or |
| <code>fileset</code> elements are used.</td> |
| </tr> |
| <tr> |
| <td>classname</td> |
| <td>Classname of the XML parser used to parse SVG images. |
| The value can be either complete classname with package |
| information included or <code>jaxp</code>, |
| which means any available parser in the <code>CLASSPATH</code> |
| that supports JAXP. See the Batik code for the default value.</td> |
| <td>No</td> |
| </tr> |
| </table> |
| <p>You can use <code>fileset</code> elements to select input |
| files and directories. See the <link href="http://jakarta.apache.org/ant/index.html">Ant</link> |
| documentation to learn how to use |
| <link href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html">filesets</link>.</p> |
| </s2> |
| |
| <anchor id="taskExamples" /> |
| <s2 title="Examples of using the rasterizer task"> |
| |
| <p>The following example is the complete Ant |
| project which converts SVG image (called <em>input.svg</em>) to PNG image |
| (called <em>output.png</em>):</p> |
| |
| <source> |
| <?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> |
| </source> |
| |
| <p>The next example is just a one task in a project. It |
| converts all files with <code>.svg</code> suffix in |
| <em>images</em> directory and all files in <em>images2</em> |
| directory to Tiff images. The resulting image files are placed |
| in the <em>results</em> directory.</p> |
| |
| <source> |
| <rasterize |
| result="image/tiff" |
| destdir="results"> |
| <fileset dir="images"> |
| <include name="**/*.svg" /> |
| </fileset> |
| <fileset dir="images2" /> |
| </rasterize> |
| </source> |
| |
| </s2> |
| </s1> |
| |
| |
| </body> |
| </document> |
