Optimizer — Riferimento approfondito

In breve

Questa pagina è il riferimento approfondito per la superficie pubblica di NextPDF\Pro\Optimizer. Copre l’orchestratore di analisi, i livelli di ottimizzazione, i due scanner e i value object di risultato. Ne indica parametri, valori predefiniti, aritmetica di stima e modalità di errore. L’analisi è in sola lettura: stima i risparmi e non produce alcun documento di output. Leggere prima la pagina della funzionalità Optimizer per indicazioni sul flusso di lavoro.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Optimizer non dispone di un flag di licenza per singola funzionalità. È una funzionalità dell’edizione Pro. Il livello di ottimizzazione è un parametro a runtime, non un interruttore di licenza.

Superficie API pubblica

composer require nextpdf/pro:^3

Il metapacchetto nextpdf/premium installa il codice di nextpdf/pro; questo modulo risiede nel namespace NextPDF\Pro\Optimizer.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Costruisce un optimizer al livello indicato	PdfOptimizer	Nulla dichiarato	Costruisce le proprie istanze di scanner
PdfOptimizer::analyze	string $pdfData	Analisi in sola lettura al livello configurato	OptimizationResult	OverflowException con input superiore a 100,000,000 byte; InvalidArgumentException dagli scanner su dati PDF non validi	Solo stime; non produce alcun documento di output
PdfOptimizer::withLevel	OptimizationLevel $level	Restituisce un nuovo optimizer al livello richiesto	self	Nulla dichiarato	L’istanza ricevente resta invariata
OptimizationLevel	casi Lossless, Balanced, Aggressive	Enum con backing string dei livelli di aggressività	—	—	Valori di backing lossless, balanced, aggressive
OptimizationLevel::label	nessuno	Etichetta del livello leggibile	string	Nulla dichiarato	Per uso di visualizzazione
OptimizationLevel::imageQuality	nessuno	Qualità immagine target per il livello	int	Nulla dichiarato	100, 75 o 50
OptimizationLevel::deduplicateStreams	nessuno	Indica se il livello abilita la deduplicazione	bool	Nulla dichiarato	false solo per Lossless
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Risultato di analisi immutabile	OptimizationResult	Nulla dichiarato	Tutte le proprietà sono public e readonly
OptimizationResult::savedBytes	nessuno	Dimensione originale meno dimensione ottimizzata stimata	int	Nulla dichiarato	Byte
OptimizationResult::savedPercent	nessuno	Riduzione percentuale della dimensione	float	Nulla dichiarato	0.0 quando la dimensione originale è zero
OptimizationResult::summary	nessuno	Report leggibile su più righe	string	Nulla dichiarato	Dimensioni formattate come B, KB o MB
ObjectDeduplicator::findDuplicates	string $pdfData	Raggruppa corpi di oggetti identici per hash SHA-256	list<DuplicateGroup>	InvalidArgumentException in caso di header %PDF mancante, input superiore a 268,435,456 byte o più di 500,000 marcatori di oggetto	Restituisce solo i gruppi con due o più membri
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Somma il conteggio dei duplicati per la dimensione dell’oggetto per ciascun gruppo	int	Nulla dichiarato	Byte
ImageRecompressor::analyzeImages	string $pdfData	Estrae i metadati per ogni XObject immagine	list<ImageAnalysis>	InvalidArgumentException in caso di header %PDF mancante	Salta gli oggetti privi di larghezza e altezza esplicite
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Consiglia un filtro e stima i risparmi	ImageCompressionSuggestion	Nulla dichiarato	Euristiche dipendenti dal livello; vedere il contratto di comportamento
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Record immutabile di gruppo duplicato	DuplicateGroup	Nulla dichiarato	Il primo numero di oggetto è l’oggetto canonico mantenuto
DuplicateGroup::duplicateCount	nessuno	Dimensione del gruppo meno l’oggetto canonico	int	Nulla dichiarato	Oggetti rimovibili tramite unione
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Record immutabile di metadati per immagine	ImageAnalysis	Nulla dichiarato	I campi rispecchiano le voci del dizionario immagine
ImageAnalysis::estimatedDpi	float $displayWidthPt	DPI effettivi alla larghezza di visualizzazione indicata	float	Nulla dichiarato	0.0 quando la larghezza di visualizzazione è zero o negativa
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Segnala i candidati al downsampling oltre i DPI target	bool	Nulla dichiarato	Confronto strettamente maggiore di
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Record immutabile di raccomandazione	ImageCompressionSuggestion	Nulla dichiarato	reason è testo esplicativo leggibile

