JSVG - A Java SVG implementation

<p align="center"> <img src="https://raw.githubusercontent.com/weisJ/jsvg/master/images/svg_logo.png" alt="The SVG logo rendered by JSVG" align="center" width="150" height="150"> <br> <em>The SVG logo rendered using JSVG</em> </p>

JSVG is an SVG user agent using AWT graphics. Its aim is to provide a small and fast implementation. This library is under active development and doesn't yet support all features of the SVG specification (see Supported features). However it does already cover most use cases and already supports more features than svgSalamander. This implementation only tries to be a static user agent meaning it won't support any scripting languages or interaction. Partial animations exists and will be extended in future versions.

This library aims to be as lightweight as possible. Generally JSVG uses ~50% less memory than svgSalamander and ~98% less than Batik.

Projects using JSVG

• The Jetbrains IDEA IDE suite (YouTrack Ticket).
• Apache NetBeans (PR #7941)
• Eclipse SWT (PR #1638)
• FlatLaf for FlatSVGIcon (PR #684)

How to use

The library is available on maven central:

dependencies {
    implementation("com.github.weisj:jsvg:2.0.0")
}

Also, nightly snapshot builds will be released to maven:

repositories {
    maven {
        url = uri("https://central.sonatype.com/repository/maven-snapshots")
    }
}

// Optional:
configurations.all {
    resolutionStrategy.cacheChangingModulesFor(0, "seconds")
}

dependencies {
    implementation("com.github.weisj:jsvg:latest.integration")
}

JSVG provides OSGi metadata in the manifest file.

Loading

To load an svg icon you can use the SVGLoader class. It will produce an SVGDocument

SVGLoader loader = new SVGLoader();
URL svgUrl = MyClass.class.getResource("mySvgFile.svg");
SVGDocument svgDocument = loader.load(svgUrl);

If you need more control over the loading process you can pass a LoaderContext for configuration purposes.

SVGDocument svgDocument = loader.load(svgUrl,
    LoaderContext.builder()
                 // configure the context
                 // ...
                 .build());

Note that SVGLoader is not guaranteed to be thread safe, hence shouldn't be used across multiple threads.

Note that by default XML entities will not be replaced during parsing. If you need this behaviour you can use a custom XML parser by implementing the XMLInput interface. A usage example can be found below in the examples.

Rendering

An SVGDocument can be rendered to any Graphics2D object you like e.g. a BufferedImage

FloatSize size = svgDocument.size();
BufferedImage image = new BufferedImage((int) size.width,(int) size.height);
Graphics2D g = image.createGraphics();
svgDocument.render(null,g);
g.dispose();

or a swing component

class MyComponent extends JComponent {
    @Override
    protected void paintComponent(Graphics g) {
        super.paintComponent(g);
        svgDocument.render(this, (Graphics2D) g, new ViewBox(0, 0, getWidth(), getHeight()));
    }
}

For more in-depth examples see Usage examples below.

Rendering Quality

The rendering quality can be adjusted by setting the RenderingHints of the Graphics2D object. The following properties are recommended:

g.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON);
g.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL, RenderingHints.VALUE_STROKE_PURE);

If either of these values are not set or have their respective default values (VALUE_ANTIALIAS_DEFAULT and VALUE_STROKE_DEFAULT) JSVG will automatically set them to the recommended values above.

JSVG also supports custom SVG specific rendering hints. These can be set using the SVGRenderingHints class. For example:

// Will use the value of RenderingHints.KEY_ANTIALIASING by default
g.setRenderingHint(SVGRenderingHints.KEY_IMAGE_ANTIALIASING, SVGRenderingHints.VALUE_IMAGE_ANTIALIASING_ON);

By default clipping with a <clipPath> element does not use soft-clipping (i.e. anti-aliasing along the edges of the clip shape). This can be enabled by setting

g.setRenderingHint(SVGRenderingHints.KEY_SOFT_CLIPPING, SVGRenderingHints.VALUE_SOFT_CLIPPING_ON);

In the future this will get stabilized and be enabled by default.

Supported custom rendering hints are:

| Key | Values | Default | Description | |-----------------------------|-----------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | KEY_IMAGE_ANTIALIASING | VALUE_IMAGE_ANTIALIAS_ON<br>VALUE_IMAGE_ANTIALIAS_OFF | Value of RenderingHints.KEY_ANTIALIASING | Enables anti-aliasing for images | | KEY_SOFT_CLIPPING | VALUE_SOFT_CLIPPING_ON<br>VALUE_SOFT_CLIPPING_OFF | VALUE_SOFT_CLIPPING_OFF | Enables soft (anti-aliased) clipping for clipPath | | KEY_MASK_CLIP_RENDERING | VALUE_MASK_CLIP_RENDERING_FAST<br>VALUE_MASK_CLIP_RENDERING_ACCURACY<br>VALUE_MASK_CLIP_RENDERING_DEFAULT | VALUE_MASK_CLIP_RENDERING_DEFAULT = VALUE_MASK_CLIP_RENDERING_FAST | Changes how masks and clip paths are rendered. Accurate rendering enforces the sub-image to which the mask/clip is applied to be rendered on its own isolated offscreen image | | KEY_CACHE_OFFSCREEN_IMAGE | VALUE_USE_CACHE<br>VALUE_NO_CACHE | VALUE_USE_CACHE | Whether to cache offscreen images. This can be useful for performance reasons, but can also lead to increased memory usage. |

All are exposed through the SVGRenderingHintsclass.

Animations

The current support for animations is limited and in an experimental state. Only basic timing mechanisms and interpolation methods are supported. Moreover most animatable properties aren't yet supported. Please beware that the API for animations is subject to change.

Animations can be controlled on a per frame basis by supplying an AnimationState to SVGDocument#renderWithPlatform. In particular this means that animations need to be driven by the user code. See below for examples on how to do this.

Supported features

For supported elements most of the attributes which apply to them are implemented.

• :white_check_mark:: The element is supported. Note that this doesn't mean that every attribute is supported.
• :white_check_mark:*: The element is supported, but won't have any effect (e.g. it's currently not possible to query the content of a <desc> element)
• :ballot_box_with_check:: The element is partially implemented and might not support most basic features of the element.
• :x:: The element is currently not supported
• :warning:: The element is deprecated in the spec and has a low priority of getting implemented.
• :test_tube:: The element is an experimental part of the svg 2.* spec. It may not fully behave as expected.

Shape and container elements

| Element | Status | |---------------|---------------------| | a | :white_check_mark: | | circle | :white_check_mark: | | clipPath