Optimizer — Deep Reference (Gated)

Gated content notice. This page is part of the gated reference surface. Distribution restricted by NDA. Do not mirror to public channels.

At a glance

This page documents the level semantics and estimation behavior beyond the public landing page.

Edition gate

Requires NextPDF Pro, installed via composer require nextpdf/premium. Get a license.

License feature flag

No per-feature license flag. The Pro edition gates the code. The optimization level is a runtime parameter.

Behavior contract

PdfOptimizer::analyze($pdfData) is read-only and returns an OptimizationResult with original size, estimated optimized size, objects removed, and image counts before and after. When the level enables deduplication, it finds duplicate object groups and estimates their savings, then counts how many image objects participate in duplicate groups to compute the image-after count. It analyzes images and estimates recompression at the level’s target quality. The estimated optimized size is clamped so it never goes below zero and never exceeds the original size. OptimizationLevel defines three levels: lossless (100 percent image quality, no deduplication, byte-stable intent), balanced (75 percent, deduplication on), aggressive (50 percent, deduplication on, downsampling). withLevel returns a new optimizer; instances are not mutated.

Public API surface

composer require nextpdf/premium

Public types: PdfOptimizer, OptimizationLevel, OptimizationResult, and the supporting analysis result value objects (DuplicateGroup, ImageAnalysis, ImageCompressionSuggestion).

Conformance

Optimization operates on the PDF object and image model defined by ISO 32000-2; the source annotates the relevant clauses. The RAG corpus was unavailable at authoring time, so this page asserts no additional external clause identifiers.

Edge cases & FIPS-mode behavior

analyze reports potential only. Produce optimized output with the Writer module.
Lossless intentionally yields small reductions because it preserves quality and skips deduplication for byte-stable output.
Analysis does not execute embedded content.
This module performs no cryptographic operations and defines no FIPS-specific behavior.