Optimizer — 詳細リファレンス

概要

このページは、NextPDF\Pro\Optimizer の公開サーフェスに関する詳細リファレンスです。分析オーケストレーター、最適化レベル、2 つのスキャナー、および結果値オブジェクトを対象とします。パラメータ、デフォルト、見積もりの算術、失敗モードを記述します。分析は読み取り専用であり、削減量を見積もるだけで出力ドキュメントは生成しません。ワークフローのガイダンスについては、まず Optimizer 機能ページ をお読みください。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。その権限がないデプロイでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得。

Optimizer には機能ごとのライセンスフラグはありません。これは Pro エディションの機能です。最適化レベルはランタイムパラメータであり、ライセンススイッチではありません。

公開 API サーフェス

composer require nextpdf/pro:^3

nextpdf/premium メタパッケージは nextpdf/pro のコードをインストールします。このモジュールは NextPDF\Pro\Optimizer 名前空間の下に置かれます。

シンボル	パラメータ	デフォルトの挙動	戻り値	スロー/失敗条件	備考
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	指定レベルでオプティマイザーを構築	PdfOptimizer	宣言なし	独自のスキャナーインスタンスを構築
PdfOptimizer::analyze	string $pdfData	設定レベルでの読み取り専用分析	OptimizationResult	100,000,000 バイトを超える入力で OverflowException、不正な PDF データではスキャナーから InvalidArgumentException	見積もりのみ。出力ドキュメントは生成しない
PdfOptimizer::withLevel	OptimizationLevel $level	要求レベルの新しいオプティマイザーを返す	self	宣言なし	受け手のインスタンスは不変
OptimizationLevel	ケース Lossless、Balanced、Aggressive	積極度レベルの文字列バック列挙型	—	—	バッキング値 lossless、balanced、aggressive
OptimizationLevel::label	なし	人間可読なレベルラベル	string	宣言なし	表示用
OptimizationLevel::imageQuality	なし	レベルの目標画像品質	int	宣言なし	100、75、または 50
OptimizationLevel::deduplicateStreams	なし	レベルが重複排除を有効にするか	bool	宣言なし	Lossless のみ false
OptimizationResult::__construct	int $originalSize、int $optimizedSize、int $objectsRemoved、int $imagesBefore、int $imagesAfter、float $processingTimeMs	イミュータブルな分析結果	OptimizationResult	宣言なし	全プロパティは public かつ readonly
OptimizationResult::savedBytes	なし	元のサイズから推定最適化後サイズを引いた値	int	宣言なし	バイト
OptimizationResult::savedPercent	なし	サイズ削減率	float	宣言なし	元のサイズがゼロの場合は 0.0
OptimizationResult::summary	なし	複数行の人間可読レポート	string	宣言なし	サイズは B、KB、または MB で整形
ObjectDeduplicator::findDuplicates	string $pdfData	同一のオブジェクト本体を SHA-256 ハッシュでグループ化	list<DuplicateGroup>	%PDF ヘッダーの欠落、268,435,456 バイトを超える入力、または 500,000 個を超えるオブジェクトマーカーで InvalidArgumentException	メンバーが 2 個以上のグループのみを返す
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	グループごとの重複数とオブジェクトサイズの積を合計	int	宣言なし	バイト
ImageRecompressor::analyzeImages	string $pdfData	すべての画像 XObject のメタデータを抽出	list<ImageAnalysis>	%PDF ヘッダーの欠落で InvalidArgumentException	明示的な幅と高さがないオブジェクトはスキップ
ImageRecompressor::suggestCompression	ImageAnalysis $image、OptimizationLevel $level	フィルターを推奨し削減量を見積もる	ImageCompressionSuggestion	宣言なし	レベル依存のヒューリスティック。挙動契約を参照
DuplicateGroup::__construct	string $contentHash、list<int> $objectNumbers、int $objectSize	イミュータブルな重複グループレコード	DuplicateGroup	宣言なし	最初のオブジェクト番号が正規の保持オブジェクト
DuplicateGroup::duplicateCount	なし	グループサイズから正規オブジェクトを引いた値	int	宣言なし	マージで削除可能なオブジェクト
ImageAnalysis::__construct	int $objectNumber、int $width、int $height、string $colorSpace、int $bitsPerComponent、string $filter、int $streamSize	イミュータブルな画像ごとのメタデータレコード	ImageAnalysis	宣言なし	フィールドは画像辞書のエントリを反映
ImageAnalysis::estimatedDpi	float $displayWidthPt	指定の表示幅における実効 DPI	float	宣言なし	表示幅がゼロまたは負の場合は 0.0
ImageAnalysis::isOverResolution	float $displayWidthPt、int $targetDpi = 300	目標 DPI を超えるダウンサンプリング候補をフラグ付け	bool	宣言なし	厳密な大なり比較
ImageCompressionSuggestion::__construct	int $objectNumber、string $currentFilter、string $suggestedFilter、int $estimatedSavings、string $reason	イミュータブルな推奨レコード	ImageCompressionSuggestion	宣言なし	reason は人間可読な説明テキスト

