Package com.ironsoftware.ironpdf.compression

Class AdvancedCompressionOptions

  • public class AdvancedCompressionOptions
extends Object
    Configuration for the advanced compression pipeline.

    Recommended starting points:

    
 // Web/email — strongest size reduction
 AdvancedCompressionOptions web = new AdvancedCompressionOptions();
 web.setJpegQuality(70);
 web.setTargetImageDpi(150);
 web.setRemoveStructureTree(true);

 // Print quality
 AdvancedCompressionOptions print = new AdvancedCompressionOptions();
 print.setJpegQuality(90);
 print.setTargetImageDpi(300);

    Mirrors the .NET AdvancedCompressionOptions class shipped in IronPdf 2026.6.

    • Constructor Detail

      • AdvancedCompressionOptions

        public AdvancedCompressionOptions()

    • Method Detail

      • getJpegQuality

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

        Recommended settings:

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

        Where the re-encoding happens depends on getTargetImageDpi():

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

      • getTargetImageDpi

        public Integer getTargetImageDpi()
        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:

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

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

      • isHighQualityImageSubsampling

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

      • isRemoveStructureTree

        public boolean isRemoveStructureTree()
        Remove the document structure tree before compression.

      • isCompressStreams

        public boolean isCompressStreams()
        Compress content streams using zlib/Flate.

      • isRecompressFlate

        public boolean isRecompressFlate()
        Re-compress already Flate-encoded streams using getCompressionLevel().

      • getCompressionLevel

        public int getCompressionLevel()
        zlib compression level (0-9). Default 9.

      • getObjectStreams

        public ObjectStreamMode getObjectStreams()
        Object stream mode used when writing the output PDF.

      • isRemoveUnreferencedResources

        public boolean isRemoveUnreferencedResources()
        Drop indirect objects that are not referenced from the document catalog.

      • isCoalesceContents

        public boolean isCoalesceContents()
        Merge a page's separate content streams so they Flate-compress together.

      • isDecodeGeneralizedStreams

        public boolean isDecodeGeneralizedStreams()
        Decode generalized filters (FlateDecode, LZW, ASCII85, ASCIIHex) before re-encoding.

      • getOptimizeImagesMinWidth

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

      • getOptimizeImagesMinHeight

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

      • getOptimizeImagesMinArea

        public int getOptimizeImagesMinArea()
        Minimum image area (width × height pixels) for image optimization to apply.

      • setBitonalMode

        public AdvancedCompressionOptions setBitonalMode​(BitonalCompressionMode bitonalMode)
        Opt-in bitonal (1-bit CCITT Group 4) compression. When not BitonalCompressionMode.OFF, eligible images are thresholded to pure black/white and CCITT Group 4 encoded, which is far smaller than JPEG on scanned text (and sharper). The bitonal result is only kept when it is actually smaller than the original; images that are already bitonal are left untouched.

        Note: when getBitonalResolutionDpi() is unset the bitonal pass falls back to getTargetImageDpi() (default 150), so setting only this resamples a 300 DPI scan to 150 DPI before thresholding. Set a bitonal resolution, or set targetImageDpi to null, to threshold at the source resolution.

        Enabling bitonal also runs the image pass for images that do not qualify (or whose CCITT encoding is not smaller): those go through the normal JPEG pass at getJpegQuality() (85 when unset), and a re-encode is kept only when it is smaller than the original. This matches .NET. Use it on documents that are mostly black-and-white scans.

        Parameters:
        bitonalMode - the bitonal mode (non-null)
        Returns:
        this instance
        Throws:
        IllegalArgumentException - if bitonalMode is null

      • getBitonalResolutionDpi

        public Integer getBitonalResolutionDpi()
        Target DPI for bitonal images when bitonal mode is enabled.
        Returns:
        the bitonal DPI, or null (default) to fall back to getTargetImageDpi()

      • setBitonalResolutionDpi

        public AdvancedCompressionOptions setBitonalResolutionDpi​(Integer bitonalResolutionDpi)
        Target DPI for bitonal images when bitonal mode is enabled; images above it are downsampled before thresholding. Wins over getTargetImageDpi() when set; when null the bitonal pass falls back to targetImageDpi, and when both are null the source resolution is kept. A value <= 0 is treated as unset. No effect when bitonal is off.
        Parameters:
        bitonalResolutionDpi - the DPI, or null
        Returns:
        this instance

      • getBitonalThreshold

        public Integer getBitonalThreshold()
        Luminance threshold used to split pixels into black/white when bitonal mode is enabled.
        Returns:
        the threshold, or null (default) for the automatic (Otsu) threshold

      • setBitonalThreshold

        public AdvancedCompressionOptions setBitonalThreshold​(Integer bitonalThreshold)
        Luminance threshold (1-255) splitting pixels into black/white when bitonal mode is enabled. null (default) auto-computes an optimal per-image threshold (Otsu's method, recommended). A value of 0 or outside 1-255 falls back to auto, since a cutoff of 0 would make every pixel white.
        Parameters:
        bitonalThreshold - the threshold, or null
        Returns:
        this instance

      • pdfiumWillReEncode

        public boolean pdfiumWillReEncode()
        Returns true if pdfium-side image re-encoding is engaged (because a positive targetImageDpi was set). The qpdf optimizeImages step is skipped in that case to avoid double JPEG encoding.

      • pdfiumImagePassWillRun

        public boolean pdfiumImagePassWillRun()
        Returns true if the pdfium image pass runs at all: a positive targetImageDpi, or bitonal mode on. (Mirrors .NET, which widened only this run condition for bitonal; the qpdf flags still key off pdfiumWillReEncode().)