2.4 Image Support

Displaying images in the PDF document is handled by the PdfImage class. This class is a PDF resource. Image sources can be:

• Image file
• .NET Image derived class such as Bitmap
• A Boolean array of black and white pixels
• QRCode barcode represented by QREncoder class
• PDF 417 barcode represented by Pdf417Encoder class
• PdfChart is a derived class of PdfImage
• PdfPrintDocument is using internally PdfImage to capture print pages

Images are saved to the PDF file in one of the following formats:

• Jpeg format (lossy compression)
• Indexed bitmap (Lossless compression)
• Gray bitmap (Lossless compression)
• Black and white bitmap (Lossless compression)

Color pictures should be saved in Jpeg format. To control the size of your image, you can reduce the resolution or change the image quality. Color pictures can be saved in shades of gray. Data size is cut by three, but you lose the color. If the image was created programmatically as in charts, and the number of colors is less than 256 the image can be saved as an indexed bitmap. Each color is represented by one byte (or less) compare to 3 bytes. This can result in a very significant file size reduction. For example, the ChartExample.pdf file is reduced from 642KB to 72KB. If the image is black and white as in PdfPrintDocument images of text, the image can be saved as BWImage. In the case of PrintExample.pdf the Jpeg file is 1795KB and the black and white version is 66KB.

Adding an image to your PDF File

Create a PdfImage class.

// create PdfImage object
PdfImage MyImage = new PdfImage(Document);

Set optional parameters if required. All the parameters have a default value.

// saved image format (default SaveImageAs.Jpeg)
// other choices are: IndexedImage, GrayImage, BWImage
MyImage.SaveAs = SaveImageAs.Jpeg;

// Crop rectangle is the image area to be cropped.
// The default is no crop (empty rectangle).
// The origin is at top left and Y axis is pointing down.
// The dimensions are in pixels.
// The crop rectangle must be contained within the image.
MyImage.CropRec = new Rectangle(x, y, width, height);

// Crop percent rectangle is the image area to be cropped.
// The default is no crop (empty rectangle).
// The origin is at top left and Y axis is pointing down.
// The dimensions are in percent of image.
// The crop rectangle must be contained within the image.
MyImage.CropPercent = new RectangleF(x, y, width, height);

// Image Quality is an integer in the range of 0 to 100.
// representing poor to best quality image.
// The default (-1) is save image with Bitmap default quality.
// For your information Bitmap class default image quality is 75.
// Lower image quality means smaller PDF file.
MyImage.ImageQuality = PdfImage.DefaultQuality;

// Image resolution sets the image resolution provided
// that it is smaller than the resolution of source image.
// Default of 0, is keeping the original image resolution.
// Resolution is specified in pixels per inch.
// Reduced resolution means smaller PDF file.
MyImage.Resolution = 0;

// Cutoff value for gray conversion to black and white.
// The range is 1 to 99. The default is 50.
// If shade of gray is below cutoff, the result is black.
// If shade of gray is above cutoff, the result is white.
MyImage.GrayToBWCutoff = 50;

// Reverse black and white
// Default is false
// In Gray or BW images the color is reversed
MyImage.ReverseBW = false;

// Attach to layer control
// Image visibility will be controlled by viewer application.
MyImage.LayerControl = PdfLayer;

Load image into PdfImage object. NOTE: the loading method saves the image in the PDF output file. Once this step is done the image cannot be changed.

// use one of 5 methods to load the image.
// image source can be a file, Bitmap,
// BW bool array, QRCode or Pdf417 barcode
MyImage.LoadImage(image_source);

Draw the image into the PDF Document.

// draw the image
Contents.DrawImage(MyImage, PosX, PosY, Width, Height);

If you want the image to maintain correct aspect ratio use ImageSize or ImageSizePosition to calculate the width and height. If the ratio of width and height is not the same as the image, the image will look stretched in one of the directions.

// calculate the largest rectangle with the correct
// aspect ratio 
SizeD MyImage.ImageSize(Double Width, Double Height);

// calculate the largest rectangle with
// correct aspect ratio that will fit in a given area and
// position. It based on <code>ContentAlignment</code> enumeration.
ImageSizePos ImageSizePosition(Double Width, Double Height, ContentAlignment Alignment);