エントリーポイントのシグネチャ

final class PdfOptimizer
{
    public function __construct(
        private OptimizationLevel $level = OptimizationLevel::Balanced,
    )

    public function analyze(string $pdfData): OptimizationResult

    public function withLevel(OptimizationLevel $level): self
}

enum OptimizationLevel: string
{
    case Lossless = 'lossless';
    case Balanced = 'balanced';
    case Aggressive = 'aggressive';

    public function label(): string

    public function imageQuality(): int

    public function deduplicateStreams(): bool
}

final readonly class OptimizationResult
{
    public function __construct(
        public int $originalSize,
        public int $optimizedSize,
        public int $objectsRemoved,
        public int $imagesBefore,
        public int $imagesAfter,
        public float $processingTimeMs,
    )

    public function savedBytes(): int

    public function savedPercent(): float

    public function summary(): string
}

final class ObjectDeduplicator
{
    public function findDuplicates(string $pdfData): array

    public function estimateSavings(array $groups): int
}

final class ImageRecompressor
{
    public function analyzeImages(string $pdfData): array

    public function suggestCompression(
        ImageAnalysis $image,
        OptimizationLevel $level,
    ): ImageCompressionSuggestion
}

挙動コントラクト

オーケストレーション

PdfOptimizer::analyze は生の PDF バイト列を受け取り、読み取り専用です。まず信頼できない入力を 100,000,000 バイトに制限し、サイズ超過の入力はスキャン実行前に OverflowException を送出します。続いて、レベルが許可する場合は重複排除分析を実行し、画像分析は常に実行して、両者を 1 つの OptimizationResult に集約します。withLevel は新しいオプティマイザーを返し、インスタンスが変更されることはありません。

レベルのセマンティクス

レベル	目標画像品質	重複排除	意図
Lossless	100%	オフ	品質劣化なし。バイト安定な出力を意図
Balanced	75%	オン	中程度の品質トレードオフ。デフォルト
Aggressive	50%	オン	最大削減。ダウンサンプリング。目に見える品質劣化

Lossless は重複排除をスキップし、出力がバイト安定に保たれるようにします。品質目標は、以下の画像推奨の算術に入力されます。

重複排除の分析

重複排除器は、世代ゼロの間接オブジェクト定義（N 0 obj から endobj まで）をスキャンします。各本体は前後の空白がトリムされ、SHA-256 でハッシュ化され、ハッシュごとにグループ化されます。したがって、パディングのみが異なる定義も一致します。メンバーが 2 個以上のグループのみが返されます。正規オブジェクト以外はすべて削除できるため、グループごとの推定削減量は重複数と単一本体サイズの積に等しくなります。

画像分析

オブジェクトは、その本体に /Subtype /Image（内部空白の有無を問わず）を含む場合、画像として扱われます。幅と高さは必須であり、いずれかを欠くオブジェクトはスキップされます。カラースペースはデフォルトで DeviceRGB、コンポーネントあたりのビット数は 8、フィルターは存在しない場合に空文字列となります。ストリームサイズは stream マーカーと endstream マーカーの間で測定されます。インラインストリームが見つからない場合は、代わりに /Length の値が使用されます。

提案ヒューリスティック

• Lossless レベルでは、現在のフィルターが維持され、推定削減量はゼロです。
• DCTDecode ソースの場合、推奨はそのレベルの品質で再エンコードします。見積もりはストリームサイズ × (1 − quality/100) × 0.5 です。
• FlateDecode ソースの場合、推奨は DCTDecode に変換します。見積もりは Balanced でストリームサイズの 40%、Aggressive で 60% です。
• その他のフィルター、またはフィルターなしの場合、推奨は FlateDecode に変換します。見積もりはストリームサイズの 20% です。

