Image Transcoder Tutorial


	トランスコーダAPI

org.apache.batik.transcoder パッケージは5つのメジャークラスを定義します:

Transcoder -
トランスコーダの全てが実装するインターフェースを定義します。あなたは個々の出力を使用する個々の入力を、transcode メソッドを呼び出すことによってトランスコードできます。入出力のフォーマットについては何も決まりがありませんが、トランスコーダによっては、特定の種類の入出力をサポートしないかもしれません。たとえば、イメージトランスコーダはSVGの org.w3c.dom.Document, Reader, InputStream, URI を入力として受け付けますが、出力としてはバイトストリームをサポートするのみです。

TranscoderInput -
トランスコーダへの入力を定義します。入力を生成する手段はさまざまですし、もっとも一般的なものについては既にAPIの一部になっています。デフォルト実装では、 org.w3c.dom.Document, Reader, InputStream, org.xml.sax.XMLReader, URIを用いて入力を生成させてくれます。

TranscoderOutput -
トランスコーダへの入力を定義します。入力を生成する手段はさまざまですし、もっとも一般的なものについては既にAPIの一部になっています。デフォルト実装では、 org.w3c.dom.Document, Writer, OutputStream, org.xml.sax.XMLFilter, URIを用いて入力を生成させてくれます。

TranscodingHints -
TranscodingHints クラスは、トランスコーダのさまざまなオプションやパラメータをコントロールするために使用される、それぞれのヒントを含みます。トランスコーダはそれぞれ、自身のヒント集合を提供します。ヒントは(key, value)のペアで規定されます。たとえば、 JPEGTranscoder はエンコーディング品質を制御するヒントを提供しています。

ErrorHandler -
このクラスは、トランスコード時に発生しうるエラーやウォーニングを取得する手段を提供します。デフォルト実装では提供されていますが、あなたは、たとえば、スタックトレースの代わりにダイアログを表示するようなハンドラを実装することができます。


	イメージトランスコーダAPIの使用方法

org.apache.batik.transcoder.image パッケージは、SVGドキュメントをJPEGやPNGのようなラスタイメージにトランスコードする、簡単な方法を提供します。それ以上のラスタイメージフォーマットは、ImageTranscoder のサブクラスを作って、writeImage メソッドを実装すれば追加できます。次のセクションでは、例の中でJPEGトランスコーダを使用しますが、PNGのトランスコーダも同じように動作します。


	イメージを生成する

以下の例では、JPEGTranscoder を利用してSVGドキュメントをJPEGイメージに変換する方法を示しています。

SaveAsJpeg.java
===============

import java.io.*;
import org.apache.batik.transcoder.image.JPEGTranscoder;
import org.apache.batik.transcoder.TranscoderInput;
import org.apache.batik.transcoder.TranscoderOutput;

public class SaveAsJPEG {

    public static void main(String [] args) throws Exception {

        // create a JPEG transcoder
        JPEGTranscoder t = new JPEGTranscoder();
        // set the transcoding hints
        t.addTranscodingHint(JPEGTranscoder.KEY_QUALITY,
                             new Float(.8));
        // create the transcoder input
        String svgURI = new File(args[0]).toURL().toString();
        TranscoderInput input = new TranscoderInput(svgURI);
        // create the transcoder output
        OutputStream ostream = new FileOutputStream("out.jpg");
        TranscoderOutput output = new TranscoderOutput(ostream);
        // save the image
        t.transcode(input, output);
        // flush and close the stream then exit
        ostream.flush();
        ostream.close();
        System.exit(0);
    }
}

このコードでは、JPEGTranscoder を生成してトランスコーディングヒントをセットしています。最初のヒントは、使用するXMLパーサを指定しています。 2番目のヒントは、エンコーディングの品質をセットしています。そして、入力と出力が生成されます。入力は、URIを示す、最初のコマンドライン引数を使用して生成されます。出力は、"out.jpg"というファイルを表すバイトストリームです。最後に、transcode メソッドが呼び出され、バイトストリームがクローズされます。

上記には示されませんでしたが、このプログラムは付加的なヒントとして、ユーザースタイルシートや、ドキュメントの言語、背景色などを指定することも可能です。

試してみてください:

このプログラムSaveAsJPEG.javaをコンパイルし、実行してみましょう。それにはSVGドキュメントが必要になるでしょう。
% java SaveAsJPEG <filename>.svg

out.jpgを見てみましょう。


	イメージのサイズを決定する

