Adding images to PDF using Aspose.PDF for .NET (part 1)
In today’s digital age, PDFs have become ubiquitous for sharing and presenting documents. PDFs offer a reliable and consistent way to distribute information, Whether for business reports, academic papers, or marketing materials. However, a plain text PDF can sometimes fall short in engagement and clarity. This is where adding images can make a significant difference.
This article will explore enhancing PDF documents by incorporating images using C#. By the end of this guide, you’ll clearly understand how to seamlessly integrate images into your PDFs, making them more visually appealing and informative. Whether you’re a seasoned developer or just starting, this tutorial will provide the tools and knowledge you need to elevate your PDF creation skills.
Let’s dive in and discover how to add that extra visual touch to your PDFs!
There are several ways to add pictures to a PDF file using the Aspose.PDF for .NET library.
Add images and fit the whole page.
In this part, I’ll explain how to add an image to a PDF page and make it fit the full page. Aspose.PDF is a very flexible library that allows the developer to use different methods to achieve his goal.
Add an image using Facades.
Facades are a classical part of the Aspose.PDF library. The PdfFileMend class is directly responsible for working with images. The main idea of working with Facades is to choose a tool (class) and bind it to the document. After that, you can perform the desired operation.
// Define the file names
string _dataDir = @"C:\Samples\";
string imageFileName = Path.Combine(_dataDir, "Images", "Sample-01.jpg");
string pdfFileName = Path.Combine(_dataDir, "example-add-image-01.pdf");
// Create a new PDF document
Document document = new Document();
// Add a new page to the document
Page page = document.Pages.Add();
// Set the page size to A3
page.SetPageSize(PageSize.A3.Height, PageSize.A3.Width);
// Create a PdfFileMend object to add the image to the PDF
Aspose.Pdf.Facades.PdfFileMend mender =
new Aspose.Pdf.Facades.PdfFileMend(document);
// Add the image to the first page of the PDF
// The image will cover the entire page
mender.AddImage(imageFileName, 1,
0, 0,
(float)page.CropBox.Width,
(float)page.CropBox.Height);
//Unbind and dispose document
mender.Close();
// Save the PDF document to the specified file
document.Save(pdfFileName);the specified file
document.Save(pdfFileName);In our case, we used the AddImage method with the following parameters:
imageName— the path of the input image file.pageNum— page number for placing the image.lowerLeftX, lowerLeftY, upperRightX, upperRightY— the rectangle coordinates of the image rectangle.
We used Cropbox coordinates to fill the page with the image. AddImage will automatically stretch or shrink the image to the specified dimensions.
You can see my test run on the screenshot.
Add an image using the modern Aspose.PDF API.
The advantage of facades is that they simplify actions for the user. In our case, it’s not very obvious because we’re only inserting one picture, but the facade also allows you to insert one image across multiple pages. But if you want a more flexible solution, you can use a modern API.
// Define the file names
string _dataDir = @"C:\Samples\";
string imageFileName = Path.Combine(_dataDir, "Images", "Sample-01.jpg");
string pdfFileName = Path.Combine(_dataDir, "example-add-image-02.pdf");
// Create a new PDF document
Document document = new Document();
// Add a new page to the document
Page page = document.Pages.Add();
// Set the page size to A3
page.SetPageSize(PageSize.A3.Height, PageSize.A3.Width);
page.AddImage(imageFileName, page.CropBox);
document.Save(pdfFileName);In this example, we get the same result as the previous one, but the advantage is that it has additional parameters to control image placement. We will talk about this later.
Add an image using the low-level API (PDF operators).
Another way is to use a low-level API. If you want to add an image using operators, then you should follow the following steps:
- Add the image to page resources,
- Calculate proportions between image size and page size,
- Preserve graphics state,
- Add a matrix operator (concatenate matrix)
- Add draw image operator (do operator)
- Preserve graphics state
// Define the file names
string _dataDir = @"C:\Samples\";
string imageFileName = Path.Combine(_dataDir, "Images", "Sample-01.jpg");
string pdfFileName = Path.Combine(_dataDir, "example-add-image-03.pdf");
// Create a new PDF document
Document document = new Document();
// Add a new page to the document
Page page = document.Pages.Add();
// Set the page size to A3
page.SetPageSize(PageSize.A3.Height, PageSize.A3.Width);
string imageId = page.Resources.Images.Add(File.OpenRead(imageFileName));
XImage xImage = page.Resources.Images[imageId];
Rectangle rectangle =
new Rectangle(0, 0, page.MediaBox.Width,
(page.MediaBox.Width * xImage.Height) / xImage.Width);
// Using the GSave operator: this operator saves current graphics state
page.Contents.Add(new GSave());
Matrix matrix = new Matrix(
new double[]{
rectangle.URX - rectangle.LLX, 0,
0, rectangle.URY - rectangle.LLY,
rectangle.LLX, rectangle.LLY
+ (page.MediaBox.Height - rectangle.Height) / 2});
// Using ConcatenateMatrix (concatenate matrix) operator:
// defines how image must be placed
page.Contents.Add(new ConcatenateMatrix(matrix));
// Using Do operator: this operator draws image
page.Contents.Add(new Do(xImage.Name));
// Using GRestore operator: this operator restores graphics state
page.Contents.Add(new GRestore());
document.Save(pdfFileName);The last expression in the matrix allows us to center the image on the page by height.
Performance: what should we choose to use?
Testing has shown that all three methods work at approximately the same speed. Therefore, you need to decide which specific method to use based on the requirements of your project.
Personally, I find the second method (page.AddImage) more convenient because it allows me to place an image anywhere on the page without much effort, which I will discuss in the next part.
