Optimizer — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona to szczegółowa dokumentacja referencyjna publicznej powierzchni NextPDF\Pro\Optimizer. Obejmuje orkiestrator analizy, poziomy optymalizacji, dwa skanery oraz obiekty wartości wyników. Podaje parametry, wartości domyślne, arytmetykę szacowania i tryby awarii. Analiza jest tylko do odczytu: szacuje oszczędności i nie wytwarza dokumentu wyjściowego. Najpierw przeczytaj stronę funkcji Optimizer, aby uzyskać wskazówki dotyczące przepływu pracy.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną warstwy Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Optimizer nie ma flagi licencji dla poszczególnych funkcji. To funkcja edycji Pro. Poziom optymalizacji jest parametrem czasu działania, a nie przełącznikiem licencji.

Powierzchnia publicznego API

composer require nextpdf/pro:^3

Metapakiet nextpdf/premium instaluje kod nextpdf/pro; ten moduł znajduje się w przestrzeni nazw NextPDF\Pro\Optimizer.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Buduje optymalizator na podanym poziomie	PdfOptimizer	Nic nie zadeklarowano	Tworzy własne instancje skanerów
PdfOptimizer::analyze	string $pdfData	Analiza tylko do odczytu na skonfigurowanym poziomie	OptimizationResult	OverflowException przy danych wejściowych powyżej 100,000,000 bajtów; InvalidArgumentException ze skanerów przy nieprawidłowych danych PDF	Tylko szacuje; nie wytwarza dokumentu wyjściowego
PdfOptimizer::withLevel	OptimizationLevel $level	Zwraca nowy optymalizator na żądanym poziomie	self	Nic nie zadeklarowano	Instancja odbierająca pozostaje niezmieniona
OptimizationLevel	przypadki Lossless, Balanced, Aggressive	Enum poziomów agresywności oparty na łańcuchach	—	—	Wartości bazowe lossless, balanced, aggressive
OptimizationLevel::label	brak	Czytelna dla człowieka etykieta poziomu	string	Nic nie zadeklarowano	Do zastosowań wyświetlania
OptimizationLevel::imageQuality	brak	Docelowa jakość obrazu dla poziomu	int	Nic nie zadeklarowano	100, 75 lub 50
OptimizationLevel::deduplicateStreams	brak	Czy poziom włącza deduplikację	bool	Nic nie zadeklarowano	false tylko dla Lossless
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Niezmienny wynik analizy	OptimizationResult	Nic nie zadeklarowano	Wszystkie właściwości są publiczne i readonly
OptimizationResult::savedBytes	brak	Rozmiar oryginalny minus szacowany rozmiar po optymalizacji	int	Nic nie zadeklarowano	Bajty
OptimizationResult::savedPercent	brak	Procentowa redukcja rozmiaru	float	Nic nie zadeklarowano	0.0, gdy rozmiar oryginalny wynosi zero
OptimizationResult::summary	brak	Wielowierszowy raport czytelny dla człowieka	string	Nic nie zadeklarowano	Rozmiary formatowane jako B, KB lub MB
ObjectDeduplicator::findDuplicates	string $pdfData	Grupuje identyczne treści obiektów według skrótu SHA-256	list<DuplicateGroup>	InvalidArgumentException przy braku nagłówka %PDF, danych wejściowych powyżej 268,435,456 bajtów lub ponad 500,000 znaczników obiektów	Zwraca tylko grupy z dwoma lub więcej członkami
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Sumuje liczbę duplikatów pomnożoną przez rozmiar obiektu dla każdej grupy	int	Nic nie zadeklarowano	Bajty
ImageRecompressor::analyzeImages	string $pdfData	Wyodrębnia metadane dla każdego obrazu XObject	list<ImageAnalysis>	InvalidArgumentException przy braku nagłówka %PDF	Pomija obiekty bez jawnej szerokości i wysokości
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Rekomenduje filtr i szacuje oszczędności	ImageCompressionSuggestion	Nic nie zadeklarowano	Heurystyki zależne od poziomu; zobacz kontrakt zachowania
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Niezmienny rekord grupy duplikatów	DuplicateGroup	Nic nie zadeklarowano	Pierwszy numer obiektu to kanoniczny zachowywany obiekt
DuplicateGroup::duplicateCount	brak	Rozmiar grupy minus kanoniczny obiekt	int	Nic nie zadeklarowano	Obiekty usuwalne przez scalanie
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Niezmienny rekord metadanych pojedynczego obrazu	ImageAnalysis	Nic nie zadeklarowano	Pola odzwierciedlają wpisy słownika obrazu
ImageAnalysis::estimatedDpi	float $displayWidthPt	Efektywne DPI przy podanej szerokości wyświetlania	float	Nic nie zadeklarowano	0.0, gdy szerokość wyświetlania jest zerowa lub ujemna
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Oznacza kandydatów do próbkowania w dół powyżej docelowego DPI	bool	Nic nie zadeklarowano	Porównanie ściśle większe niż
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Niezmienny rekord rekomendacji	ImageCompressionSuggestion	Nic nie zadeklarowano	reason to czytelny dla człowieka tekst objaśniający

