Adding an Image to a PDF Using iTextSharp (Issue Fixed)

Developers adding images to PDFs with iTextSharp frequently encounter confusion around scaling and aspect ratio preservation. The library provides multiple scaling methods - ScaleToFit, ScalePercent, and ScaleAbsolute - but selecting the correct one and calculating parameters requires understanding iTextSharp's 72 DPI coordinate system. With over 170,000 views on the original Stack Overflow question, this remains a common pain point for .NET developers working with PDF image insertion.

The Problem

iTextSharp handles images differently than developers expect from web or desktop image manipulation. When you load an image into iTextSharp, it maintains the original pixel dimensions but interprets them at 72 dots per inch (DPI). This means an 800x600 pixel image would appear as approximately 11x8 inches in the PDF - far larger than most developers intend.

The core challenge is that developers want images to:

• Fit within page margins without distortion
• Maintain their original aspect ratio
• Scale appropriately for both portrait and landscape orientations
• Work consistently across different image sizes

iTextSharp provides no single method that handles all these requirements automatically. Developers must manually calculate scaling factors based on image orientation, page dimensions, and desired output size.

Common Symptoms

Developers encounter these issues when adding images:

• Images extending beyond page boundaries
• Distorted images when using ScaleAbsolute with incorrect dimensions
• Inconsistent sizing across batches of mixed-orientation images
• Images appearing 35% larger than expected compared to web display
• Difficulty positioning images precisely on the page

Who Is Affected

The 170,000+ views on Stack Overflow indicate this affects developers across:

Use Cases: Photo album generation, report attachments, invoice logos, document archival, image galleries in PDFs, certificate generation with signatures.

Image Sources: User uploads, scanned documents, screenshots, photographs, generated charts, company logos.

Frameworks: .NET Framework 4.x with iTextSharp, though the concepts apply similarly to iText 7.

Evidence from the Developer Community

Timeline

Date	Event	Source
2010-12-01	Original question posted about image scaling	Stack Overflow
2011-2015	Multiple answers with varying approaches	Stack Overflow
2018-10-26	Additional workarounds contributed	Stack Overflow
2023-10-24	Question still receiving views and updates	Stack Overflow

Community Reports

"Is there some way to have the picture use like a Zoom feature to stretch to fit, but also maintain the aspect ratio"

• Developer, Stack Overflow, December 2010

The accepted answer demonstrates the complexity required - developers must iterate through images, check height versus width to determine orientation, calculate a percentage based on maximum desired dimensions, then apply that percentage:

foreach (var image in images)
{
    iTextSharp.text.Image pic = iTextSharp.text.Image.GetInstance(image, System.Drawing.Imaging.ImageFormat.Jpeg);

    if (pic.Height > pic.Width)
    {
        // Portrait: limit height to 800
        float percentage = 700 / pic.Height;
        pic.ScalePercent(percentage * 100);
    }
    else
    {
        // Landscape: limit width to 600
        float percentage = 540 / pic.Width;
        pic.ScalePercent(percentage * 100);
    }

    document.Add(pic);
}

Root Cause Analysis

The complexity stems from several architectural decisions in iTextSharp:

72 DPI Coordinate System: PDF uses a point-based coordinate system where 1 point = 1/72 inch. When iTextSharp loads an image, it interprets pixel dimensions at this resolution. A 1440x1080 image becomes 20x15 inches on the page without scaling.

Multiple Scaling Methods: iTextSharp provides three distinct scaling approaches, each with different behaviors:

• ScalePercent(float percent) - Scales by percentage of original size
• ScaleToFit(float width, float height) - Scales to fit within a rectangle while maintaining aspect ratio
• ScaleAbsolute(float width, float height) - Stretches to exact dimensions, potentially distorting the image

No Automatic Page Awareness: None of these methods automatically consider page size, margins, or existing content. Developers must calculate appropriate dimensions manually.

Position vs Scale Confusion: Setting image position only shifts where the visible portion appears; it does not implicitly scale the image to fit that location.

Attempted Workarounds

Workaround 1: ScaleToFit with Page Size

Approach: Use ScaleToFit with page dimensions to ensure the image fits on the page.

iTextSharp.text.Image image = iTextSharp.text.Image.GetInstance(imagePath);
image.ScaleToFit(document.PageSize.Width, document.PageSize.Height);
document.Add(image);

