Class AdvancedCompressionOptions

Configuration for the advanced compression pipeline.

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

Use AdvancedCompressionOptions in IronPDF when a C# application works with PDF generation. It represents configuration for the advanced compression pipeline.

AdvancedCompressionOptions matters when an application needs to configure or invoke PDF generation from C# code. The class encapsulates the related options and behavior in a single object that is set up once and reused across render or processing calls. Typical scenarios include batch generation pipelines, templated document workflows, and integration with existing C# document services.

To use AdvancedCompressionOptions, instantiate or obtain it from the relevant entry point in the IronPDF C# API. Key properties include CoalesceContents, CompressionLevel, CompressStreams, DecodeGeneralizedStreams. Assign options or invoke methods on the instance to configure or perform the operation. The PDF compression covers typical usage in C# end to end.

using IronPdf;

var instance = new AdvancedCompressionOptions();
var current = instance.CoalesceContents;
// Read or assign other properties such as CompressionLevel, CompressStreams

For the broader workflow, see the IronPDF C# documentation for related how-to guides and examples. For broader context, the PDF generation portion of the IronPDF C# API contains related types that work with AdvancedCompressionOptions directly. AdvancedCompressionOptions exposes additional members beyond those highlighted above; the reference tables on this page list the full set. In application code, treat AdvancedCompressionOptions as a configured object that is constructed once and reused across operations rather than instantiated per call. Configuration is generally idempotent: assigning the same property value twice has the same effect as assigning it once. For diagnostic purposes, inspect the relevant AdvancedCompressionOptions property after each operation to confirm the configured state. See the constructors, properties, and methods tables below for the complete API surface of AdvancedCompressionOptions. Application code typically obtains or instantiates a single AdvancedCompressionOptions and shares it across multiple IronPDF operations rather than recreating it per call.

Constructors

AdvancedCompressionOptions()

Declaration
public AdvancedCompressionOptions()

Properties

BitonalMode

Bitonal (1-bit CCITT Group 4) compression mode for scanned/black-and-white content. When not Off, eligible images are thresholded to pure black/white and CCITT Group 4 encoded, which is dramatically smaller than JPEG on scanned text (and sharper). The bitonal result is only kept when it is actually smaller than the original; otherwise the JPEG path is used.

options.BitonalMode = BitonalCompressionMode.Off;    // Default: normal JPEG pipeline
options.BitonalMode = BitonalCompressionMode.Force;  // Convert every eligible 8-bit image

Note: BitonalResolutionDpi defaults to null and the bitonal pass then falls back to TargetImageDpi, which defaults to 150. So setting only BitonalMode resamples a 300 DPI scan to 150 DPI before thresholding. Set BitonalResolutionDpi explicitly, or set TargetImageDpi to null, to threshold at the source resolution.

Declaration
public BitonalCompressionMode BitonalMode { get; set; }
Property Value
Type Description
BitonalCompressionMode
Remarks

Only applies to images the pipeline can rasterize; already-bitonal images are left untouched.

BitonalResolutionDpi

Target DPI for bitonal images when BitonalMode is enabled. Images whose effective resolution exceeds this are downsampled before thresholding.

Precedence: this value wins when set. When it is null the bitonal path falls back to TargetImageDpi, so a bitonal pass is not silently left at full resolution when only TargetImageDpi is set. When both are null the source resolution is kept. Has no effect when BitonalMode is Off.

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

BitonalThreshold

Luminance threshold (1-255) used to split pixels into black/white when BitonalMode is enabled. null (default) auto-computes an optimal per-image threshold using Otsu's method (recommended for varied scans). Set an explicit value only when you need a fixed, deterministic cutoff. A value of 0, or one outside 1-255, falls back to the auto threshold, because a cutoff of 0 would make every pixel white.

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

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)

Images that are already bitonal (1 bit per component, e.g. CCITT/JBIG2 scans) are exempt: they are left untouched rather than rasterized and re-encoded, because re-encoding a 1-bit image as JPEG enlarges and degrades it. As a result TargetImageDpi does not downsample already-bitonal images.

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.