http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Overview
FAQ
License
Download
Install
Demo

In the news

Tools and Apps
Browser
Rasterizer
Font Converter
Pretty-printer

Architecture
Generator
DOM API
Scripting
JSVGCanvas
Transcoder API

Extensions

Testing

Contributors
Mail Lists

CVS Repository
Bug Database

Status

Glossary


イントロダクション

トランスコーダ API(パッケージorg.apache.batik.transcoder) のゴールは、入力から出力へのトランスコーディングのための一般的なAPIを提供することです。まず、このドキュメントではTranscoder, TranscoderInput そして TranscoderOutput が定義する -- そして全てのトランスコーダが共通にする -- 基本的なトランスコーダAPIについて説明します。その次に、SVGドキュメントのフラグメントをJPEGやPNGのようなラスタ イメージにラスタライズさせてくれるイメージ トランスコーダAPI(パッケージorg.apache.batik.transcoder.image) の使い方について説明します。


トランスコーダ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 メソッドが呼び出され、バイトストリームがクローズされます。

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

    試してみてください:

    1. このプログラムSaveAsJPEG.javaをコンパイルし、実行してみましょう。それにはSVGドキュメントが必要になるでしょう。
      % java SaveAsJPEG <filename>.svg
    2. 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ドキュメントのレンダリングされる部分を決定します - そしてその部分は、指定されたラスタ イメージのサイズに応じてズームインまたはズームアウトすることになります。

    試してみてください:

    1. プログラム SaveAsJPEGTiles.java をコンパイルして実行してみましょう。 "anne.svg" ドキュメントが必要になります。
      % java SaveAsJPEGTiles
    2. 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ドキュメントをラスタ イメージにトランスコードできます。

    試してみてください:

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



    Copyright © 2000-2001 The Apache Software Foundation. All Rights Reserved.