Sygnatury punktów wejścia

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
}

Kontrakt zachowania

Orkiestracja

PdfOptimizer::analyze przyjmuje surowe bajty PDF i działa tylko do odczytu. Najpierw ogranicza niezaufane dane wejściowe do 100,000,000 bajtów; zbyt duże dane wejściowe zgłaszają OverflowException przed uruchomieniem jakiegokolwiek skanowania. Następnie uruchamia analizę deduplikacji, gdy poziom na to pozwala, zawsze uruchamia analizę obrazów i agreguje obie w jeden OptimizationResult. withLevel zwraca nowy optymalizator; instancje nigdy nie są mutowane.

Semantyka poziomów

Poziom	Docelowa jakość obrazu	Deduplikacja	Intencja
Lossless	100%	Wyłączona	Brak utraty jakości; intencja wyniku stabilnego bajtowo
Balanced	75%	Włączona	Umiarkowany kompromis jakości; wartość domyślna
Aggressive	50%	Włączona	Maksymalna redukcja; próbkowanie w dół; widoczna utrata jakości

Lossless pomija deduplikację, aby wynik mógł pozostać stabilny bajtowo. Docelowa jakość zasila arytmetykę sugestii obrazów poniżej.

Analiza deduplikacji

Deduplikator skanuje definicje obiektów pośrednich o generacji zero (N 0 obj do endobj). Każda treść jest przycinana z otaczających białych znaków, haszowana algorytmem SHA-256 i grupowana według skrótu. Definicje różniące się tylko dopełnieniem nadal się zatem dopasowują. Zwracane są tylko grupy z dwoma lub więcej członkami. Szacowane oszczędności dla grupy równają się liczbie duplikatów pomnożonej przez rozmiar pojedynczej treści, ponieważ można usunąć wszystkie obiekty poza kanonicznym.

Analiza obrazów

Obiekt jest traktowany jako obraz, gdy jego treść zawiera /Subtype /Image (z wewnętrzną spacją lub bez niej). Szerokość i wysokość są wymagane; obiekt pozbawiony którejkolwiek z nich jest pomijany. W razie braku przestrzeń barw domyślnie przyjmuje DeviceRGB, liczba bitów na składową 8, a filtr pusty łańcuch. Rozmiar strumienia jest mierzony między znacznikami stream i endstream; gdy nie znaleziono strumienia wbudowanego, zamiast tego używana jest wartość /Length.

Heurystyki sugestii

• Na poziomie Lossless bieżący filtr jest zachowywany, a szacowane oszczędności wynoszą zero.
• Dla źródeł DCTDecode sugestia ponownie koduje przy jakości poziomu. Szacunek to rozmiar strumienia razy (1 − jakość/100) razy 0.5.
• Dla źródeł FlateDecode sugestia konwertuje na DCTDecode. Szacunek to 40% rozmiaru strumienia przy Balanced i 60% przy Aggressive.
• Dla dowolnego innego filtra lub braku filtra sugestia konwertuje na FlateDecode. Szacunek to 20% rozmiaru strumienia.

Arytmetyka wyniku

• Liczba usuniętych obiektów równa się sumie — po wszystkich grupach duplikatów — członków poza kanonicznym pierwszym.
• Całkowite oszczędności równają się oszczędnościom z deduplikacji plus szacunki sugestii dla poszczególnych obrazów.
• Szacowany rozmiar po optymalizacji to rozmiar oryginalny minus całkowite oszczędności, ograniczony od dołu do zera. Oszczędności są nieujemne, więc szacunek nigdy nie przekracza rozmiaru oryginalnego.
• Liczba obrazów po odejmuje, dla każdej grupy duplikatów zawierającej analizowany obraz, liczbę duplikujących się członków tej grupy. Liczba jest ograniczana od dołu do zera.
• Czas przetwarzania jest mierzony zegarem monotonicznym i raportowany w milisekundach.