結果の計算

• 削除されるオブジェクト数は、すべての重複グループにわたる、正規の最初のオブジェクトを超えるメンバー数の合計に等しくなります。
• 総削減量は、重複排除の削減量に画像ごとの推奨見積もりを加えた値に等しくなります。
• 推定最適化後サイズは、元のサイズから総削減量を引いた値で、下限はゼロです。削減量は非負であるため、見積もりが元のサイズを超えることはありません。
• 最適化後の画像数は、分析済み画像を含む各重複グループについて、そのグループの重複メンバー数を減算します。この数の下限はゼロです。
• 処理時間は単調増加クロックで測定され、ミリ秒で報告されます。

DPI 見積もり器は、ピクセル幅を表示幅（インチ単位、1 インチ 72 ポイント）で割ります。表示幅がゼロまたは負の場合は 0.0 になります。過解像度の判定は、見積もりを目標値（デフォルトで 300 DPI）と比較します。

エッジケースと失敗モード

• analyze は可能性のみを報告します。最適化された出力は Writer モジュールで生成してください。
• 空の入力、または %PDF ヘッダーで始まらない入力は、InvalidArgumentException で失敗します。
• 100,000,000 バイトを超える入力は、スキャン前にオーケストレーターの入口で OverflowException により失敗します。
• 重複排除器は、268,435,456 バイトを超える入力および 500,000 個を超えるオブジェクトマーカーを独自に拒否します。いずれも InvalidArgumentException でフェイルクローズし、切り詰めや部分的なスキャンは行われません。
• 世代ゼロのオブジェクト定義のみが対象です。世代番号が非ゼロのオブジェクトはスキャンされません。
• 閉じ endobj マーカーがない定義はスキップされます。
• 明示的な幅と高さがない画像オブジェクトは、画像レポートから除外されます。
• すべての削減量の数値は、オブジェクトメタデータから導かれたヒューリスティックであり、実測された再圧縮結果ではありません。
• lossless レベルは意図的に小さな削減量を報告します。品質を保ち、重複排除をスキップするためです。
• 分析は埋め込みコンテンツをデコード、実行、レンダリングすることは一切ありません。オブジェクト構造とメタデータのみを読み取ります。
• 使用される暗号プリミティブは、重複コンテンツのグループ化のための SHA-256 のみです。このモジュールは FIPS 固有の挙動を定義しません。

適合性

両スキャナーは、ISO 32000-2:2020 の PDF オブジェクトおよび画像モデルに対して動作します。重複排除は間接オブジェクト定義を対象とし、その識別子構造は ISO 32000-2:2020, 7.3.10 で定義され、本ページの引用レコードで引用されています。画像分析は、画像辞書が明示的に示すパラメータ（幅、高さ、コンポーネントあたりのビット数）を、同じく引用している ISO 32000-2:2020, 8.9.4 に従って読み取ります。

これらの記述は、引用された各条項に対する能力を説明するものです。NextPDF は適合性認証を保持しておらず、ある条項のサポートは認証の主張ではありません。

開発上の注意

• モジュールソースには @since 1.9.0 が付与されています。本リファレンスは nextpdf/pro 3.1.0 で提供されるサーフェスを記述します。
• すべてのクラスは final であり、結果および分析レコードは readonly な値オブジェクトです。変更する代わりに新しいインスタンスを構築してください。
• デフォルトレベルは Balanced です。別のレベルはコンストラクターまたは with スタイルのメソッドで選択してください。
• 入口での入力上限は、NextPDF の各入力サーフェスで共有される Core の入力サイズガードによって強制されます。
• 分析は、すでにメモリ上にあるバイト列に対する文字列ベースの処理です。このモジュールはファイルシステムやネットワークへのアクセスを行いません。
• 内部メカニズムの詳細はソースリポジトリの内部ドキュメントに留まり、本マニュアルの対象外です。

公開の境界

本ページは、外部から観測可能な挙動とサポートされる公開 API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、メカニズム表、Runbook のファイル名、チケットのプレフィックスは対象外です。

関連項目

• Optimizer — ワークフローガイダンスとコードサンプルの機能ページ。
• Writer — 詳細リファレンス — 最適化された出力ドキュメントを生成。
• Accelerator — 詳細リファレンス — 本モジュールのセマンティクスでのサイドカーオフロードによるバッチ最適化。