Firme dei punti di ingresso

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
}

Contratto di comportamento

Orchestrazione

PdfOptimizer::analyze accetta byte PDF grezzi ed è in sola lettura. Innanzitutto limita l’input non attendibile a 100,000,000 byte; un input sovradimensionato genera OverflowException prima che venga eseguita qualsiasi scansione. Esegue poi l’analisi di deduplicazione quando il livello lo consente, esegue sempre l’analisi delle immagini e aggrega entrambe in un unico OptimizationResult. withLevel restituisce un nuovo optimizer; le istanze non vengono mai mutate.

Semantica dei livelli

Livello	Qualità immagine target	Deduplicazione	Intento
Lossless	100%	Disattivata	Nessuna perdita di qualità; intento di output stabile a livello di byte
Balanced	75%	Attiva	Compromesso di qualità moderato; il valore predefinito
Aggressive	50%	Attiva	Riduzione massima; downsampling; perdita di qualità visibile

Lossless salta la deduplicazione affinché l’output possa rimanere stabile a livello di byte. La qualità target alimenta l’aritmetica dei suggerimenti sulle immagini più sotto.

Analisi di deduplicazione

Il deduplicatore esamina le definizioni di oggetti indiretti di generazione zero (da N 0 obj a endobj). Ogni corpo viene ripulito dagli spazi circostanti, sottoposto ad hashing con SHA-256 e raggruppato per hash. Le definizioni che differiscono solo per il padding corrispondono quindi comunque. Vengono restituiti solo i gruppi con due o più membri. Il risparmio stimato per gruppo è pari al conteggio dei duplicati moltiplicato per la dimensione del singolo corpo, poiché tutti gli oggetti tranne quello canonico possono essere rimossi.

Analisi delle immagini

Un oggetto è trattato come immagine quando il suo corpo contiene /Subtype /Image (con o senza uno spazio interno). Larghezza e altezza sono obbligatorie; un oggetto privo di una delle due viene saltato. Lo spazio colore assume come predefinito DeviceRGB, i bit per componente 8 e il filtro una stringa vuota quando assente. La dimensione dello stream è misurata tra i marcatori stream ed endstream; quando non viene trovato alcuno stream inline, si utilizza invece il valore /Length.

Euristiche di suggerimento

• Al livello Lossless, il filtro corrente viene mantenuto e il risparmio stimato è zero.
• Per le sorgenti DCTDecode, il suggerimento ricodifica alla qualità del livello. La stima è la dimensione dello stream moltiplicata per (1 − qualità/100) moltiplicata per 0.5.
• Per le sorgenti FlateDecode, il suggerimento converte in DCTDecode. La stima è il 40% della dimensione dello stream con Balanced e il 60% con Aggressive.
• Per qualsiasi altro filtro, o in assenza di filtro, il suggerimento converte in FlateDecode. La stima è il 20% della dimensione dello stream.

Aritmetica del risultato

• Gli oggetti rimossi sono pari alla somma, su tutti i gruppi duplicati, dei membri oltre il primo canonico.
• Il risparmio totale è pari al risparmio da deduplicazione più le stime dei suggerimenti per immagine.
• La dimensione ottimizzata stimata è la dimensione originale meno il risparmio totale, con un limite inferiore pari a zero. Il risparmio è non negativo, quindi la stima non supera mai la dimensione originale.
• Il conteggio delle immagini dopo sottrae, per ogni gruppo duplicato contenente un’immagine analizzata, il conteggio dei membri duplicati di quel gruppo. Il conteggio ha un limite inferiore pari a zero.
• Il tempo di elaborazione è misurato con un clock monotono e riportato in millisecondi.

