Frequently Asked Questions
Questions
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 some SVG 1.2 features were introduced in Batik 1.7beta1. The 1.7 release brought mostly bug fixes. Completion of remaining SVG 1.1 functionality and the addition of Further SVG 1.2 functionality 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?
There are many companies supporting SVG and you will find a list of available implementations on the W3C’s SVG implementation page.
1.10. Where can I find the SVG specification?
The SVG specification is available from the W3C web site.
1.11. How much of SVG does Batik implement?
The status page shows how much of the SVG specification Batik implements by showing which of the tests in the SVG Basic Effectivity test suite Batik successfully passes.
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 8 implementation at this time.
2.2. How do I install Batik?
You will need a JRE/JDK version 8 or above 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 Git 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.