Limitations:

• Does not account for page margins
• Image may still extend into non-printable areas
• Full-page images leave no room for headers, footers, or other content

Workaround 2: Manual Dimension Calculation

Approach: Calculate available space accounting for margins, then scale accordingly.

iTextSharp.text.Image image = iTextSharp.text.Image.GetInstance(imagePath);

float availableWidth = document.PageSize.Width - document.LeftMargin - document.RightMargin;
float availableHeight = document.PageSize.Height - document.TopMargin - document.BottomMargin;

image.ScaleToFit(availableWidth, availableHeight);
document.Add(image);

Limitations:

• Requires tracking margin values throughout code
• Does not handle centering or positioning
• Complex when mixing images with other content

Workaround 3: Orientation-Based Percentage Scaling

Approach: The accepted Stack Overflow answer - check orientation and calculate percentage.

if (pic.Height > pic.Width)
{
    float percentage = 700 / pic.Height;
    pic.ScalePercent(percentage * 100);
}
else
{
    float percentage = 540 / pic.Width;
    pic.ScalePercent(percentage * 100);
}

Limitations:

• Magic numbers (700, 540) must be adjusted for different page sizes
• Does not adapt to varying document layouts
• Requires understanding of iTextSharp's internal coordinate system

A Different Approach: IronPDF

IronPDF takes a fundamentally different approach to image handling in PDFs. Rather than working with pixel dimensions and scaling calculations, IronPDF allows developers to use HTML and CSS - the same technologies used for web layout. Images are embedded using standard <img> tags with CSS controlling size and positioning.

Why IronPDF Simplifies Image Handling

When you embed images through HTML in IronPDF, you work with familiar concepts:

• width and height CSS properties control sizing
• max-width: 100% ensures images never exceed their container
• object-fit CSS property controls how images fill their space
• Flexbox and Grid provide precise positioning
• Percentage-based dimensions adapt to page size automatically

The Chromium rendering engine handles all aspect ratio calculations internally, just as it does when displaying images in a browser.

Code Example

using IronPdf;
using System;
using System.IO;

/// <summary>
/// Generates a PDF document containing images with automatic aspect ratio handling.
/// Uses HTML/CSS for layout, eliminating manual scaling calculations.
/// </summary>
public class ImagePdfGenerator
{
    public void CreatePdfWithImages(string[] imagePaths, string outputPath)
    {
        var renderer = new ChromePdfRenderer();

        // Configure page settings
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;
        renderer.RenderingOptions.MarginLeft = 20;
        renderer.RenderingOptions.MarginRight = 20;

        // Build HTML with embedded images
        string html = BuildImageGalleryHtml(imagePaths);

        // Render to PDF - Chromium handles all scaling automatically
        using var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs(outputPath);
    }