Estymator DPI dzieli szerokość w pikselach przez szerokość wyświetlania w calach (72 punkty na cal). Zerowa lub ujemna szerokość wyświetlania daje 0.0. Predykat nadmiarowej rozdzielczości porównuje szacunek z celem, domyślnie 300 DPI.

Przypadki brzegowe i tryby awarii

• analyze zgłasza wyłącznie potencjał. Zoptymalizowany wynik wytwarzaj za pomocą modułu Writer.
• Puste dane wejściowe lub dane niezaczynające się od nagłówka %PDF kończą się błędem InvalidArgumentException.
• Dane wejściowe powyżej 100,000,000 bajtów kończą się błędem OverflowException u wejścia orkiestratora, przed jakimkolwiek skanowaniem.
• Deduplikator niezależnie odrzuca dane wejściowe powyżej 268,435,456 bajtów oraz ponad 500,000 znaczników obiektów. Oba odrzucenia następują fail-closed z InvalidArgumentException; nic nie jest obcinane ani częściowo skanowane.
• Uczestniczą wyłącznie definicje obiektów o generacji zero. Obiekty o niezerowych numerach generacji nie są skanowane.
• Definicja bez zamykającego znacznika endobj jest pomijana.
• Obiekty obrazów bez jawnej szerokości i wysokości są wykluczane z raportu obrazów.
• Wszystkie liczby oszczędności są heurystykami wywiedzionymi z metadanych obiektów, a nie zmierzonymi wynikami ponownej kompresji.
• Poziom lossless celowo zgłasza niewielkie redukcje; zachowuje jakość i pomija deduplikację.
• Analiza nigdy nie dekoduje, nie wykonuje ani nie renderuje osadzonej treści. Odczytuje wyłącznie strukturę obiektów i metadane.
• Jedynym używanym prymitywem kryptograficznym jest SHA-256, do grupowania zduplikowanych treści. Moduł nie definiuje zachowania specyficznego dla FIPS.

Zgodność ze standardami

Oba skanery operują na modelu obiektów i obrazów PDF według ISO 32000-2:2020. Deduplikacja dotyczy definicji obiektów pośrednich; struktura ich identyfikatorów jest zdefiniowana w ISO 32000-2:2020, 7.3.10, cytowanym w rekordzie cytatów tej strony. Analiza obrazów odczytuje parametry, które słownik obrazu podaje jawnie — szerokość, wysokość i liczbę bitów na składową — zgodnie z ISO 32000-2:2020, 8.9.4, również cytowanym.

Te stwierdzenia opisują funkcję w odniesieniu do cytowanych klauzul. NextPDF nie posiada certyfikacji zgodności, a wsparcie dla klauzuli nie jest deklaracją certyfikacji.

Uwagi deweloperskie

• Źródło modułu zawiera @since 1.9.0; ta dokumentacja opisuje powierzchnię w postaci dostarczonej w nextpdf/pro 3.1.0.
• Wszystkie klasy są final; rekordy wyników i analizy to obiekty wartości readonly. Twórz nowe instancje zamiast mutować.
• Domyślny poziom to Balanced. Wybierz inny poziom przez konstruktor lub metodę w stylu with.
• Wejściowe ograniczenie u wejścia jest egzekwowane przez strażnika rozmiaru danych wejściowych Core, współdzielonego przez powierzchnie wejściowe NextPDF.
• Analiza opiera się na łańcuchach nad bajtami już w pamięci. Moduł nie wykonuje żadnego dostępu do systemu plików ani sieci.
• Szczegóły wewnętrznych mechanizmów pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie i wspieraną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków i prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Optimizer — strona funkcji z przewodnikiem po przepływie pracy i przykładami kodu.
• Writer — szczegółowa dokumentacja referencyjna — wytwarza zoptymalizowany dokument wyjściowy.
• Accelerator — szczegółowa dokumentacja referencyjna — wsadowa optymalizacja z odciążeniem sidecar przy semantyce tego modułu.