先の例に以下のコード業を追加することで、ラスタイメージのサイズを（ピクセルで）指定できます。この新しいトランスコーディングヒント KEY_WIDTH は、ラスタイメージの幅を指定させます。ラスタイメージの高さ（KEY_HEIGHTの使用）については、サポートされていませんが、トランスコーダはラスタイメージのディメンションを、そのSVGドキュメントのアスペクト比を維持することで、自動計算します。


	t.addTranscodingHint(JPEGTranscoder.KEY_WIDTH, new Integer(100));

このトランスコーダは、もしKEY_WIDTHを初期化することなしにKEY_HEIGHT を指定しても、同じ振る舞いをすることになります。いずれの場合でも（両方のキーが指定されても）、トランスコーダはSVGドキュメントのアスペクト比を保持します。


	特定の領域を選択する

イメージトランスコーダでは、特定の領域（すなわち、SVGドキュメントの一部分）を指定することができます。キーKEY_AOI で、レンダリングするSVGドキュメントのリージョンを選択することができます。このキーの値は、SVGドキュメントの空間で定義されたピクセルを用いて指定されたjava.awt.Rectangle でなければなりません。以下の例は、SVGドキュメントを4枚のタイルに分割する例を示します。

SaveAsJPEGTiles.java
====================

import java.io.*;
import java.awt.*;
import org.apache.batik.transcoder.image.JPEGTranscoder;
import org.apache.batik.transcoder.TranscoderInput;
import org.apache.batik.transcoder.TranscoderOutput;

public class SaveAsJPEGTiles {

    JPEGTranscoder trans = new JPEGTranscoder();

    public SaveAsJPEGTiles() {
        trans.addTranscodingHint(JPEGTranscoder.KEY_QUALITY,
                                 new Float(.8));
    }

    public void tile(String inputFilename,
                     String outputFilename,
                     Rectangle aoi) throws Exception {
        trans.addTranscodingHint(JPEGTranscoder.KEY_WIDTH,
                                 new Float(aoi.width));
        trans.addTranscodingHint(JPEGTranscoder.KEY_HEIGHT,
                                 new Float(aoi.height));
        trans.addTranscodingHint(JPEGTranscoder.KEY_AOI, aoi);
        String svgURI = new File(inputFilename).toURL().toString();
        TranscoderInput input = new TranscoderInput(svgURI);
        OutputStream ostream = new FileOutputStream(outputFilename);
        TranscoderOutput output = new TranscoderOutput(ostream);
        trans.transcode(input, output);
        ostream.flush();
        ostream.close();
    }

    public static void main(String [] args) throws Exception {
        SaveAsJPEGTiles p = new SaveAsJPEGTiles();
        String in = "samples/anne.svg";
        int documentWidth = 450;
        int documentHeight = 500;
        int dw2 = documentWidth / 2;
        int dh2 = documentHeight / 2;
        p.tile(in, "tileTopLeft.jpg", new Rectangle(0, 0, dw2, dh2));
        p.tile(in, "tileTopRight.jpg", new Rectangle(dw2, 0, dw2, dh2));
        p.tile(in, "tileBottomLeft.jpg", new Rectangle(0, dh2, dw2, dh2));
        p.tile(in, "tileBottomRight.jpg", new Rectangle(dw2, dh2, dw2, dh2));
        System.exit(0);
    }
}

このコードは、1つのドキュメント "anne.svg" を、同じサイズの4つのタイルに分割しています。このドキュメントとそのオリジナルサイズを考慮して、4つのリージョンを定義できます。それから、それぞれのリージョンについて、KEY_AOI キーを使用してラスタライズします。この特定した領域の幅と高さに等しくなるように（つまり1:1のズーム倍率で）、イメージの幅と高さについても指定していることに注意してください。もちろん、KEY_WIDTH, KEY_HEIGHT キーを KEY_AOIと組み合わせて使用することもできます。その場合、最初の特定した領域が、SVGドキュメントのレンダリングされる部分を決定します - そしてその部分は、指定されたラスタイメージのサイズに応じてズームインまたはズームアウトすることになります。

試してみてください:

プログラム SaveAsJPEGTiles.java をコンパイルして実行してみましょう。 "anne.svg" ドキュメントが必要になります。
% java SaveAsJPEGTiles

tileTopRight.jpg, tileTopRight.jpg, tileBottomRight.jpg, tileBottomLeft.jpg を見てみましょう。


	その他のトランスコーディングヒント

ImageTranscoder は、生成されるイメージをカスタマイズするための、さらなる TranscodingHints を提供しています。

ImageTranscoder.KEY_MEDIA -
このヒントは使用するCSSメディアを選択させてくれます。トランスコードするSVGドキュメントの作者は、CSS メディア規則を用いて、CSSメディアを制御できます。たとえば:

trans.addTranscodingHint(ImageTranscoder.KEY_MEDIA, "print");

