Add Image Elements to PDF Document

The PdfDocument class allows you to create PDF documents from scratch and add various content elements using a simple programmatic interface.

The PDF image element is represented by the EvoPdf.ChromiumPdfImageElement class and can be added to a PdfDocument using the PdfDocumentAddImage(PdfImageElement) method.

Create and Render PDF Image Elements

An image element requires either an image file path or image data as a byte array when it is created. The steps below describe how to create image elements and render them in a PDF document.

Create the Image Element

An EvoPdf.ChromiumPdfImageElement instance can be created either from image data provided as a byte array using the PdfImageElement(Byte) constructor or from an image file path using the PdfImageElement(String) constructor. The PdfImageElement class also includes properties to specify the X and Y position of the image element relative to the top-left corner of the PDF page, excluding the page margins. These properties are zero by default. The example below creates an image element positioned at specific coordinates on the PDF page, rendered without any resizing.

Create an Image Element

PdfImageElement pdfImage = new PdfImageElement(imagePath)
{
  X = crtXPos,
  Y = crtYPos
};

Positioning and Scaling

The X and Y properties specify the location of the image element relative to the top-left corner of the PDF page. The page margins are excluded when positioning the element.

If either the Width or PdfImageElementHeight property is specified, the library will attempt to scale the image to fit the specified width or height. Image scaling can also be controlled by the PdfImageElementScaleDownToFit and PdfImageElementEnlargeToFit properties. In the example below, the image will be rendered at the specified coordinates and will have a width of 150 points.

Create an Image Element

string imagesPath = GetDemoImagesPath();

// Add a transparent PNG image with custom width
PdfImageElement pdfPngImage = new PdfImageElement(Path.Combine(imagesPath, "transparent.png"))
{
    X = crtXPos,
    Y = crtYPos,
    Width = 150
};

Image Horizontal and Vertical Alignment

You can control the horizontal and vertical alignment of the image on the PDF page using the PdfImageElementHorizontalAlign and PdfImageElementVerticalAlign properties. If they are set to a value other than None, they will take precedence over the X and Y properties.

Render Image Element

To render the image element on the current PDF page, use the PdfDocumentAddImage(PdfImageElement) method. The code below renders the created image element on the current page.

Render Image Element in Current PDF Page

PdfImageRenderInfo imageRenderInfo = pdfDocument.AddImage(pdfPngImage);

The AddImage(PdfImageElement) method returns a EvoPdf.ChromiumPdfImageRenderInfo object, which contains information about the rendered image, such as its scaled size. This information is useful for document layout, as it allows you to position the next element relative to the previous one. For example, the vertical position for the next element can be updated as shown below.

Update Location after Image Rendering

crtYPos = imageRenderInfo.BoundingBox.Bottom + ySeparator;

Code Sample - Create PDF Documents with Text and Images

C#

using System.IO;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

// Use EVO PDF Namespace
using EvoPdf.Chromium;

namespace EvoPdf_Chromium_AspNetDemo.Controllers.PDF_Creator
{
    public class Create_PDF_DocumentsController : Controller
    {
        private readonly IWebHostEnvironment m_hostingEnvironment;

        public Create_PDF_DocumentsController(IWebHostEnvironment hostingEnvironment)
        {
            m_hostingEnvironment = hostingEnvironment;
        }

        public IActionResult Index()
        {
            return View();
        }

