Table of Contents

Page images

ConvertToImages renders pages to PNG or JPEG from the same layout the PDF uses, so an image and a PDF of the same page always agree. There is no System.Drawing, SkiaSharp or native code involved, and the same page renders to identical bytes on every platform.

Resolution and format

Pages arrive one at a time, through one of two callbacks. PageEncoded hands you each page's bytes; PageStreamFactory asks you for a stream to write each page into. You must set one of them.

using DocWright;
using DocWright.Core.Primitives;
using DocWright.Renderers.Imaging;

// High-resolution JPEGs of every page, streamed straight to files.
var print = new ImageRenderOptions
{
    Dpi = 200,
    Format = ImageOutputFormat.Jpeg,
    JpegQuality = 90,
    Background = ColorRgb.FromRgb(0xFF, 0xFF, 0xFF),
    PageStreamFactory = page => File.Create($"page-{page}.jpg"),
};
ConversionResult result = converter.ConvertToImages(document, print);
Console.WriteLine($"{result.PageCount} JPEG page(s) at 200 DPI");

Sizing

Ask for a size instead of a resolution. The same six properties exist on ImageRenderOptions and on PdfRasterOptions, for PDFs:

using DocWright.Core.Imaging;
using DocWright.Renderers.Imaging;

Action<int, byte[]> Save(string name) => (page, png) => File.WriteAllBytes($"{name}-{page}.png", png);

// 240 px wide; the height follows the page's proportions.
var thumbnail = new ImageRenderOptions { Width = 240, PageEncoded = Save("thumb") };

// Exactly 200 x 200: fill the square and crop the overflow from the centre.
var tile = new ImageRenderOptions { Width = 200, Height = 200, Fit = ImageFit.Cover, PageEncoded = Save("tile") };

// Fit inside 300 x 300 without cropping: a portrait page stays portrait.
var contained = new ImageRenderOptions { Width = 300, Height = 300, Fit = ImageFit.Contain, PageEncoded = Save("contain") };

// 300 DPI, but never wider than 1600 px.
var capped = new ImageRenderOptions { Dpi = 300, MaxWidth = 1600, PageEncoded = Save("capped") };

foreach (ImageRenderOptions options in new[] { thumbnail, tile, contained, capped })
{
    converter.ConvertToImages(document, options);
}

Output

2 JPEG page(s) at 200 DPI
capped-1.png is 1600 px wide
the same page, three ways
A 240 pixel wide thumbnailWidth = 240
A 200 by 200 tile cropped from the page centre200 × 200, Cover
The page fitted inside 300 by 300300 × 300, Contain
Property Meaning
Dpi Resolution. The default is 150. Whole numbers only.
Width, Height Target size in pixels, where 0 means unconstrained. Set one and the other follows the page's proportions.
Fit Contain (default) fits inside the box without padding. Cover fills the box and crops the overflow from the centre. Exact stretches to fill. Cover and Exact need both a width and a height.
ScalePercent Uniform scale, where 100 is natural size. Ignored when Width or Height is set.
MaxWidth, MaxHeight Upper bounds. A page that is too big shrinks, whole; it is never cropped and never enlarged.
Format Png (default) or Jpeg.
JpegQuality 1–100, default 85.
Background The page colour behind transparent areas.

Resizing is a scale, not a resample. The page is rendered directly at the requested size, so a 240-pixel thumbnail is as sharp as one rendered at the equivalent DPI.

Choosing pages

Pass ConvertOptions with Pages as the third argument. Limits and diagnostics apply as they do for PDF:

converter.ConvertToImages(input, imageOptions, new ConvertOptions { Pages = PageRange.Single(1) });

Worth knowing

  • Output is sRGB, with no embedded colour profile and no metadata. A PNG doesn't record its own DPI, so tell your consumer the resolution out of band.
  • Scaling is nearest-neighbour. Word documents are mostly sharp text, logos and screenshots, which smoothing filters blur.
  • For existing PDF files, use ConvertPdfToImages, which takes the same options. See Reading and rendering PDFs.