+
+
1. General questions
+
+
1.1. What is Batik?
+
+
+
+ Batik is a Java-based toolkit for applications or applets that want
+ to use images in the Scalable
+ Vector Graphics (SVG) format for various purposes, such as
+ display, generation or manipulation.
+
+
+
+
1.2. What is SVG?
+
+
+
+
+SVG (Scalable Vector
+ Graphics) is an open-standard language for describing
+ two-dimensional (2D) graphics in XML. It is a Recommendation from the
+ W3C. SVG lets you describe rich images
+ with features such as gradients, transparency, filter effects and animation.
+
+
+ SVG has three types of graphic objects: shapes (e.g., paths consisting
+ of straight lines and curves), images and text. Graphical objects can be grouped,
+ styled, transformed and composited (e.g., drawn with transparency). SVG has a
+ large set of static features which includes nested transformations, clipping
+ paths, masking and filter effects.
+
+
+ In addition, SVG images can be dynamic and interactive. A rich set of event
+ handlers such as for mouse movement and clicks can be assigned to any SVG
+ graphical object. These handlers can invoke scripts, which, in response to an
+ event, can dynamically modify the SVG graphic through the SVG Document Object Model
+ (DOM) API, allowing, for example scripts to change the color or location of graphical
+ elements.
+
+
+ SVG graphical elements can be animated through scripting. Alternatively,
+ animation sequences can be expressed directly in XML because SVG leverages the
+ SMIL Animation
+ specification for multimedia, another
+ W3C specification.
+
+
+
+
1.3. What can I do with Batik?
+
+
+
+ Batik contains several core modules
+ which can be used independently or jointly to generate SVG
+ content (see the SVG Generator
+ and SVG DOM implementation documentation)
+ view SVG content (see the JSVGCanvas)
+ or convert to and from the SVG format (see the
+ SVG Transcoder page).
+
+
+ In addition, Batik contains
+ low level
+ modules, such as an object-oriented Graphic Vector Toolkit
+ (GVT), a set of low level parsers specific to the SVG syntax and a
+ set of extensions to the Java 2D API
+ (such as sophisticated fill types and filter effects).
+
+
+ Finally, Batik comes with packaged applications to help developers get
+ familiar with the code and be quickly able to use the various modules: Squiggle, an
+ SVG browser (in the
+ org.apache.batik.apps.svgbrowser package) an
+ SVG rasterizer (in the
+ org.apache.batik.apps.rasterizer package), a
+ Font converter (in the
+ org.apache.batik.apps.ttf2svg package) and an
+ SVG pretty printer (in the
+ org.apache.batik.apps.svgpp package).
+
+ Squiggle, the SVG browser can display SVG
+ documents and lets the user zoom, pan and rotate any SVG document,
+ view the SVG source, link between SVG documents, view a tree
+ representation of the SVG DOM and more. One important component of
+ the SVG viewer is the org.apache.batik.swing.JSVGCanvas
+ component, which can be plugged in to any Java application or applet
+ to provide SVG viewing capability.
+
+
+ The SVG rasterizer
+ lets the user convert
+ SVG files to raster formats such as JPEG, PNG or TIFF . It
+ contains an extensible mechanism so that arbitrary raster
+ formats can be added. For example, the rasterizer lets you
+ create one SVG file with a special effect (e.g., shadows,
+ gradients, etc.), turn it into a PNG image, then modify the
+ SVG source (e.g., modify a piece of text or a color), and
+ generate another PNG image from it. This way, you can easily
+ generate a series of images sharing a common theme or look and
+ feel to post on a web site. (Note that the rasterizer can also
+ be used on a web server to do this conversion automatically).
+
+
+ The SVG Font Converter
+ lets the user easily create
+ an SVG
+ Font for a set of characters from a TrueType Font
+ file. That SVG Font definition can be embedded in a document
+ using the characters. This allows users to create SVG
+ documents that are self contained and do not rely on system
+ fonts, and guarantees that the SVG file will be displayed
+ exactly as it was authored on all platforms.
+
+
+ The SVG Pretty Printer
+ is a convenience tool to
+ pretty print an SVG document, which means that you can
+ reformat any existing SVG document to produce a nicely
+ formatted and highly legible version.
+
+
+ These applications show that Batik can be used client side
+ (the browser can be used on any client machine) and server
+ side (the rasterizer can be used to serve SVG images to client
+ machines that do not have SVG support).
+
+
+
+
1.4. Why do we have such a project at Apache?
+
+
+
+ The mission
+ of the Apache XML Graphics Project is to promote the use of
+ XML-based graphics by “providing robust, full-featured,
+ commercial-quality, and freely available software packages for the
+ conversion of XML to graphical output and for related components”.
+ Batik as an open source implementation of a key format for today’s
+ and tomorrow’s web fits well in this mission.
+
+
+
+
1.5. How does Batik relate to other Apache projects?
+
+
+
+ Batik is used in Cocoon
+ for server side rasterization of SVG images. In addition, the Batik is used in the
+ FOP project to convert
+ SVG images to PDF format.
+
+
+
+
1.6. How did it start?
+
+
+
+ Batik started out because several teams doing SVG related projects decided to join
+ efforts with the idea that the whole will be greater than the sum of the parts. The
+ following companies or institutions are part of the team that contributed and/or
+ created the initial Batik project, during the fall of 2000:
+
+
+
+ In addition, the Batik project is supported by IBM.
+
+
+ We encourage anyone to participate. As with all ASF projects, all efforts are
+ volunteer-based. We are looking for individuals to work with us on
+ fulfilling our goals for Batik in the spirit of collaborative open-source
+ software development.
+
+
+
+
1.7. Where is Batik going? What is next?
+
+
+
+ The SVG implementation is not complete (see the current
+ status), and there is more work to
+ do to achieve a fully functional viewer.
+
+
+ Batik 1.1 supports all static SVG features,
+ linking and a limited support for scripting, and the 1.5 release
+ completed support for scripting and dynamic documents.
+ With Batik 1.6 came many improvements to
+ the implementation of SVG DOM functions, bug fixes, performance
+ improvements, and the beginning of some SVG 1.2 support.
+ Declarative animation and further SVG 1.2 features
+ should be supported in the 2.0 release.
+
+
+ The type of applications (e.g., transcoding applications)
+ that can or will be added to Batik depends on contributions
+ and feedback.
+
+
+
+
1.8. How can I create and author SVG content?
+
+
+
+ Well, you can always use a plain text editor such as vi or
+ xemacs, but there are many graphic authoring packages that can
+ export SVG documents and that will let you author SVG content
+ visually.
+
+
+ You can get a list of tools exporting SVG from the SVG
+ implementation section of the SVG Home page on the W3C
+ web site. You can also imagine building a tool on top of
+ Batik: feel free to contribute!
+
+
+ Authoring is one way of creating SVG content, and graphic
+ authoring packages are useful for that purpose. However, there
+ are many types of graphics which can be generated, such as
+ stock quotes, statistical data, etc. For these types of
+ graphics, there are many ways to generate SVG content. For
+ example, if your data (say stock information) is contained in
+ an XML document, you could use XSLT to transform your XML data
+ into SVG. If your data comes from a database and you retrieve
+ that data in a servlet on a Web server (e.g., using JDBC), you
+ could use the Java binding for the DOM API to generate an SVG
+ document from the database data. You could also use Batik’s
+ SVG generator and use the Java 2D API to generate that
+ graphic.
+
+
+ The following URLs will be useful to learn more about each of
+ these solutions:
+
+
+
+
+
1.9. What other SVG products are out there?
+
+
+
+
1.10. Where can I find the SVG specification?
+
+
+
+
1.11. How much of SVG does Batik implement?
+
+
+
+
1.12. What are the benefits of SVG being an XML grammar?
+
+
+
+ Being an XML grammar means SVG can leverage work done around
+ XML, and SVG actually leverages other grammars such as
+ XLink,
+ for linking and
+ SMIL
+ for the animation.
+
+
+ Beyond the use and mix with other XML syntaxes, being an XML grammar
+ lets SVG benefit from the plethora of XML tools that make it so easy
+ to manipulate, generate, search and edit XML files.
+
+
+
+
1.13. Where does the name come from?
+
+
+
+ Batik is a highly evolved art tradition that developed in Java
+ (one of the islands comprising what is now called
+ Indonesia). Batik is generally thought of as the quintessentially
+ Indonesian textile. Motifs of flowers, twining plants, leaves,
+ buds, birds, butterflies, fish, insects and geometric forms are
+ rich in symbolic association and variety; there are about three
+ thousand recorded batik patterns.
+
+
+ We think that Batik gracefully evokes Java, graphics and
+ high-quality, terms that constitute the core of the toolkit.
+
+
+
+This page
+ shows examples of what Batik textures look like.
+
+
+
+
2. Getting started with Apache Batik/SVG
+
+
2.1. What are the system requirements to run Batik?
+
+
+
+ Batik is written in the Java language and requires a version 1.3
+ implementation at this time.
+
+
+
+
2.2. How do I install Batik?
+
+
+
+ You will need the JDK 1.3 to run
+ Batik.
+
+
+ To install Batik you need to download
+ the binary or source distribution and unzip it on your computer.
+
+
+ You can have a look at the installation
+ instructions for more information.
+
+
+
+
2.3. How can I see a demo?
+
+
+
+ You can see an online demonstration of Squiggle the SVG
+ browser on the demo page. Alternatively, you
+ can download Batik or see
+ screenshots of the Batik SVG viewer,
+ images created from the rasterizer and
+ an example of how to use the
+ SVGGraphics2D generator.
+
+
+
+
2.4. What scripting languages can I use in my SVG files?
+
+
+
+ A limited support of scripting in SVG files is provided with
+ the current version of Batik (script are executed but dynamic
+ update is not supported).
+
+
+ Batik can recognize the following scripting languages:
+
+
+
+-
+ ECMAScript thanks to the
+ Mozilla Rhino JavaScript
+ engine included in the distribution,
+
+
+-
+ Python for which you need to download the
+ Jython engine, and
+
+
+-
+ Tcl for which you need to download the
+ Jacl engine.
+
+
+
+
+ To get more information on how to install optional
+ scripting languages you can have a look at the
+ installation instructions.
+
+
+
+
3. Troubleshooting Apache Batik
+
+
3.1.
+ When I try to run Batik it results in a NoSuchMethodException. What
+ is the problem?
+
+
+
+
+ There is certainly something wrong with your classpath. Clear your
+ CLASSPATH environment variable and be sure to remove
+ all the libraries which use the W3C’s DOM bindings from
+ jre/lib/ext before running any of the Batik’s
+ applications.
+
+
+
+
3.2.
+ When I change the document in Java it doesn’t update the
+ display, even if I call repaint?
+
+
+
+
+ There are two common causes for this. The first is that the
+ JSVGCanvas
+ doesn’t know it’s a dynamic document. Normally
+ Batik detects this by looking for script elements but when you
+ modify the document from Java it can’t tell. So call
+
+
myJSVGCanvas.setDocumentState(JSVGCanvas.ALWAYS_DYNAMIC);
+
+ before loading the document (with setURI,
+ setDocument, setSVGDocument, etc.).
+
+
+ The second common reason is that the changes aren’t made in
+ the
+ UpdateManager’s
+ thread. You can run code in the UpdateManager’s thread
+ with the following:
+
+
UpdateManager um = JSVGCanvas.getUpdateManager();
+um.getUpdateRunnableQueue().invokeLater(Runnable);
+
+
+NOTE: The update manager only becomes
+ available after the first rendering completes. You can
+ be notified when this happens by registering a
+ GVTTreeRendererListener.
+
+
+
+
3.3.
+ When I change the document in Java it only updates if I
+ move the mouse over the canvas?
+
+
+
+
+ The most common causes for this, is that the changes are not made in
+ the UpdateManager’s thread. See previous FAQ for
+ example code to run code in the Update Manager’s thread. Moving the
+ mouse works because it delivers the mouse move events in the update
+ thread, and after a runnable completes in the
+ UpdateManager’s thread it checks if the canvas needs
+ repainting.
+
+
+
+
3.4.
+ When I create new SVG elements or modify some SVG attributes through
+ the DOM API, from ECMAScript, nothing happens, the changes are not
+ rendered. Why not?
+
+
+
+
+ A common problem is that script contain the wrong DOM calls
+ to create elements or modify attributes.
+
+
+ SVG elements need to be created in the SVG namespace. For example,
+ to create a rect element, you should use
+
+
document.createElementNS(svgNS, "rect");
+
+ (where svgNS is equal to
+ "http://www.w3.org/2000/svg"), which appropriately
+ creates the rect element in the SVG namespace. A call to
+
+
document.createElement("rect")
+
+ creates an element with the name rect but which does not
+ belong to the SVG namespace. As such, it is ignored by Batik.
+
+
+ Most SVG attributes belong to what is called the “per element type
+ partition namespace” (see the
+ Namespaces in XML
+ specification). The appropriate way to set attributes on an SVG
+ element is a call to setAttributeNS with a namespace
+ value of null, for example:
+
+
elt.setAttributeNS(null, "width", "40");
+
+ In the Batik SVG DOM implementation, you can also use a call to
+ setAttribute and you can write
+
+
elt.setAttribute("width", "40")
+
+ However, it is important to know that some implementations make a
+ difference between setAttribute(x, y) and
+ setAttributeNS(null, x, y), so it is goo practice
+ to use setAttributeNS which is the only guaranteed
+ interoperable way of setting attributes in a namespace aware DOM
+ implementation.
+
+
+ Finally, for attributes which belong to a specific namespace, like the
+ the href attribute on the image element,
+ you have to use the setAttributeNS method with the
+ XLink namespace. For example, assuming img references an
+ image DOM Element, you can modify the
+ href as follows:
+
+
img.setAttributeNS(xlinkNS, "xlink:href", "myImage.jpg");
+
+ where xlinkNS is equal to
+ "http://www.w3.org/1999/xlink".
+
+
+ For more information on common authoring pitfalls, see Jonathan Watt’s
+ SVG Authoring
+ Guidelines.
+
+
+
+
3.5.
+ When I get the UpdateManager from the canvas sometimes
+ it is null, why?
+
+
+
+
+ The JSVGCanvas is highly asynchronous so when you call
+ setURI, setDocument or
+ setSVGDocument they return essentially immediately.
+ Behind the scenes, the canvas creates the rendering tree and does a
+ first rendering after dispatching the document SVGLoad
+ event. Only after this first rendering does the
+ UpdateManger become available.
+
+
+
+
3.6.
+ Why do I have to go through the UpdateManager to
+ run my code? Can’t you just synchronize the DOM?
+
+
+
+
+ It would be possible to synchronize individual calls to
+ the DOM, however in general this is almost useless for the
+ way DOM works. For example creating a single rectangle
+ element takes approximately 6 individual DOM calls. So
+ higher level synchronization is needed.
+
+
+ The use of a
+ Runnable
+ is a common way of accomplishing synchronization for a block of code.
+ This is essentially the approach that Swing takes (all Swing
+ modification should take place in the Swing thread). It was
+ considered to use the Swing event thread, but this would lock the
+ user interface while scripts were working.
+
+
+
+
3.7.
+ I can use the Batik extension tags with the source distribution
+ but not with the binary distribution. What am I missing?
+
+
+
+
+ When running from the source distribution you automatically get the
+ service provider entries for the Batik extension elements
+ (such as regularPolygon and star).
+ We chose not to include these by default in the
+ binary distribution for the Batik applications.
+
+
+ There is a subdirectory called extensions that has jar
+ files that enable the extended elements from Batik.
+
+
+
+
3.8.
+ Why do I get red circles when I view the samples/extensions files?
+
+
+
+
+ You are using the binary distribution. This distribution does not
+ include support for our example extensions (they are just examples
+ and other people can do more sophisticated things).
+
+
+ If you want to view these examples you need to use the extension
+ enabled versions of the applications in the extensions
+ subdirectory.
+
+
+
+
3.9.
+ I am modifying the DOM after displaying it in the JSVGCanvas,
+ but my changes aren’t shown (even if I call repaint).
+
+
+
+
+ For efficiency, if Batik loads a static document it doesn’t
+ set up any dynamic support. Batik normally decides whether a
+ document is dynamic by checking if it contains any
+ script elements or event handler attributes. However,
+ if your Java application is modifying the DOM directly there may be
+ no script elements. In this case you need to tell Batik to set up
+ dynamic support regardless.
+
+
+ You can inform the JSVGCanvas that a document should
+ be handled dynamically by calling the setDocumentState
+ method, just before loading the document:
+
+
JSVGCanvas myCanvas = ...;
+myCanvas.setDocumentState(JSVGCanvas.ALWAYS_DYNAMIC);
+myCanvas.setURI("myFile.svg");
+
+
+
3.10.
+ I am trying to use Batik and FOP together but Batik does not work and
+ fails on the org.w3c.* packages. What is happening?
+
+
+
+
+ Both FOP and Batik use the org.w3c.* packages.
+ Depending on the version of FOP and Batik, Batik has been using a
+ version of these packages which is more recent than the one in the
+ xml-apis.jar file FOP uses. However, if the
+ xml-apis.jar file that comes with the FOP distribution
+ is loaded before the Batik jar files, then the version coming with
+ FOP takes precedence (i.e., that is the version the Java Virtual
+ Machine loads). Because that version is incompatible with Batik, you
+ encounter this problem.
+
+
+ The solution is to either repackage the xml-apis.jar file
+ with the classes in the Batik distribution (you will need the Batik
+ source distribution to do that), or you will need to make sure the
+ Batik jars are loaded before FOP’s xml-apis.jar, for
+ example by putting Batik’s jar file before FOP’s in your classpath.
+ If you are copying your jar files to .../jre/lib/ext,
+ you can simply remove the FOP xml-apis.jar file from
+ that directory.
+
+
+
+
3.11.
+ How do I checkout the latest SVN version of Batik?
+
+
+
+
+ You just have to follow the instructions on the
+ download page.
+
+
+
+
3.12.
+ I’m using Mac OS X, and some of the SVG files I view are messed up
+ (things appear clipped or out of place). What do I need to do to fix
+ this?
+
+
+
+
+ As of Mac OS X release 10.1.1 there still appears to be
+ problems in the Apple implementation of the Java 2D APIs. The
+ true source of these problems and/or workarounds have yet to be
+ identified (although the problems appear to be closely tied to a
+ “gstack underflow” error message from the Apple JVM). We are
+ interested in finding the source of these problems and
+ reasonable workarounds, so if you know what causes these errors
+ the Batik team would be very interested in hearing from you
+ (either directly or through the user/developer mailing lists).
+
+
+ Other things to be aware of on Mac OS X, due to fixes for
+ other problems with Java 2D under Mac OS X, you may find that
+ some filtering operations take significantly more memory than on
+ other platforms. This will be especially true for deeply nested
+ filter trees (where the result of one filtering operation is
+ filtered by another filtering operation).
+
+
+ Finally a few hints on avoiding problems under Mac OS X. The
+ bugs seems to be triggered by filters, and pure raster SVG documents
+ have not been found to cause problems. The use of the
+ filterRes attribute on the filter element
+ seems especially problematic. The bug isn’t 100% reproducible, so
+ while some content exhibits the problem, if you play with the
+ document enough it will often “fix” itself for a while, then later
+ it will go back to being broken (which indicates that the problem may
+ be some sort of race condition in the JVM).
+
+
+
+
3.13.
+ I cannot run the Batik demo on Mac OS X (10.1.1). The Batik splash
+ screen hangs. What is happening?
+
+
+
+
+ The Batik demo uses Java Web Start. Java Web
+ Start (under the Applications/Utilities folder), lets
+ you start a Java application from a web browser. You can see the
+ debug traces by enabling the Java console for Java Web Start. If you
+ do, you will see that there is a
+ java.lang.NoSuchMethodError exception thrown.
+
+
+ This is happening because the Java Web Start jar file
+ (javaws.jar in /Applications/Utilities/Java Web
+ Start/Content/MacOS) contains an older version of the DOM
+ bindings.
+
+
+ One work around is to manually patch the javaws.jar
+ file to remove the DOM bindings so that they do not take precedence
+ over the Batik ones.
+
+
+
+
4. How do I contribute to Batik Development?
+
+
4.1. How can I contribute to Apache Batik development?
+
+
+
+ The Batik Project is an open volunteer project in the
+ spirit of the Apache
+ Software Foundation (ASF). This means that there are
+ many ways to contribute to the project, either with direct
+ participation (coding, documenting, answering questions,
+ proposing ideas, reporting bugs, suggesting bug-fixes, etc.)
+ or by resource donation (publicity, hardware, software,
+ conference presentations, speeches, etc.). Applications that
+ use the Batik modules, such as tools or extensions, are of special
+ interest to the project.
+
+
+ The process for contributing to Batik is the same as for other
+ Java projects at Apache. A formal description of that process
+ can be found on the Jakarta
+ web site. You can also view a list of
+ who has contributed to Batik.
+
+
+ For direct participation, we suggest that you subscribe to the
+ Batik mailing lists and to
+ checkout the
+ latest
+ code.
+
+
+
+
4.2. How do I submit patches or bug fixes?
+
+
+
+ You can submit bug fixes and patches to the
+ Batik developers
+ mailing list and you can enter bugs in
+ Bugzilla.
+
+
+