ImageTranscoder.KEY_ALTERNATE_STYLESHEET -
このヒントは、トランスコードするSVGドキュメントの作者がxml-stylesheet 処理命令を用いて指定していた代替スタイルシートを選択させてくれます。たとえば:

trans.addTranscodingHint(ImageTranscoder.KEY_ALTERNATE_STYLESHEET, alternateStylesheetName);

ImageTranscoder.KEY_USER_STYLESHEET_URI -
このヒントはユーザースタイルシートを使用させてくれます。ユーザースタイルシートはトランスコードするSVGドキュメントのスタイルのいくつかを上書きできます。たとえば:

trans.addTranscodingHint(ImageTranscoder.KEY_USER_STYLESHEET_URI, "http://...");

ImageTranscoder.KEY_PIXEL_TO_MM -
このヒントは、ピクセルからミリメートルへの変換倍率を指定させてくれます。この倍率は単位長がどのようにピクセルに変換されるかを決定するのに用いられます。たとえば:

// 96dpi
trans.addTranscodingHint(ImageTranscoder.KEY_PIXEL_TO_MM, new Float(0.2645833f));
or
// 72dpi
trans.addTranscodingHint(ImageTranscoder.KEY_PIXEL_TO_MM, new Float(0.3528f));

ImageTranscoder.KEY_BACKGROUND_COLOR -
このヒントは、背景色を選択させてくれます。たとえば:

trans.addTranscodingHint(ImageTranscoder.KEY_BACKGROUND_COLOR, Color.white);


	SVG DOM ツリーからイメージを生成する

以下のコードはSVG DOMツリーを生成し保存します。

DOMRasterizer.java
==================

import java.io.*;
import org.apache.batik.transcoder.image.JPEGTranscoder;
import org.apache.batik.transcoder.TranscoderInput;
import org.apache.batik.transcoder.TranscoderOutput;
import org.apache.batik.dom.svg.SVGDOMImplementation;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.DOMImplementation;

public class DOMRasterizer {

    public Document createDocument() {
        DOMImplementation impl = SVGDOMImplementation.getDOMImplementation();
        String svgNS = SVGDOMImplementation.SVG_NAMESPACE_URI;
        Document document =
            impl.createDocument(svgNS, "svg", null);
        Element root = document.getDocumentElement();
        root.setAttributeNS(null, "width", "450");
        root.setAttributeNS(null, "height", "500");

        Element e;
        e = document.createElementNS(svgNS, "rect");
        e.setAttributeNS(null, "x", "10");
        e.setAttributeNS(null, "y", "10");
        e.setAttributeNS(null, "width", "200");
        e.setAttributeNS(null, "height", "300");
        e.setAttributeNS(null, "style", "fill:red;stroke:black;stroke-width:4");
        root.appendChild(e);

        e = document.createElementNS(svgNS, "circle");
        e.setAttributeNS(null, "cx", "225");
        e.setAttributeNS(null, "cy", "250");
        e.setAttributeNS(null, "r", "100");
        e.setAttributeNS(null, "style", "fill:green;fill-opacity:.5");
        root.appendChild(e);

        return document;
    }

    public void save(Document document) throws Exception {
        JPEGTranscoder t = new JPEGTranscoder();
        t.addTranscodingHint(JPEGTranscoder.KEY_QUALITY,
                             new Float(.8));
        TranscoderInput input = new TranscoderInput(document);
        OutputStream ostream = new FileOutputStream("out.jpg");
        TranscoderOutput output = new TranscoderOutput(ostream);
        t.transcode(input, output);
        ostream.flush();
        ostream.close();
    }

    public static void main(String [] args) throws Exception {
        DOMRasterizer rasterizer = new DOMRasterizer();
        Document document = rasterizer.createDocument();
        rasterizer.save(document);
        System.exit(0);
    }
}

このコードは2つの独立した部分に分かれます。

SVG DOM ツリーを生成する -

createDocument メソッドを参照
ここでは、3つのステップが必要とされます。最初は、 Batik SVG DOM 実装を(SVGDOMImplementation クラスを通して)取得する部分からなります。そうすると、org.w3c.dom.Document（これは結局 SVG の Document となります）を、svg ネームスペースURIと "svg" ドキュメントエレメントでcreateDocument メソッドを呼び出すことで生成できます。最後に、ドキュメントエレメントを取得して自分のDOMツリーの構築を始めることができます。

DOMをラスタライズする -

save メソッドを参照
先の例に類似して、TranscoderInput を、今回はSVG Documentから生成することによって、SVGドキュメントをラスタイメージにトランスコードできます。

試してみてください:

このプログラム DOMRasterizer.java をコンパイルして実行してみましょう。
% java DOMRasterizer

out.jpg を見てみましょう。