Class QPdfCompressionFlags

Tunable qpdf compression flags. Mirrors the subset of QPDFJob options that IronPdf exposes during advanced compression.

Defaults are tuned for size — they enable CoalesceContents and DecodeGeneralizedStreams, which produce smaller output than the legacy CompressAndSaveAs(bytes, path, jpeg: null, password) overload.

To exactly reproduce legacy output, use IronSoftware.Pdfium.QPdf.QPdfCompressionFlags.Legacy(System.Nullable{System.Int32}) (internal preset the legacy overload itself uses).

Example - opt in to image re-encoding:

var flags = new QPdfCompressionFlags
{
    OptimizeImages = true,
    JpegQuality   = 70
};

Inheritance

System.Object

QPdfCompressionFlags

Namespace: IronSoftware.Pdfium.QPdf

Assembly: IronPdf.dll

Syntax

public class QPdfCompressionFlags : Object

Constructors

QPdfCompressionFlags()

Declaration

public QPdfCompressionFlags()

Properties

CoalesceContents

Merge a page's separate content streams into a single stream so they can be Flate-compressed together. Maps to qpdf coalesceContents.

Most PDF generators (Chrome included) emit page content as several fragments — one per drawing batch — each compressed independently. Compressing them as a single stream almost always wins, because the combined stream contains more repeated tokens for the deflate dictionary to exploit.

Example:

flags.CoalesceContents = true;   // Merge page content streams (default) — smaller text PDFs
flags.CoalesceContents = false;  // Preserve original stream fragmentation

Declaration

public bool CoalesceContents { get; set; }

Property Value

Type	Description
System.Boolean	true to merge per-page content streams (default); false to preserve them as-is.

Remarks

Lossless. Does not affect rendering or text extraction. Most useful on text-heavy PDFs and PDFs produced by Chrome / wkhtmltopdf. Has no effect when CompressStreams is false.

CompressionLevel

zlib compression level used by qpdf when (re-)compressing streams (0-9). Maps to qpdf compressionLevel.

Recommended settings:

flags.CompressionLevel = 9;  // Maximum compression (default) — best size, slowest
flags.CompressionLevel = 6;  // zlib default — balanced
flags.CompressionLevel = 1;  // Fastest — minimal compression
flags.CompressionLevel = 0;  // No compression (store only)

Declaration

public int CompressionLevel { get; set; }

Property Value

Type	Description
System.Int32	Integer in the range 0-9. Default is 9.

Remarks

Diminishing returns above level 6 — level 9 is typically only a few percent smaller than level 6 but takes noticeably longer.

CompressStreams

Compress content streams using zlib/Flate. Maps to qpdf compressStreams ("y" when true, "n" when false).

Example:

flags.CompressStreams = true;   // Compress all eligible streams (default)
flags.CompressStreams = false;  // Leave streams uncompressed (debugging only)

Declaration

public bool CompressStreams { get; set; }

Property Value

Type	Description
System.Boolean	true to compress streams (default); false to leave them as-is.

Remarks

Disabling this almost always increases file size. Only set to false when producing a human-readable PDF for inspection or diffing.

DecodeGeneralizedStreams

Decode generalized filters (FlateDecode, LZWDecode, ASCII85, ASCIIHex) before re-encoding so qpdf can actually re-pack the stream data instead of passing the existing compressed bytes through unchanged. Maps to qpdf decodeLevel ("generalized" when true, "none" when false).

PDFium emits zlib at level 6. qpdf at level 9 typically shaves a few more percent — but only if the existing Flate streams are first decoded. Combine with RecompressFlate and a high CompressionLevel for the largest saving on text-heavy PDFs.

Example:

// Recommended setup for maximum text-PDF compression:
flags.DecodeGeneralizedStreams = true;   // Default
flags.RecompressFlate          = true;
flags.CompressionLevel         = 9;
// Faster pass — pass existing compressed streams through unchanged:
flags.DecodeGeneralizedStreams = false;

Declaration

public bool DecodeGeneralizedStreams { get; set; }

Property Value

Type	Description
System.Boolean	true to decode generalized filters before re-encoding (default); false to leave them as the input encoded them.

Remarks

Lossless — only generalized filters are touched. Specialized (RunLengthDecode) and image filters (DCTDecode, CCITTFaxDecode, JBIG2Decode, JPXDecode) are not affected by this flag. Disabling can speed up compression on very large PDFs at the cost of missing recompression gains, especially when the source was compressed at a level lower than CompressionLevel.

JpegQuality

JPEG quality used by qpdf when re-encoding images during optimization (1-100). Maps to qpdf jpegQuality. When set, automatically enables image optimization.

Recommended settings:

flags.JpegQuality = null;  // No image re-encoding (default)
flags.JpegQuality = 95;    // Archival — minimal artifacts
flags.JpegQuality = 85;    // High quality
flags.JpegQuality = 70;    // Balanced — good for general use
flags.JpegQuality = 50;    // Web/email — visible artifacts, smaller files

Declaration

public Nullable<int> JpegQuality { get; set; }

Property Value

Type	Description
System.Nullable<System.Int32>	Quality level from 1 (minimum) to 100 (maximum), or null (default) to leave images untouched.

Remarks

