iText Tutorial: Coordinate Systems

PDF において新しいページが始まるとき、CTM (現在の変換行列) は、ユーザ座標系からデバイス座標系へポジションをマッピングします。既定では、座標系の原点は、ページの左下の角です。x-軸は水平方向右へ、y-軸は垂直方向上へ伸びています。すべての測量単位は、ポイントです。これは、iText固有の選択ではなく、PDF Reference Manual, 4.2節座標系で文書化されています。

Example: java com.lowagie.examples.directcontent.coordinates.XandYcoordinates
Puts some marks at specific X and Y coordinates; connects the marks with a line and puts some text next to the marks: see XandY.pdf

例で得られたPDFを印刷し、その位置を測ってみると、下からあるいは左からの距離は、いつも正しいわけではないことがわかるでしょう。Adobeの印刷ダイアログは、（"用紙にあわせる"などの）いくつかのオプションがありますが、それにより印刷結果は異なりますので、注意が必要です。

先頭に戻る

変換

CTMを変更するに、いくつ方法がありますが、そのひとつに concatCTM(float, float, float, float, float, float) メソッドがあります。例えば、原点を左上、y-軸の方向を変更したいときには、PdfContentByte を得た後に、このメソッドを使います。

cb.concatCTM(1f, 0f, 0f, -1f, 0f, PageSize.A4.height());

このように、新しい変換行列を適用した状態で、最初の例と同じコードを実行すると、上下さかさまで、テキストが鏡文字になります。

Example: java com.lowagie.examples.directcontent.coordinates.UpsideDown
Same example as above, but now the origin is in the upper left corner: see upsidedown.pdf

このような変換は、アフィン変換と呼ばれ、17歳ぐらいに学校で習ったはずです。あなたの記憶を呼び覚ますために、いくつかの数式を示します。

イメージやテキストの移動、スケーリング(拡大･縮小)、回転をしたいときには、変換行列を使う必要があります。iText の変換を含んでいるほとんどのメソッドは a, b, c, d, e および f のパラメータをとります。これらのパラメータは、変換行列の要素です。

[	a	b	0	]
	c	d	0
	e	f	1

われわれは、2次元変換にしか興味がなく、3次元については議論をしないので、三番目の列は、固定化されています。パラメータ e と f により、移動を指定します。次の行列は、x-方向に e ピクセル、y-方向に f ピクセル移動します。

[	1	0	0	]
	0	1	0
	e	f	1

a と d のパラメータは、スケーリングに使います。次の行列は、x-方向に2倍、y-方向に3倍拡大します。

[	2	0	0	]
	0	3	0
	0	0	1

何かを回転させたいときには、a, b, c と d を変更します。angle をラジアンで表した回転角度とすると、行列は、次のようになります。

[	Math.cos(angle)	Math.sin(angle)	0	]
	-Math.sin(angle)	Math.cos(angle)	0
	0	0	1

オブジェクトを回転させる場合の、座標系の回転軸は (0, 0) にあるという警告: 何かを回転させるときには、ページの外へ回転してしまわないかを用心してください。ページ上にとどめるために、移動の処理が必要になるでしょう。もちろん、移動 (tX, tY)、スケーリング (sX, sY)、回転 (angle)をひとつの行列にまとめることもできます。

[	sX * Math.cos(angle)	sY * Math.sin(angle)	0	]
	-sX * Math.sin(angle)	sY * Math.cos(angle)	0
	tX	tY	1

なので、次のようなパラメータになります。

a = sX * Math.cos(angle);
b = sY * Math.sin(angle);
c = -sX * Math.sin(angle);
d = sY * Math.cos(angle)
e = tX;
f = tY;

CTMを変更するほかの方法として、transform(java.awt.geom.AffineTransform) を使うこともできます。AffineTransform は、JDK のオブジェクトです。ある getInstance メソッドでインスタンス化するこのオブジェクトは、理解が簡単です。座標系のスケーリングをしたいときには、'スケールインスタンス' を得るだけです。

cb.transform(AffineTransform.getScaleInstance(1.2, 0.75));

Check SUN's API for more information.

Example: java com.lowagie.examples.directcontent.coordinates.AffineTransformation
Same example as above, but now the X and Y coordinates are scaled: see affinetransformation.pdf

先頭に戻る

PdfTemplate の追加

上記で説明したことはかなり理屈っぽく見えますが、この部で紹介しなければならないことです。PdfTemplate を使うならば、変換行列も必要になるでしょう。これまでは、PdfTemplate を追加するメソッドとして PdfContentByte.addTemplate(com.lowagie.text.pdf.PdfTemplate, float, float) だけを使ってきました。このメソッドは、次の行列を使って移動をします。

[	1	0	0	]
	0	1	0
	x	y	1

実際、このメソッドはより洗練されたメソッドである addTemplate(com.lowagie.text.pdf.PdfTemplate, float, float, float, float, float, float) を呼び出します。
cb.addTemplate(template, x, y) の代わりに、cb.addTemplate(template, 1, 0, 0, 1, x, y) を呼び出すこともできます。（これは、実際にiTextが内部で行っています。）このメソッドのパラメータ (a, b, c, d, e, f) の値は、すでに説明した通りです。

Example: java com.lowagie.examples.directcontent.coordinates.Transformations
Add a template using different transformation matrices: see transformations.pdf

先頭に戻る

イメージの追加

これまで、PdfTemplateオブジェクトについて説明してきましたが、Imageオブジェクトにも当てはまります。addImage(com.lowagie.text.Image) というメソッドがありますが、これは、（最初に、setAbsolutePosition(float, float) メソッドを呼び出したのならば）イメージを絶対位置へ追加します。addImage(com.lowagie.text.Image, float, float, float, float, float, float) は、イメージを変換することができます。

Example: java com.lowagie.examples.directcontent.coordinates.TransformImage
Add an image using different transformation matrices: see transformimage.pdf
External resources for this example: hitchcock.png

これは、非常に取り扱いにくい機能であり、PdfTemplate でもできることです。しかし、イメージを変換したいときにはiTextによる変換行列の構築を任せたほうがよでしょう。Image クラスには、イメージの変換をするために必要なほとんどのことを行うためのメソッドを持っています。

先頭に戻る