Class CompressionOptions

Configuration options for reducing PDF file size through compression. Controls image quality, structural data, and compression algorithms for optimal size/quality balance.

Example - Optimize PDF for different use cases:

// Maximum compression for email/web (smaller file, lower quality):
var webOptions = new CompressionOptions
{
    CompressImages = true,
    ShrinkImages = true,
    JpegQuality = 60,
    HighQualityImageSubsampling = false,
    RemoveStructureTree = true
};
pdf.Compress(webOptions);  // Can reduce 10MB to ~2MB

// Balanced compression for general distribution:
var balancedOptions = new CompressionOptions
{
CompressImages = true,
ShrinkImages = true,
JpegQuality = 80,
HighQualityImageSubsampling = true,
RemoveStructureTree = false  // Preserve text selection
};
pdf.Compress(balancedOptions);


// Quality-first compression for archival:
var archiveOptions = new CompressionOptions
{
CompressImages = true,
ShrinkImages = false,  // Keep original resolution
JpegQuality = 95,
HighQualityImageSubsampling = true,
RemoveStructureTree = false
};
pdf.Compress(archiveOptions);

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

Compression Trade-offs:

Related Resources:

Constructors

CompressionOptions()

Declaration
public CompressionOptions()

Properties

CompressImages

Enables JPEG compression for embedded images to reduce file size. Images are re-encoded using the JpegQuality setting (default: true).

Example:

options.CompressImages = true;
options.JpegQuality = 75;  // Use with specific quality

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

true to compress images (default); false to preserve original encoding.

HighQualityImageSubsampling

Controls JPEG chroma subsampling quality during image compression. Higher quality preserves color detail, especially in photos and graphics (default: true).

Subsampling modes:

options.HighQualityImageSubsampling = true;   // 4:4:4 - Better color accuracy
options.HighQualityImageSubsampling = false;  // 4:1:1 - Smaller file, some color loss

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

true for 4:4:4 subsampling (default); false for 4:1:1 subsampling.

JpegQuality

JPEG compression quality level for images (1-100). Higher values preserve detail but produce larger files (default: 90).

Recommended settings:

options.JpegQuality = 95;  // Archival - nearly lossless
options.JpegQuality = 85;  // High quality - minimal visible artifacts
options.JpegQuality = 70;  // Balanced - good for general use
options.JpegQuality = 50;  // Web/email - noticeable artifacts, small file
options.JpegQuality = 30;  // Aggressive - significant quality loss

Declaration
public int JpegQuality { get; set; }
Property Value
Type Description
System.Int32

Quality level from 1 (minimum) to 100 (maximum). Default is 90.

RemoveStructureTree

Removes the document structure tree to reduce file size. The structure tree stores logical layout information (headings, paragraphs, reading order).

Can significantly reduce file size for complex documents.

When to keep structure tree:

// Preserve for accessibility and text selection:
options.RemoveStructureTree = false;

// Remove for maximum compression (web uploads):
options.RemoveStructureTree = true;

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

true to remove structure (default); false to preserve accessibility.
Remarks

Removing the structure tree may affect text selection in complex documents and reduces PDF/UA accessibility compliance.

ShrinkImages

Scales down image resolution to match visible display size in the PDF. Dramatically reduces file size for PDFs with oversized source images (default: true).

Example impact:

// A 4000x3000 image displayed at 400x300 in the PDF:
options.ShrinkImages = true;   // Resizes to ~400x300 → Major size reduction
options.ShrinkImages = false;  // Keeps original 4000x3000 → Better for zoom/print

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

true to shrink images (default); false to preserve original resolution.
Remarks

Set to false if users may need to zoom in on images or print at high quality.

See Also