        [HttpPost]
        public ActionResult CreatePdf(IFormCollection collection)
        {
            // Set license key received after purchase to use the library in licensed mode
            // Leave it not set to use the library in demo mode
            Licensing.LicenseKey = "4W9+bn19bn5ue2B+bn1/YH98YHd3d3c=";

            PdfDocumentCreateSettings pdfCreateSettings = new PdfDocumentCreateSettings()
            {
                PageSize = PdfPageSize.A4,
                PageOrientation = PdfPageOrientation.Portrait,
                Margins = new PdfMargins(36, 36, 36, 36)
            };

            // Create a new PDF document with the specified settings
            using PdfDocument pdfDocument = new PdfDocument(pdfCreateSettings);

            const int startXPos = 0;
            const int startYPos = 0;
            const int ySeparator = 15;

            int currentPage = pdfDocument.PageNumber;
            int crtXPos = startXPos;
            int crtYPos = startYPos;

            // Create a standard Helvetica font
            PdfFont fontHelvetica = PdfFontManager.CreateStandardFont(PdfStandardFont.Helvetica, 16f,
                PdfFontStyle.Bold | PdfFontStyle.Underline, PdfColor.Black);

            // Add a title using the Helvetica font
            PdfTextElement pdfTitle1 = new PdfTextElement("Transparent PNG Image with Custom Width", fontHelvetica)
            {
                X = crtXPos,
                Y = crtYPos
            };
            PdfTextRenderInfo textRenderInfo = pdfDocument.AddText(pdfTitle1);

            // Update the Y position after rendering the title
            crtYPos = textRenderInfo.LastPageRectangle.Bounds.Bottom + ySeparator;

            string imagesPath = GetDemoImagesPath();

            // Add a transparent PNG image with custom width
            PdfImageElement pdfPngImage = new PdfImageElement(Path.Combine(imagesPath, "transparent.png"))
            {
                X = crtXPos,
                Y = crtYPos,
                Width = 150
            };
            PdfImageRenderInfo imageRenderInfo = pdfDocument.AddImage(pdfPngImage);

            crtYPos = imageRenderInfo.BoundingBox.Bottom + ySeparator;

            // Create a standard Courier font
            PdfFont fontCourier = PdfFontManager.CreateStandardFont(PdfStandardFont.Courier, 16f,
                PdfFontStyle.Bold | PdfFontStyle.Italic, PdfColor.Green);

            // Add a title for the JPEG image
            PdfTextElement pdfTitle2 = new PdfTextElement("JPEG Image with Custom Height", fontCourier)
            {
                X = crtXPos,
                Y = crtYPos
            };
            textRenderInfo = pdfDocument.AddText(pdfTitle2);

            crtYPos = textRenderInfo.LastPageRectangle.Bounds.Bottom + ySeparator;

            // Ensure there is enough vertical space on the current page for the image.
            // Add a new page and reset Y position if needed
            EnsureSpaceOnPage(ref crtYPos, 200, pdfDocument);

            // Add a JPEG image with custom height
            PdfImageElement pdfJpgImage = new PdfImageElement(Path.Combine(imagesPath, "image.jpg"))
            {
                X = crtXPos,
                Y = crtYPos,
                Height = 150
            };
            imageRenderInfo = pdfDocument.AddImage(pdfJpgImage);

            crtYPos = imageRenderInfo.BoundingBox.Bottom + ySeparator;

            string fontsPath = GetDemoFontsPath();
            string textsPath = GetDemoTextsPath();

            string alphabetFilePath = Path.Combine(textsPath, "Alphabet.txt");
            string alfabetString = System.IO.File.ReadAllText(alphabetFilePath);

            // Create a blue bold Courier font
            PdfFont fontCourier2 = PdfFontManager.CreateStandardFont(PdfStandardFont.Courier, 16f,
                PdfFontStyle.Bold, PdfColor.Blue);

            // Add a title for the Unicode text
            PdfTextElement pdfTitle3 = new PdfTextElement("Multi Page Unicode Text with Custom Font", fontCourier2)
            {
                Y = crtYPos,
                Alignment = PdfTextAlignment.Center
            };
            textRenderInfo = pdfDocument.AddText(pdfTitle3);

            crtYPos = textRenderInfo.LastPageRectangle.Bounds.Bottom + ySeparator;

            string dejaVuRegularFontFile = Path.Combine(fontsPath, "DejaVuSerif.ttf");

            // Create an Unicode TrueType font from file
            PdfFont trueTypeFont = PdfFontManager.CreateFont(dejaVuRegularFontFile, 16f,
                PdfFontStyle.Normal, PdfColor.Black);

            // Add long Unicode text using the TrueType font, allowing continuation on next pages
            PdfTextElement pdfText1 = new PdfTextElement(alfabetString, trueTypeFont)
            {
                X = crtXPos,
                Y = crtYPos,
                Alignment = PdfTextAlignment.Left,
                ContinueOnNextPage = true
            };

            // Draw a rectangle around rendered text in each page
            pdfText1.OnPageRendered = (pageNumber, boundingBox) =>
            {
                PdfRectangleElement border = new PdfRectangleElement(boundingBox.X, boundingBox.Y,
                    boundingBox.Width, boundingBox.Height + 5)
                {
                    BorderColor = PdfColor.Blue,
                };
                pdfDocument.AddRectangle(border);
            };

            textRenderInfo = pdfDocument.AddText(pdfText1);

            // Set the next page to landscape A4
            pdfDocument.SetPageSize(PdfPageSize.A4, PdfPageOrientation.Landscape);

            // Add a new page
            pdfDocument.AddPage();

            // Reset positions
            crtXPos = 0;
            crtYPos = 0;

            // Add the same text again, with the same font, centered
            PdfTextElement pdfText2 = new PdfTextElement(alfabetString, trueTypeFont)
            {
                X = crtXPos,
                Y = crtYPos,
                Alignment = PdfTextAlignment.Center,
                ContinueOnNextPage = true
            };

            pdfText2.OnPageRendered = (pageNumber, boundingBox) =>
            {
                PdfRectangleElement border = new PdfRectangleElement(boundingBox.X, boundingBox.Y,
                    boundingBox.Width, boundingBox.Height + 5)
                {
                    BorderColor = PdfColor.Purple,
                };
                pdfDocument.AddRectangle(border);
            };

            textRenderInfo = pdfDocument.AddText(pdfText2);

            // Add a new page
            pdfDocument.AddPage();

            // Reset positions
            crtXPos = 0;
            crtYPos = 0;

            PdfFont rtlTileFont = PdfFontManager.CreateStandardFont(PdfStandardFont.Courier, 16f, 
                PdfFontStyle.Normal, PdfColor.Purple);

            PdfTextElement rtlTitle = new PdfTextElement("Add Right to Left Text", rtlTileFont)
            {
                X = crtXPos,
                Y = crtYPos
            };
            textRenderInfo = pdfDocument.AddText(rtlTitle);
            crtYPos = textRenderInfo.LastPageRectangle.Bounds.Bottom + ySeparator;

            // Create a Unicode font that supports Arabic (RTL)
            string notoSansArabicRegularFontFile = Path.Combine(fontsPath, "NotoSansArabic-Regular.ttf");

            PdfFont trueTypeFontArabic = PdfFontManager.CreateFont(notoSansArabicRegularFontFile, 16f,
                PdfFontStyle.Normal, PdfColor.Black);

            string rtlFilePath = Path.Combine(textsPath, "RightToLeft.txt");
            string rtlString = System.IO.File.ReadAllText(rtlFilePath);

            // Render the right to left text
            PdfTextElement pdfTextRtl = new PdfTextElement(rtlString, trueTypeFontArabic)
            {
                X = crtXPos,
                Y = crtYPos,
                Direction = PdfTextDirection.RightToLeft
            };
            textRenderInfo = pdfDocument.AddText(pdfTextRtl);

            // Save to memory buffer
            byte[] outPdfBuffer = pdfDocument.Save();

            // Send PDF to browser
            FileResult fileResult = new FileContentResult(outPdfBuffer, "application/pdf");
            fileResult.FileDownloadName = "PdfDocument.pdf";

            return fileResult;
        }

        private void EnsureSpaceOnPage(ref int crtYPos, int requestedHeight, PdfDocument pdfDocument)
        {
            if (crtYPos + requestedHeight > pdfDocument.ContentHeight)
            {
                pdfDocument.AddPage();
                crtYPos = 0;
            }
        }

        private string GetDemoFilesPath()
        {
            return m_hostingEnvironment.ContentRootPath + "/wwwroot" + "/DemoAppFiles/Input/";
        }

        private string GetDemoImagesPath()
        {
            return Path.Combine(GetDemoFilesPath(), "Image_Files");
        }

        private string GetDemoFontsPath()
        {
            return Path.Combine(GetDemoFilesPath(), "Font_Files");
        }

        private string GetDemoTextsPath()
        {
            return Path.Combine(GetDemoFilesPath(), "Text_Files");
        }
    }
}