    private string BuildImageGalleryHtml(string[] imagePaths)
    {
        var imageHtml = new System.Text.StringBuilder();

        foreach (var path in imagePaths)
        {
            // Convert image to base64 for embedding
            byte[] imageBytes = File.ReadAllBytes(path);
            string base64 = Convert.ToBase64String(imageBytes);
            string extension = Path.GetExtension(path).ToLower().TrimStart('.');
            string mimeType = extension == "jpg" ? "jpeg" : extension;

            imageHtml.AppendLine($@"
                <div class='image-container'>
                    <img src='data:image/{mimeType};base64,{base64}' alt='Document Image' />
                </div>");
        }

        return $@"
<!DOCTYPE html>
<html>
<head>
    <style>
        body {{
            font-family: Arial, sans-serif;
            margin: 0;
            padding: 0;
        }}
        .image-container {{
            page-break-inside: avoid;
            margin-bottom: 20px;
            text-align: center;
        }}
        .image-container img {{
            max-width: 100%;
            max-height: 700px;
            height: auto;
            /* Maintains aspect ratio automatically */
            object-fit: contain;
        }}
    </style>
</head>
<body>
    {imageHtml}
</body>
</html>";
    }
}

Using the class:

var generator = new ImagePdfGenerator();
string[] photos = new[]
{
    @"C:\photos\landscape.jpg",
    @"C:\photos\portrait.png",
    @"C:\photos\square.jpg"
};
generator.CreatePdfWithImages(photos, @"C:\output\photo-album.pdf");

Key points about this code:

• max-width: 100% ensures images never exceed the page width
• max-height: 700px constrains tall images while maintaining aspect ratio
• object-fit: contain preserves aspect ratio within the constraints
• No manual calculations required for portrait vs landscape images
• CSS handles all scaling logic through the Chromium engine

Precise Image Positioning

For documents requiring exact image placement (certificates, forms, letterheads):

using IronPdf;

public class PositionedImagePdf
{
    public void CreateCertificate(string logoPath, string signaturePath)
    {
        var renderer = new ChromePdfRenderer();

        // Convert images to base64
        string logoBase64 = Convert.ToBase64String(File.ReadAllBytes(logoPath));
        string signatureBase64 = Convert.ToBase64String(File.ReadAllBytes(signaturePath));

        string html = $@"
<!DOCTYPE html>
<html>
<head>
    <style>
        @page {{
            size: A4 landscape;
            margin: 0;
        }}
        body {{
            margin: 0;
            padding: 40px;
            position: relative;
            height: 100vh;
            box-sizing: border-box;
        }}
        .logo {{
            position: absolute;
            top: 30px;
            left: 50%;
            transform: translateX(-50%);
            width: 150px;
            height: auto;
        }}
        .content {{
            text-align: center;
            margin-top: 100px;
        }}
        .content h1 {{
            font-size: 36px;
            color: #2c3e50;
            margin-bottom: 20px;
        }}
        .signature {{
            position: absolute;
            bottom: 80px;
            right: 100px;
            width: 200px;
            height: auto;
        }}
        .signature-line {{
            position: absolute;
            bottom: 70px;
            right: 80px;
            width: 240px;
            border-top: 1px solid #333;
        }}
    </style>
</head>
<body>
    <img class='logo' src='data:image/png;base64,{logoBase64}' alt='Company Logo' />

    <div class='content'>
        <h1>Certificate of Completion</h1>
        <p>This certifies that <strong>John Smith</strong></p>
        <p>has successfully completed the training program</p>
    </div>

    <img class='signature' src='data:image/png;base64,{signatureBase64}' alt='Signature' />
    <div class='signature-line'></div>
</body>
</html>";

        using var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("certificate.pdf");
    }
}

API Reference

For more details on the methods used:

• ChromePdfRenderer
• Adding Images to PDFs
• Base URLs and Asset Encoding
• Embedding Images with Data URIs

Migration Considerations

Licensing

IronPDF is commercial software with per-developer licensing. A free trial is available for evaluation. See licensing details for pricing options.

API Differences

The paradigm shift is significant:

iTextSharp	IronPDF
Load image object, calculate scale, position manually	Define image in HTML/CSS
Pixel dimensions at 72 DPI	Standard CSS sizing (px, %, em, etc.)
ScaleToFit, ScalePercent methods	max-width, object-fit CSS
Absolute positioning with coordinates	CSS positioning (absolute, relative, flexbox, grid)

What You Gain

• CSS handles aspect ratio preservation automatically
• Familiar web development workflow for layout
• No manual DPI or coordinate calculations
• Responsive layouts with percentage-based sizing
• Complex positioning with CSS Grid or Flexbox

What to Consider

• Different approach requires HTML/CSS knowledge
• Chromium binaries add to deployment size
• Base64 encoding increases HTML size for embedded images
• Learning curve if unfamiliar with CSS layout

Conclusion

iTextSharp's image scaling requires understanding its 72 DPI coordinate system and choosing between multiple scaling methods, each with different behaviors. For developers comfortable with HTML and CSS, IronPDF's approach eliminates these calculations entirely - the browser engine handles aspect ratios, positioning, and scaling using standard web technologies.

---

Jacob Mellor is CTO at Iron Software and originally built IronPDF.

---

References

1. Adding an image to a PDF using iTextSharp and scale it properly{:rel="nofollow"} - Stack Overflow, 170K+ views
2. iTextSharp - Working with images{:rel="nofollow"} - Mike's .NET Tutorial
3. How to preserve high resolution images in PDF?{:rel="nofollow"} - iText Knowledge Base
4. How to resize an Image to fit it into a PdfPCell?{:rel="nofollow"} - iText Knowledge Base

For the latest IronPDF documentation and tutorials, visit ironpdf.com.