# Tutorial: iText by Example

## Images

Images:
iText supports different kinds of image formats (even formats that aren't limited to images):

- JPEG: Joint Photographic Experts Group. Commonly used to refer to a lossy compression technique, reducing the size of a graphic file by as much as 96%. Usually the best file format for photographs on the Web.
- GIF: Graphic Interchange Format. A common format for image files, especially suitable for images containing large areas of the same color. GIF format files of simple images are often smaller than the same file would be if stored in JPEG format, but GIF format does not store photographic images as well as JPEG.
- PNG: Portable Network Graphics. A graphics format designed as the successor to GIF. It features compression, transparency, and progressive loading, like GIF, but it is free of patent restrictions.
- TIFF: Tagged Image File Format. A file format commonly used for digital scanned images.
- BMP: Windows bitmap. A common form of bitmap file in Microsoft Windows. Poorly supported by other operating systems and with limited support for colour.
- WMF: Windows Metafile Format. A vector graphics format for Windows-compatible computers used mostly for word-processing clip art.
- basic support for EPS: Encapsulated PostScript; a graphics format that describes an image in the PostScript language.
- java.awt.Image: a JAVA object that is in the JDK from SUN
- com.lowagie.text.pdf.PdfTemplate: a sequence of PDF syntax, defined in a PdfTemplate can be wrapped in an Image
- com.lowagie.text.pdf.Barcode: an abstract class, check the implementing classes to know what types of barcodes are supported

An Image can be created with one of the getInstance-methods. Image is an abstract class, so the getInstance method will detect the type of the given image (Jpeg, WMF,...) and return the corresponding object (Jpeg, ImgWMF,...). Lots of PDF libraries decompress images and change them into a Bitmap-like format before adding them to the PDF-file. This approach is avoided in iText, because it results in huge PDF files. The size of the resulting file is tens of times larger than the sum of the different images. This is not the case with iText. Identical Images are also reused (there's only one Image XObject) to save space.
Example: java com.lowagie.examples.objects.images.Images
Adds different formats of images to a document.: see Images.pdf
External resources for this example: otsoe.jpg iText.bmp pngnow.png iText.tif getacro.gif iText.wmf
The most common way to get an Image instance, is to use the path to the file (getInstance(java.lang.String)) or the URL (getInstance(java.net.URL)), but you can also create an Image using the raw image data (for instance if you have an Image stored in a database):
Example: java com.lowagie.examples.objects.images.RawData
Using raw image data to construct an Image object.: see rawdata.pdf
External resources for this example: otsoe.jpg
As iText is a JAVA library, the java.awt.Image object is also supported, but be careful when you are using this functionality on UNIX/Linux systems. As you know you may need some special X requirements when using the java.awt.Toolkit for creating a java.awt.Image. If you stick to com.lowagie.text.Image, you don't need this extra requirement; you can use com.lowagie.text.Image on every platform.
Example: java com.lowagie.examples.objects.images.AwtImage
Using a java.awt.Image object to construct an Image object.: see awt_image.pdf
External resources for this example: H.gif
Go to top of the page
Image alignment:
You can set the alignment of an image with setAlignment(int). As parameter, you can use one of the self explaining constants LEFT, RIGHT or MIDDLE
Example: java com.lowagie.examples.objects.images.Alignment
Alignment of images.: see alignment.pdf
External resources for this example: vonnegut.gif otsoe.jpg hitchcock.png
You can combine these alignment constants with TEXTWRAP or UNDERLYING. With the first constant, you can have the text wrapped around the image. With the second constant, you specify that the text should cover the image. Both constants are illustrated in the following example:
Example: java com.lowagie.examples.objects.images.ImagesAlignment
Alignment and wrapping of images.: see imagesAlignment.pdf
External resources for this example: vonnegut.gif otsoe.jpg hitchcock.png
If you don't specify an absolute position for the image, iText tries to add it at the position of the current pointer. However, it is not certain that there will be enough space to add the image. In that case iText postpones adding the image and adds other content first. If you really want the Image to be added at the moment you are calling the add-method, you have to set the writer to use the strict image sequence:

    writer.setStrictImageSequence(true);

Look at the example to see the difference between the default behaviour of iText and the behaviour when the strict image sequence is set:
Example: java com.lowagie.examples.objects.images.ImageSequence
Adds images to a document, once respecting the order in which they were added, once in the default order.: see inSequence.pdf NotInSequence.pdf
External resources for this example: otsoe.jpg getacro.gif
Go to top of the page
Image transformations:
You can also add an Image at an absolute position on the page, regardless of the other content. In the chapter on coordinate systems the mechanisms of the transformation matrix that allow you to do this are explained in detail, but maybe that's overkill. You probably don't need all that math. You will probably only need simple translations, some scaling or basic rotating.
Translation
One thing you must know about the coordinate system is the place of the origin: it's in the lower left corner. The parameters of the method setAbsolutePosition(float, float) define the lowerleft corner of the image.
Example: java com.lowagie.examples.objects.images.AbsolutePositions
Adding an Image at absolute positions.: see absolutepositions.pdf
External resources for this example: hitchcock.png
Scaling
If you want to scale the image to a size of your own choice, use on of the scaleAbsolute[Width|Height]-methods. If you want to scale the image to a certain percentage, use on of the scalePercent-methods.
Remark that the resolution of an image that is added without scaling will be 72dpi by default. If an image is placed with a scaling of 50% the the resolution will be 144. With lower scalings the resolution will increase because the pixels are the same but the size will be smaller. To put a picture with 300dpi use a scaling of 72/300=24%. For instance: if you have a 5X5 inch image that you scan at 300 dpi, the resultant image is 1500X1500 pixels (5X300 = 1500). When you place this image in the pdf with a scaling of 24% (72/300 = 0.24), the image in the pdf will be 5X5 inch with 1500X1500 pixel at 300 dpi. The image will always be 1500X1500 pixel whatever the size.
Example: java com.lowagie.examples.objects.images.Scaling
Scaling images.: see scaling.pdf
External resources for this example: otsoe.jpg
Another usefull method for scaling is scaleToFit. This method will scale the image to fit a rectangle, but will keep the XY-ratio intact. Remark that the Images used for the next example are not my own. They are used by courtesy of www.bigfoto.com.
Example: java com.lowagie.examples.objects.images.DvdCover dvdcover.pdf My Sunflower Movie 808080 sunflower-front.jpg sunflower-back.jpg
Make a DVD Cover.: see dvdcover.pdf
External resources for this example: sunflower-front.jpg sunflower-back.jpg
Rotating
You can rotate an Image with one of these methods: setRotation(float) (angle in radians) or setRotationDegrees(float) (angle in degrees).
Example: java com.lowagie.examples.objects.images.Rotating
Rotating images.: see rotating.pdf
External resources for this example: otsoe.jpg
Go to top of the page
Some special features:
Clickable images
If you want a clickable image or you want to add an annotation to an image, you have to construct an Annotation-object and add it to the image. You don't need to specify a position (you can take 0, 0, 0, 0). The position will be internally updated to fit the image. See the method setAnnotation(com.lowagie.text.Annotation) and the chapter on annotations.
Example: java com.lowagie.examples.objects.images.AnnotatedImage
images and annotations.: see annotated_images.pdf
External resources for this example: otsoe.jpg iText.wmf
Image inside a Chunk
In some cases it can be handy to wrap an image inside a Chunk. Just create a Chunk with an image and an offset with one of the Chunk constructors that take an Image as parameter.
Example: java com.lowagie.examples.objects.images.ImageChunks
Images wrapped in a Chunk.: see imageChunks.pdf
External resources for this example: pngnow.png
Image masks
You can create an Image that can be used as mask, making another image transparent:

|  |  |  |  |  |  |  | 3C
|  |  |  |  |  |  |  | 7E
|  |  |  |  |  |  |  | E7
|  |  |  |  |  |  |  | C3
|  |  |  |  |  |  |  | C3
|  |  |  |  |  |  |  | E7
|  |  |  |  |  |  |  | 7E
|  |  |  |  |  |  |  | 3C

This image has a size of 8 by 8 pixels, 1 component and 1 byte per component. Using the method makeMask(), it can be turned into a mask:

    byte maskr[] =
       {(byte)0x3c,
        (byte)0x7e,
        (byte)0xe7,
        (byte)0xc3,
        (byte)0xc3,
        (byte)0xe7,
        (byte)0x7e,
        (byte)0x3c};
    Image mask = Image.getInstance(8, 8, 1, 1, maskr);
    mask.makeMask();
    mask.setInvertMask(true);

We can use this mask for explicit masking to clip some parts of an image:

    PdfContentByte cb = writer.getDirectContent();
    Image image = Image.getInstance("vonnegut.gif");
    image.setImageMask(mask);

In the chapter on colors and patterns, the concept of stencil masks is discussed. You can use the mask we created from an Image for stencil masking:

    PdfContentByte cb = writer.getDirectContent();
    cb.setRGBColorFill(255, 0, 0);
    cb.addImage(mask, mask.scaledWidth() * 8, 0, 0, mask.scaledHeight() * 8, 100, 400);

(Remark that for the addImage method, you will need to read more about coordinate systems...)
Example: java com.lowagie.examples.objects.images.ImageMasks
Applying a mask to an image.: see maskedImages.pdf
External resources for this example: otsoe.jpg
Selected examples
EPS, Tiff and barcode functionality is discussed in a separate chapter.
Go to top of the page
Amazon books: