Transcoding

EchoSVG supports converting a few formats from and to SVG, for example:

• SVG to PNG

• SVG to JPEG

• SVG to TIFF

• WMF to SVG

• SVG to SVG, or pretty-printing SVG

Prerequisites

First, you have to declare a dependency on the echosvg-transcoder module in your build, for example in Gradle you would put the following in your build.gradle file (see Gradle Notes for more information):

Then, in your build.gradle file you can list the dependencies, for example:

dependencies {
    implementation "io.sf.carte:echosvg-transcoder:${echosvgVersion}"
}

or the equivalent if you use Maven (please read Maven Notes first).

If your project is modular, do not forget

requires io.sf.carte.echosvg.transcoder

API

The base interface for transcoding is Transcoder, and there you will find a single method used to transcode, which takes input and output objects:

void transcode(TranscoderInput input, TranscoderOutput output) throws TranscoderException;

Different transcoders allow you to achieve different things, and in order to configure the transcoding you can set several transcoding hints, which are documented in the API javadocs. Not all of the hints apply to all the transcoders, but common ones that you may use are the following:

KEY_DOCUMENT_ELEMENT, KEY_DOCUMENT_ELEMENT_NAMESPACE_URI

You only need to set those hints if you process SVG inside an HTML document, in which case you should do the following:

transcoder.addTranscodingHint(XMLAbstractTranscoder.KEY_DOCUMENT_ELEMENT_NAMESPACE_URI,
     "http://www.w3.org/1999/xhtml");
transcoder.addTranscodingHint(XMLAbstractTranscoder.KEY_DOCUMENT_ELEMENT, "html");

KEY_WIDTH, KEY_HEIGHT

Expressed in CSS pixels, let you scale the image.

transcoder.addTranscodingHint(SVGAbstractTranscoder.KEY_WIDTH, 600f);
transcoder.addTranscodingHint(SVGAbstractTranscoder.KEY_HEIGHT, 600f);

KEY_MEDIA

Set a valid CSS medium.

transcoder.addTranscodingHint(SVGAbstractTranscoder.KEY_MEDIA, "print");

KEY_EXECUTE_ONLOAD

Execute the script's onload event (only Javascript is supported via Rhino, and should not be used on untrusted scripts).

transcoder.addTranscodingHint(SVGAbstractTranscoder.KEY_EXECUTE_ONLOAD, Boolean.TRUE);

KEY_SVG_SELECTOR

If the SVG image is embedded inside an HTML document which contains several embedded SVGs, you can set a selector that points to the desired one.

transcoder.addTranscodingHint(SVGAbstractTranscoder.KEY_SVG_SELECTOR, ".svgclass");

KEY_DEFAULT_FONT_FAMILY

As the name implies, allow setting the default font family.

transcoder.addTranscodingHint(SVGAbstractTranscoder.KEY_DEFAULT_FONT_FAMILY, "Helvetica");

KEY_BACKGROUND_COLOR

For image transcoders only, allows setting a background color.

transcoder.addTranscodingHint(ImageTranscoder.KEY_BACKGROUND_COLOR, Color.cyan);

KEY_QUALITY

For the JPEG transcoder only, sets the desired quality (0 to 1).

transcoder.addTranscodingHint(JPEGTranscoder.KEY_QUALITY, 0.86f);

Example

Transcode an SVG file into PNG

PNGTranscoder transcoder = new PNGTranscoder();
transcoder.addTranscodingHint(SVGAbstractTranscoder.KEY_DEFAULT_FONT_FAMILY, "Open Sans");

try (FileReader reader = new FileReader(originFile, StandardCharsets.UTF_8);
        FileOutputStream ostream = new FileOutputStream(destinationFile)) {
    TranscoderInput input = new TranscoderInput(reader);
    TranscoderOutput output = new TranscoderOutput(ostream);
    transcoder.transcode(input, output);
}

Modern CSS with CSSTranscodingHelper

If you need support for more modern CSS than the basic Transcoder infrastructure provides, give the CSSTranscodingHelper a try. It is basically a wrapper over the transcoder, with support for recent CSS and (to some extent) foreign elements.