Recursive AI

Convert an image to PDF in C#

OnePDF is a free, open-source PDF library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

NuGet GitHub Docs Download example (.zip)

Wrap a PNG or JPEG in a new PDF, with page size set from pixels and resolution.

Terminal
dotnet add package RecursiveAI.OnePdf

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OnePdf;
 
using var doc = PdfDocument.CreateEmpty();
var image = doc.AddPngImage(
    File.ReadAllBytes("sample.png"));
double w = image.Width * 72 / 150.0;
double h = image.Height * 72 / 150.0;
var page = doc.InsertBlankPage(0, w, h);
using var content = page.BeginContent();
content.DrawImage(image, 0, 0, w, h);
content.Commit();
doc.Save("image.pdf");

Writes image.pdf, a 288 × 144 point page at 150 dpi; prints nothing. sample.png is the example’s 600 × 300 pixel drawing of a blue rectangle and an orange circle.

Unzip the example, then dotnet run.

The full program

The example includes the PNG above and a JPEG of the same drawing, both CC0. The program prints the image’s pixel dimensions and the resulting page size.

C#
using OnePdf;
 
using var doc = PdfDocument.CreateEmpty();
var image = doc.AddPngImage(File.ReadAllBytes("sample.png"));
double dpi = 150;
double width = image.Width * 72 / dpi;
double height = image.Height * 72 / dpi;
var page = doc.InsertBlankPage(0, width, height);
using (var content = page.BeginContent())
{
    content.DrawImage(image, 0, 0, width, height);
    content.Commit();
}
doc.Save("image.pdf");
Console.WriteLine($"sample.png: {image.Width} x {image.Height} pixels");
Console.WriteLine($"image.pdf: {width:0.##} x {height:0.##} points at {dpi} dpi");
Text
sample.png: 600 x 300 pixels
image.pdf: 288 x 144 points at 150 dpi

An unreadable or unsupported PNG or JPEG throws PdfFormatException when you add it, before Save is called.

To put multiple images in one PDF, add a page for each image to the same document, then save once.

Variations

Use JPEG. This complete program creates the same page size using sample.jpg from the example. JPEG bytes are embedded without recompression.

C#
using OnePdf;
 
using var doc = PdfDocument.CreateEmpty();
var image = doc.AddJpegImage(File.ReadAllBytes("sample.jpg"));
double width = image.Width * 72 / 150.0;
double height = image.Height * 72 / 150.0;
var page = doc.InsertBlankPage(0, width, height);
using var content = page.BeginContent();
content.DrawImage(image, 0, 0, width, height);
content.Commit();
doc.Save("photo.pdf");

Writes photo.pdf; no console output.

Fit on Letter paper. Keep a 36-point margin and center the picture without stretching it. The smaller scale factor fits both axes.

C#
using OnePdf;
 
using var doc = PdfDocument.CreateEmpty();
var image = doc.AddPngImage(File.ReadAllBytes("sample.png"));
var page = doc.InsertBlankPage(0, 612, 792);
double scale = Math.Min(540.0 / image.Width, 720.0 / image.Height);
double width = image.Width * scale, height = image.Height * scale;
using var content = page.BeginContent();
content.DrawImage(image, (612 - width) / 2, (792 - height) / 2,
    width, height);
content.Commit();
doc.Save("letter.pdf");
Console.WriteLine($"Image: {width} x {height} points");
Text
Image: 540 x 270 points

The short answer

To convert an image to PDF in C#, create an empty OnePDF document, embed the PNG with AddPngImage or the JPEG with AddJpegImage, create a page, and draw the image onto it. Call Commit before saving. The primary package, RecursiveAI.OnePdf, includes this drawing API; no layout add-on is needed.

Unlike stamping an existing file, this starts with no pages. You choose whether the output page follows the picture’s proportions or uses a fixed paper size. The full program does the former; the Letter variation does the latter. Neither approach creates searchable text from a scan.

How can I convert my image to a PDF?

First decide what the PDF should represent: a picture at a specified print resolution, or a sheet of paper containing a picture. For the first case, multiply each pixel dimension by 72 and divide by the desired dots per inch. In the example, 600 pixels at 150 dpi becomes 288 points, or four inches. The 300-pixel height becomes 144 points, or two inches. Applying the same conversion to both axes preserves aspect ratio.

This sets the picture’s displayed size, not its pixel count. A larger page does not add detail. Likewise, choosing a higher dpi makes the page smaller without resampling the picture. The sample ignores any resolution metadata and uses the explicit value in the program, making that decision visible.

For fixed paper, start with the page dimensions. Subtract the margins to get the available rectangle. Divide its width and height by the image’s pixel dimensions, take the smaller factor, and multiply both image dimensions by that factor. The Letter snippet implements that calculation. Using separate factors would stretch the picture; taking the larger factor would require cropping to avoid running past the available area.

Coordinates start at the lower left and increase upward. The new pages here have no rotation. The content creation docs explain how rotation and page boxes affect drawing onto other pages.

How do I convert JPG to PDF in C#?

Use AddJpegImage rather than AddPngImage, as in the first variation. OnePDF embeds the JPEG bytes as they are, without an additional JPEG encoding step. Its documented JPEG support includes progressive images and CMYK; arithmetic-coded and lossless JPEGs are refused. Renaming another image format to .jpg does not convert it.

For PNG, alpha transparency becomes a PDF soft mask; a transparent-color PNG uses a color-key mask. Opaque, noninterlaced PNG compressed data can pass through without recompression. These are embedding behaviors, not an image optimizer: reducing the drawn dimensions alone does not reduce the source pixels. If file size matters, prepare an appropriately sized picture before embedding it.

Is there a free C# image-to-PDF library?

OnePDF is free and open source under MIT or Apache-2.0. This example uses the RecursiveAI.OnePdf package directly and needs no license key or web service. Both source images in the download are original geometric drawings released under CC0, so the example has no sample-download step.

For several pictures, repeat the page creation and drawing steps for each one in the desired order, adding each image to the same document. The page dimensions may differ between pictures. Save the document after the pages are committed. This produces pages containing images, not OCR text, accessibility descriptions or an archival conformance claim. Those are separate requirements from wrapping a picture in a PDF.

All onepdf recipes