Setting this property implies OptimizeImages = true. Leave null when image re-encoding has been done at a higher layer to avoid double JPEG encoding (a JPEG-of-a-JPEG is visibly worse than the math suggests for the same final quality setting).

ObjectStreams

Object stream mode used when writing the output PDF. Maps to qpdf objectStreams.

Modes:

flags.ObjectStreams = QPdfObjectStreams.Generate;  // Pack indirect objects into object streams (default; smallest)
flags.ObjectStreams = QPdfObjectStreams.Preserve;  // Keep input's object stream layout
flags.ObjectStreams = QPdfObjectStreams.Disable;   // Write every object as a top-level indirect object

Declaration

public QPdfObjectStreams ObjectStreams { get; set; }

Property Value

Type	Description
QPdfObjectStreams	One of QPdfObjectStreams. Default is Generate.

Remarks

"generate" produces the smallest output for PDF 1.5 and later. Use "disable" when consumer tools cannot read object streams.

OptimizeImages

Enable qpdf's image optimization pass, which re-encodes eligible images (subject to OptimizeImagesMinWidth, OptimizeImagesMinHeight, OptimizeImagesMinArea). Maps to qpdf optimizeImages.

Automatically enabled when JpegQuality is set.

Example:

// Explicit:
flags.OptimizeImages = true;
flags.JpegQuality    = 75;
// Implicit (setting JpegQuality alone is enough):
flags.JpegQuality    = 75;

Declaration

public bool OptimizeImages { get; set; }

Property Value

Type	Description
System.Boolean	true to run qpdf's image optimization pass; false to leave images untouched (default).

Remarks

Disable this flag (and leave JpegQuality null) when image resampling has already been performed at a higher layer (e.g. Pdfium-side DPI downsampling), to avoid double JPEG encoding.

OptimizeImagesMinArea

Minimum image area (in pixels) for image optimization to apply. Maps to qpdf oiMinArea. Images with fewer total pixels than this are skipped.

Example:

flags.OptimizeImagesMinArea = 0;       // Optimize all images (default)
flags.OptimizeImagesMinArea = 16384;   // Skip images smaller than ~128x128

Declaration

public int OptimizeImagesMinArea { get; set; }

Property Value

Type	Description
System.Int32	Pixel area threshold (width × height). Default is 0 (no minimum — process every image).

Remarks

Useful for excluding signatures, logos, and other small assets from re-encoding, where re-encoding cost outweighs any size benefit. Has no effect unless OptimizeImages is enabled (or JpegQuality is set, which auto-enables it).

OptimizeImagesMinHeight

Minimum image height (in pixels) for image optimization to apply. Maps to qpdf oiMinHeight. Images shorter than this are skipped.

Example:

flags.OptimizeImagesMinHeight = 0;    // Optimize all images (default)
flags.OptimizeImagesMinHeight = 128;  // Skip small images

Declaration

public int OptimizeImagesMinHeight { get; set; }

Property Value

Type	Description
System.Int32	Pixel height threshold. Default is 0 (no minimum — process every image).

Remarks

Has no effect unless OptimizeImages is enabled (or JpegQuality is set, which auto-enables it).

OptimizeImagesMinWidth

Minimum image width (in pixels) for image optimization to apply. Maps to qpdf oiMinWidth. Images narrower than this are skipped.

Example:

flags.OptimizeImagesMinWidth = 0;     // Optimize all images (default)
flags.OptimizeImagesMinWidth = 128;   // Skip thumbnails / small icons

Declaration

public int OptimizeImagesMinWidth { get; set; }

Property Value

Type	Description
System.Int32	Pixel width threshold. Default is 0 (no minimum — process every image).

Remarks

Has no effect unless OptimizeImages is enabled (or JpegQuality is set, which auto-enables it).

RecompressFlate

Re-compress already Flate-encoded streams using CompressionLevel. Maps to qpdf recompressFlate.

Example:

flags.RecompressFlate = true;   // Re-deflate streams at the chosen level (default)
flags.RecompressFlate = false;  // Skip — faster, but misses gains on poorly compressed input

Declaration

public bool RecompressFlate { get; set; }

Property Value

Type	Description
System.Boolean	true to re-compress Flate streams (default); false to skip.

Remarks

Has no effect when CompressStreams is false. Particularly useful on PDFs that were originally compressed at a lower level.

RemoveUnreferencedResources

Drop indirect objects that are not referenced from the document catalog. Maps to qpdf removeUnreferencedResources ("yes" when true, "no" when false).

Example:

flags.RemoveUnreferencedResources = true;   // Strip orphan objects (default)
flags.RemoveUnreferencedResources = false;  // Preserve every object — useful for forensic round-trips

Declaration

public bool RemoveUnreferencedResources { get; set; }

Property Value

Type	Description
System.Boolean	true to drop unreferenced resources (default); false to preserve them.

Remarks

Removes only objects with zero references. Does not deduplicate objects with identical content — that requires a separate optimization pass.

Methods

MaximumLossless()

Returns a flag preset that prioritises file size reduction with strict visual fidelity (no image re-encoding).

Declaration

public static QPdfCompressionFlags MaximumLossless()

Returns

Type	Description
QPdfCompressionFlags