Lo stimatore di DPI divide la larghezza in pixel per la larghezza di visualizzazione in pollici (72 punti per pollice). Una larghezza di visualizzazione zero o negativa produce 0.0. Il predicato di sovrarisoluzione confronta la stima con un target, per impostazione predefinita 300 DPI.

Casi limite e modalità di errore

• analyze segnala soltanto il potenziale. Produrre l’output ottimizzato con il modulo Writer.
• Un input vuoto, o un input che non inizia con l’header %PDF, fallisce con InvalidArgumentException.
• Un input superiore a 100,000,000 byte fallisce con OverflowException alla porta d’ingresso dell’orchestratore, prima di qualsiasi scansione.
• Il deduplicatore rifiuta autonomamente input superiori a 268,435,456 byte e più di 500,000 marcatori di oggetto. Entrambi i casi vengono rifiutati fail-closed con InvalidArgumentException; nulla viene troncato o scansionato parzialmente.
• Partecipano solo le definizioni di oggetti di generazione zero. Gli oggetti con numeri di generazione diversi da zero non vengono scansionati.
• Una definizione priva del marcatore di chiusura endobj viene saltata.
• Gli oggetti immagine privi di larghezza e altezza esplicite sono esclusi dal report delle immagini.
• Tutti i valori di risparmio sono euristiche derivate dai metadati degli oggetti, non risultati di ricompressione misurati.
• Il livello lossless segnala intenzionalmente riduzioni ridotte; preserva la qualità e salta la deduplicazione.
• L’analisi non decodifica, esegue o esegue il rendering di contenuti incorporati. Legge esclusivamente la struttura degli oggetti e i metadati.
• L’unica primitiva crittografica utilizzata è SHA-256, per il raggruppamento dei contenuti duplicati. Il modulo non definisce alcun comportamento specifico FIPS.

Conformità

Entrambi gli scanner operano sul modello di oggetti e immagini PDF di ISO 32000-2:2020. La deduplicazione ha come oggetto le definizioni di oggetti indiretti; la struttura del loro identificatore è definita in ISO 32000-2:2020, 7.3.10, citata nel record di citazioni di questa pagina. L’analisi delle immagini legge i parametri che un dizionario immagine indica esplicitamente — larghezza, altezza e bit per componente — secondo ISO 32000-2:2020, 8.9.4, anch’essa citata.

Queste affermazioni descrivono la capacità rispetto alle clausole citate. NextPDF non detiene alcuna certificazione di conformità e il supporto di una clausola non costituisce un’attestazione di certificazione.

Note di sviluppo

• Il sorgente del modulo riporta @since 1.9.0; questo riferimento documenta la superficie così come distribuita in nextpdf/pro 3.1.0.
• Tutte le classi sono final; i record di risultato e di analisi sono value object readonly. Costruire nuove istanze invece di mutarle.
• Il livello predefinito è Balanced. Selezionare un altro livello tramite il costruttore o il metodo in stile with.
• Il limite di input alla porta d’ingresso è applicato da un guard di dimensione input di Core, condiviso tra le superfici di input di NextPDF.
• L’analisi è basata su stringhe sui byte già in memoria. Il modulo non effettua alcun accesso al filesystem o alla rete.
• I dettagli sui meccanismi interni rimangono nella documentazione interna del repository sorgente e sono fuori dall’ambito di questo manuale.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi di supporto, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Optimizer — la pagina della funzionalità per indicazioni sul flusso di lavoro e esempi di codice.
• Writer — Riferimento approfondito — produce il documento di output ottimizzato.
• Accelerator — Riferimento approfondito — ottimizzazione in batch con offload sidecar secondo la semantica di questo modulo.