<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>iText Tutorial: Coordinate Systems</title><meta name="Description" content="Coordinate Systems - changing the Current Transformation Matrix (CTM)"><meta name="Keywords" content="PDF, JAVA, iText, examples, PdfContentByte, transformation matrix, coordinate systems, Lowagie, Bruno"><link rel="stylesheet" href="./../../style.css" type="text/css"></head><body><a name="top" class="logo" href="http://www.lowagie.com/iText"><img src="http://www.lowagie.com/iText/images/logo.gif" border="0" alt="iText"></a><h1>Tutorial: iText by Example</h1><h2>Coordinate Systems</h2><div id="content"><div id="sidebar"><a class="toc" href="./../../index.html#directcontent_coordinates">
Table of Contents
</a><div align="Center" class="small">Best viewed with:<br><script type="text/javascript"><!--
google_ad_client = "pub-0340380473790570";
google_ad_width = 180;
google_ad_height = 60;
google_ad_format = "180x60_as_rimg";
google_cpa_choice = "CAAQyaj8zwEaCIwcWMzeycafKMu293M";
//--></script><script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script></div><div class="sidetitle">Sections:</div><ul><li><a href="#inaction">In the book</a></li><li><a href="#xycoordinates">The coordinate system</a></li><li><a href="#transform">Transformations</a></li><li><a href="#templates">Adding PdfTemplates</a></li><li><a href="#images">Adding Images</a></li></ul><br><br><div class="sidetitle">Examples:</div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/XandYcoordinates.java">XandYcoordinates</a><br><div class="description">Puts some marks at specific X and Y coordinates; connects the marks with a line and puts some text next to the marks</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/XandY.pdf">XandY.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/UpsideDown.java">UpsideDown</a><br><div class="description">Same example as above, but now the origin is in the upper left corner</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/upsidedown.pdf">upsidedown.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/AffineTransformation.java">AffineTransformation</a><br><div class="description">Same example as above, but now the X and Y coordinates are scaled</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/affinetransformation.pdf">affinetransformation.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/Transformations.java">Transformations</a><br><div class="description">Add a template using different transformation matrices</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/transformations.pdf">transformations.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/TransformImage.java">TransformImage</a><br><div class="description">Add an image using different transformation matrices</div><div class="small">Input:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/hitchcock.png">hitchcock.png</a></li></ul><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/transformimage.pdf">transformimage.pdf</a></li></ul></div><div class="example"><div class="small">ANT script (all examples):</div><ul><li><a href="./../../directcontent/coordinates/build.xml">
build.xml
</a></li></ul></div></div><div id="main"><a name="inaction"></a><div class="title">In the book:</div><div xmlns="http://www.w3.org/1999/xhtml" xmlns:site="http://www.lowagie.com/iText/site">
<p xmlns=""><a href="http://itext.ugent.be/itext-in-action/"><img src="http://itext.ugent.be/img/lowagie_3d.jpg" border="0" align="right"></a>
The examples in this free online tutorial will help you getting started
with iText. Note that most examples are two years old.
Some of the examples may be obsolete. Also the theory that
comes with the examples isn't always 100% accurate.
If you want more recent examples or if you want to know more
about the theoretical background of PDF and iText, please consult the book
<a href="http://itext.ugent.be/itext-in-action/">
"iText in Action".
</a>
Note that the first and the third chapter of the book
can be downloaded for free from <a href="http://www.manning.com/affiliate/idevaffiliate.php?id=223_53">http://manning.com/lowagie/</a></p><p>
More specifically:
<ul><li><a class="subtitle" href="http://itext.ugent.be/itext-in-action/chapter.php?chapter=10">
Chapter 10:
</a>Constructing and painting paths</li></ul></p>
</div><a class="top" href="#top">Go to top of the page</a><a name="xycoordinates"></a><div class="title">The coordinate system:</div><div xmlns="http://www.w3.org/1999/xhtml">
See PDF Reference Manual (version 1.6) p169:
<blockquote>Coordinate systems define the canvas on which all painting occurs.
They determine the position, orientation, and size of the text, graphics, and
images that appear on a page.</blockquote>
If you start a new page in PDF, the CTM (current transformation matrix)
maps positions from user coordinates to device coordinates. The origin of
the coordinate system is in the lower left corner of the page by default.
The x-axis is oriented horizontally to the right, the y-axis vertically
to the upper left corner. All measurements are done in points.
This is not an iText specific choice. All this is documented in the PDF Reference Manual,
section 4.2 Coordinate Systems.
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/XandYcoordinates.java">
com.lowagie.examples.directcontent.coordinates.XandYcoordinates</a><br>Puts some marks at specific X and Y coordinates; connects the marks with a line and puts some text next to the marks: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/XandY.pdf">XandY.pdf</a><br></div>
If you print the resulting PDF of the example and measure the locations on the page,
you will see that the distances measured from the bottom or the left side of the page
are not always correct. Adobe's print dialog has several options (like "fit to paper")
that change the printed result, so be careful!<br xmlns="http://www.w3.org/1999/xhtml">
</div><a class="top" href="#top">Go to top of the page</a><a xmlns="" name="transform"></a><div class="title">Transformations:</div><div xmlns="http://www.w3.org/1999/xhtml">
There are different ways to change the CTM.<br>
You can use the method
<a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#concatCTM(float,%20float,%20float,%20float,%20float,%20float)">concatCTM(float, float, float, float, float, float)</a>.
For instance, if you want to shift the origin to the upper left corner and change the orientation of the y-axis,
you can use this statement right after getting the PdfContentByte:
<pre xmlns="http://www.w3.org/1999/xhtml" class="commandline">cb.concatCTM(1f, 0f, 0f, -1f, 0f, PageSize.A4.height());</pre>
If we take the same code as in the first example, but apply this new transformation matrix, we see that
everything is upside-down now and all text is mirrored.
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/UpsideDown.java">
com.lowagie.examples.directcontent.coordinates.UpsideDown</a><br>Same example as above, but now the origin is in the upper left corner: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/upsidedown.pdf">upsidedown.pdf</a><br></div>
These transformations are called <i xmlns="http://www.w3.org/1999/xhtml">affine transformations</i>
and you should have learnt about them at school when you were about 17 years old.
If you want to freshen up your memory, I've got some algebra for you:<br><br>
if you want to translate, scale or rotate images or text, you need to use a Transformation Matrix.
Most iText methods involving transformations ask you for the parameters a, b, c, d, e and f.
Those parameters are elements of the Transformation Matrix:<br>
<table>
<tr>
<td rowspan="3" valign="middle"><font size="+4">[</font></td>
<td>a</td>
<td>b</td>
<td>0</td>
<td rowspan="3" valign="middle"><font size="+4">]</font></td>
</tr>
<tr>
<td>c</td>
<td>d</td>
<td>0</td>
</tr>
<tr>
<td>e</td>
<td>f</td>
<td>1</td>
</tr>
</table>
The third column is fixed because we are only interested in 2D transformations,
we are not discussing 3D here.
With the parameters e and f, you can specify a translation.
The following matrix moves everything e pixels in x-direction and f pixels
in y-direction.
<table>
<tr>
<td rowspan="3" valign="middle"><font size="+4">[</font></td>
<td>1</td>
<td>0</td>
<td>0</td>
<td rowspan="3" valign="middle"><font size="+4">]</font></td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td>e</td>
<td>f</td>
<td>1</td>
</tr>
</table>
You can use the a and d parameter to scale.
The following matrix doubles everything in x-direction and triples everything in y-direction:
<table>
<tr>
<td rowspan="3" valign="middle"><font size="+4">[</font></td>
<td>2</td>
<td>0</td>
<td>0</td>
<td rowspan="3" valign="middle"><font size="+4">]</font></td>
</tr>
<tr>
<td>0</td>
<td>3</td>
<td>0</td>
</tr>
<tr>
<td>0</td>
<td>0</td>
<td>1</td>
</tr>
</table>
If you want to rotate something, you have to change a, b, c and d.
With angle equals to the rotation angle in radians, you have a matrix like this:
<table>
<tr>
<td rowspan="3" valign="middle"><font size="+4">[</font></td>
<td>Math.cos(angle)</td>
<td>Math.sin(angle)</td>
<td>0</td>
<td rowspan="3" valign="middle"><font size="+4">]</font></td>
</tr>
<tr>
<td>-Math.sin(angle)</td>
<td>Math.cos(angle)</td>
<td>0</td>
</tr>
<tr>
<td>0</td>
<td>0</td>
<td>1</td>
</tr>
</table>
There is one serious caveat when you rotate an object: the coordinate of the
rotation pivot is (0, 0). If you rotate something, you have to watch out that
it is not rotated 'off' your page. you may have to perform a
translation to keep the object on the page.
Of course you can combine translation (tX, tY), scaling (sX, sY) rotation (angle) in one matrix:
<table>
<tr>
<td rowspan="3" valign="middle"><font size="+4">[</font></td>
<td>sX * Math.cos(angle)</td>
<td>sY * Math.sin(angle)</td>
<td>0</td>
<td rowspan="3" valign="middle"><font size="+4">]</font></td>
</tr>
<tr>
<td>-sX * Math.sin(angle)</td>
<td>sY * Math.cos(angle)</td>
<td>0</td>
</tr>
<tr>
<td>tX</td>
<td>tY</td>
<td>1</td>
</tr>
</table>
So you will have to use these parameters:
<ul>
<li>a = sX * Math.cos(angle);</li>
<li>b = sY * Math.sin(angle);</li>
<li>c = -sX * Math.sin(angle);</li>
<li>d = sY * Math.cos(angle)</li>
<li>e = tX;</li>
<li>f = tY;</li>
</ul><br>
<br>
Another way to change the CTM is by using
<a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#transform(java.awt.geom.AffineTransform)">transform(java.awt.geom.AffineTransform)</a>
As you can see AffineTransform is an object in the JDK.
It comes with some getInstance methods that are easier to understand.
If you want a scale coordinate system, just get a 'scale instance':
<pre xmlns="http://www.w3.org/1999/xhtml" class="commandline">cb.transform(AffineTransform.getScaleInstance(1.2, 0.75));</pre>
Check SUN's API for more information.
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/AffineTransformation.java">
com.lowagie.examples.directcontent.coordinates.AffineTransformation</a><br>Same example as above, but now the X and Y coordinates are scaled: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/affinetransformation.pdf">affinetransformation.pdf</a><br></div>
</div><a class="top" href="#top">Go to top of the page</a><a name="templates"></a><div class="title">Adding PdfTemplates:</div><div xmlns="http://www.w3.org/1999/xhtml">
The stuff above probably seems rather theoretical, but it was a necessary introduction
to this part: if you are using PdfTemplates, you are going to need a transformation matrix.
Up till now, we only have used this method to add a PdfTemplate:
<a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#addTemplate(com.lowagie.text.pdf.PdfTemplate,%20float,%20float)">PdfContentByte.addTemplate(com.lowagie.text.pdf.PdfTemplate, float, float)</a>.
This method performs a translation, using this matrix:
<table xmlns="http://www.w3.org/1999/xhtml">
<tr>
<td rowspan="3" valign="middle"><font size="+4">[</font></td>
<td>1</td>
<td>0</td>
<td>0</td>
<td rowspan="3" valign="middle"><font size="+4">]</font></td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td>x</td>
<td>y</td>
<td>1</td>
</tr>
</table>
In fact, the method just calls the more sophisticated method:
<a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#addTemplate(com.lowagie.text.pdf.PdfTemplate,%20float,%20float,%20float,%20float,%20float,%20float)">addTemplate(com.lowagie.text.pdf.PdfTemplate, float, float, float, float, float, float)</a>.<br xmlns="http://www.w3.org/1999/xhtml">
Instead of <span class="commandline">cb.addTemplate(template, x, y)</span>, you could call
<span class="commandline">cb.addTemplate(template, 1, 0, 0, 1, x, y)</span> (that's exactly what happens internally in iText).
The parameters in this method are the (a, b, c, d, e, f) values
as explained <a xmlns="" href="./../../directcontent/coordinates/index.html#transform">above</a>.
<div id="example">
Example: java
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/Transformations.java">
com.lowagie.examples.directcontent.coordinates.Transformations</a><br>Add a template using different transformation matrices: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/transformations.pdf">transformations.pdf</a><br></div></div><a class="top" href="#top">Go to top of the page</a><a name="images"></a><div class="title">Adding Images:</div><div xmlns="http://www.w3.org/1999/xhtml">
What was explained for PdfTemplate objects also goes for Image objects.
There's a method <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#addImage(com.lowagie.text.Image)">addImage(com.lowagie.text.Image)</a>
that adds the Image at an absolute position (provided that you used
<a href="http://itext.ugent.be/library/api/com/lowagie/text/Image.html#setAbsolutePosition(float,%20float)">setAbsolutePosition(float, float)</a> first).
But there's also <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#addImage(com.lowagie.text.Image,%20float,%20float,%20float,%20float,%20float,%20float)">addImage(com.lowagie.text.Image, float, float, float, float, float, float)</a>
that allows you to transform the Image.
<div id="example">
Example: java
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/TransformImage.java">
com.lowagie.examples.directcontent.coordinates.TransformImage</a><br>Add an image using different transformation matrices: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/transformimage.pdf">transformimage.pdf</a><br>
External resources for this example:
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/coordinates/hitchcock.png">hitchcock.png</a><br></div>
This is very tricky stuff. It's doable for PdfTemplates, but if you want to transform Images,
you'd better trust on iText to construct the transformation matrix.
Class Image has sufficient methods to perform most of the
<a href="./../../objects/images/index.html#transformations">Image transformations</a>
you are going to need.
</div><a class="top" href="#top">Go to top of the page</a><div id="footer" xmlns="http://www.w3.org/1999/xhtml">
Page Updated: 2006/09/17 10:13:59
Copyright © 1999-2005
Bruno Lowagie<br><a href="http://www.lowagie.com/iText/">iText</a> is a Free Java-Pdf library by Bruno Lowagie and Paulo Soares.
</div></div></div><div class="commercial"><br><script type="text/javascript"><!--
google_ad_client = "pub-0340380473790570";
google_ad_width = 120;
google_ad_height = 600;
google_ad_format = "120x600_as";
google_ad_channel ="";
google_ad_type = "text_image";
google_color_border = "FFFFFF";
google_color_bg = "FFFFFF";
google_color_link = "1B09BD";
google_color_url = "100670";
google_color_text = "707070";
//--></script><script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script><br><br><div class="subtitle">Amazon books:</div><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=8&l=as1&asins=1932394796&fc1=000000&lc1=0000ff&bc1=<1=_blank&IS2=1&bg1=ffffff&f=ifr" width="120" height="240" scrolling="no" marginwidth="0" marginheight="0" frameborder="0" align="Center"></iframe>');
//--></script><a xmlns="" href="http://www.amazon.co.uk/exec/obidos/ASIN/1932394796/catloogjecom-21" class="amazonlinks">
amazon.co.uk-link
</a><br><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=8&l=as1&asins=0321304748&fc1=000000&lc1=0000ff&bc1=<1=_blank&IS2=1&bg1=ffffff&f=ifr" width="120" height="240" scrolling="no" marginwidth="0" marginheight="0" frameborder="0" align="Center"></iframe>');
//--></script><a href="http://www.amazon.co.uk/exec/obidos/ASIN/0321304748/catloogjecom-21" class="amazonlinks">
amazon.co.uk-link
</a><br><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=10&l=st1&mode=books&search=PDF&=1&fc1=&lc1=<1=&bg1=&f=ifr" width="120" height="460" border="0" frameborder="0" style="border:none;" scrolling="no" marginwidth="0" marginheight="0"></iframe>');
//--></script><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=10&l=st1&mode=books&search=Coordinate Systems&=1&fc1=&lc1=<1=&bg1=&f=ifr" width="120" height="460" border="0" frameborder="0" style="border:none;" scrolling="no" marginwidth="0" marginheight="0"></iframe>');
//--></script><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=10&l=st1&mode=books&search=Algebra&=1&fc1=&lc1=<1=&bg1=&f=ifr" width="120" height="460" border="0" frameborder="0" style="border:none;" scrolling="no" marginwidth="0" marginheight="0"></iframe>');
//--></script><br></div></body></html>
