The dimensions of a page (aka the page boundaries) are defined in a page dictionary:
/MediaBox: the boundaries of the physical medium (the page). This value is mandatory, so you'll find it in every PDF./CropBox: the region that is visible when displayed or printed. The /CropBox is equal to or smaller than the /MediaBox. This value is optional; if it's missing, the /CropBox is equal to the /MediaBox.- Other possible values are the
/BleedBox, /TrimBox and /ArtBox. These have been defined for specific purposes, but they aren't used that often anymore. If they are missing, they default to the /CropBox. None of these values can outsize the /CropBox.
When you create a document with iText, you define the /MediaBox either explicitly or implicitly.
Explicitly:
Rectangle rect = new Rectangle(20, 20, 300, 600);
Document document = new Document(rect);
Implicitly:
Document document = new Document();
This single line is equivalent to:
Rectangle rect = new Rectangle(0, 0, 595, 842);
Document document = new Document(rect);
The four parameters passed to the Rectangle constructor (llx, lly, urx, ury) define a rectangle using the x and y coordinates of the lower-left and the upper-right corner.
In case of new Rectangle(0, 0, 595, 842), the lower-left corner of the page coincides with the origin of the coordinate system (0, 0). The upper-right corner of the page coincides with the coordinate (595, 842).
All measurements are defined in user units, and by default, the user units roughly corresponds with the typographic point: 1 user unit = 1 point.
Note the word roughly: we use points to do calculations, but in the ISO standard, we are very cautious not to use point as a synonym for user unit. For instance: an A4 page measures 595 by 842 user units, but if you'd calculate the exact value in points, there would be a slight difference (some numbers after the point).
The lower-left corner of the page isn't always the origin of the coordinate system. If we define a page using Rectangle(20, 20, 300, 600), the origin is 20 user units below and 20 user units to the left of the lower-left corner. It's also possible to use negative values to define a page size.
For instance: suppose that you want to create an A2 document consisting of 4 A4 pages, than you could define the page sizes like this:
Rectangle(-595, 0, 0, 842) Rectangle(0, 0, 595, 842)
Rectangle(-595, -842, 0, 0) Rectangle(0, -842, 595, 0);
By defining the media box like this, you also pass information with respect to the relative position of the different pages. If you look at the 4 A4 pages as a unit, the origin of the coordinate system is the exact center of the A2 page.
Important:
All of the above assumes that you didn't introduce any coordinate transformations, e.g. using the concatCTM() or transform() method. These methods allow you to change the coordinate system, for instance change the angle between the x and y axis from 90 degrees (the default) to another angle. You can also scale an axis to get a different aspect ratio. While it's certainly fun to do this, it requires quite some Math.
