Class AdvancedCompressionOptions

Configuration for the advanced compression pipeline.

Inheritance
System.Object
AdvancedCompressionOptions
Namespace: IronPdf
Assembly: IronPdf.dll
Syntax
public class AdvancedCompressionOptions : Object
Remarks

Recommended starting points:

// Web/email — strongest size reduction
new AdvancedCompressionOptions {
    JpegQuality = 70,
    TargetImageDpi = 150,
    RemoveStructureTree = true
};

// Print quality
new AdvancedCompressionOptions {
    JpegQuality = 90,
    TargetImageDpi = 300
};

Constructors

AdvancedCompressionOptions()

Declaration
public AdvancedCompressionOptions()

Properties

CoalesceContents

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

Example:

options.CoalesceContents = true;   // Merge page content streams (default) — smaller text PDFs
options.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.

Recommended settings:

options.CompressionLevel = 9;  // Maximum compression (default) — best size, slowest
options.CompressionLevel = 6;  // zlib default — balanced
options.CompressionLevel = 1;  // Fastest — minimal compression
options.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.

Example:

options.CompressStreams = true;   // Compress all eligible streams (default)
options.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.

Example:

// Recommended setup for maximum text-PDF compression:
options.DecodeGeneralizedStreams = true;   // Default
options.RecompressFlate          = true;
options.CompressionLevel         = 9;

// Faster pass — pass existing compressed streams through unchanged:
options.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.

HighQualityImageSubsampling

4:4:4 chroma subsampling when true (better color), 4:1:1 when false (smaller).

Declaration
public bool HighQualityImageSubsampling { get; set; }
Property Value
Type Description
System.Boolean

JpegQuality

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

Recommended settings:

options.JpegQuality = null;  // No image re-encoding (default)
options.JpegQuality = 95;    // Archival — minimal artifacts
options.JpegQuality = 85;    // High quality
options.JpegQuality = 70;    // Balanced — good for general use
options.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

Where the re-encoding happens depends on TargetImageDpi:

  • TargetImageDpi set (default 150): Each image is downsampled and re-encoded at this JPEG quality. optimizeImages is skipped to avoid double JPEG encoding.
  • TargetImageDpi = null: optimizeImages re-encodes images at this JPEG quality without changing pixel dimensions.

The two paths can produce visibly different artifacts at the same quality value. If you need predictable output, decide up-front whether you want resolution reduction or quality-only reduction and set TargetImageDpi accordingly.

ObjectStreams

Object stream mode used when writing the output PDF.

Modes:

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

Declaration
public ObjectStreamMode ObjectStreams { get; set; }
Property Value
Type Description
ObjectStreamMode

One of ObjectStreamMode. Default is Generate.
Remarks

Generate produces the smallest output for PDF 1.5 and later. Use Disable when consumer tools cannot read object streams.

OptimizeImagesMinArea

Minimum image area (in pixels) for image optimization to apply.

Example:

options.OptimizeImagesMinArea = 0;       // Optimize all images (default)
options.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 JpegQuality is set.

OptimizeImagesMinHeight

Minimum image height (in pixels) for image optimization to apply.

Example:

options.OptimizeImagesMinHeight = 0;    // Optimize all images (default)
options.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 JpegQuality is set.

OptimizeImagesMinWidth

Minimum image width (in pixels) for image optimization to apply.

Example:

options.OptimizeImagesMinWidth = 0;     // Optimize all images (default)
options.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 JpegQuality is set.

RecompressFlate

Re-compress already Flate-encoded streams using CompressionLevel.

Example:

options.RecompressFlate = true;   // Re-deflate streams at the chosen level (default)
options.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.

RemoveStructureTree

Remove the document structure tree before compression.

Declaration
public bool RemoveStructureTree { get; set; }
Property Value
Type Description
System.Boolean

RemoveUnreferencedResources

Drop indirect objects that are not referenced from the document catalog.

Example:

options.RemoveUnreferencedResources = true;   // Strip orphan objects (default)
options.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.

TargetImageDpi

Target DPI for image downsampling during advanced compression. Images whose effective rendered DPI exceeds this value are box-filter downsampled to TargetImageDpi before re-encoding.

Recommended values:

options.TargetImageDpi = 300;   // Print quality — lossless to the eye at normal viewing distance
options.TargetImageDpi = 200;   // Crisp on high-DPI / retina screens
options.TargetImageDpi = 150;   // Default — best size/quality balance for screen + email
options.TargetImageDpi = 96;    // Aggressive — soft text but still readable
options.TargetImageDpi = null;  // Disabled — preserve original resolution (largest file)

Declaration
public Nullable<int> TargetImageDpi { get; set; }
Property Value
Type Description
System.Nullable<System.Int32>

DPI threshold. null disables downsampling entirely. Default is 150, which produces meaningful size reductions on Chrome-rendered or scanned PDFs with no perceptible quality loss for screen viewing.
Remarks

Has no effect on images already at or below the threshold — they pass through unchanged.

Quality warning: Values below 96 produce visibly pixelated output. Use < 96 only when file size is the dominant concern (e.g. email attachments

with strict size limits, archive storage where readability matters more than fidelity). At 50 DPI, an A4 page renders at roughly 413×585 pixels — text

remains readable but small text and thin lines will alias noticeably.

Lossy. Once an image is downsampled it cannot be restored to its original resolution.