Optimizer — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Pro\Optimizer genel yüzeyi için derinlemesine başvurudur. Analiz düzenleyicisini, optimizasyon düzeylerini, iki tarayıcıyı ve sonuç değer nesnelerini kapsar. Parametreleri, varsayılanları, tahmin aritmetiğini ve hata modlarını belirtir. Analiz salt okunurdur: tasarrufları tahmin eder ve hiçbir çıktı belgesi üretmez. İş akışı rehberliği için önce Optimizer yetenek sayfasını okuyun.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Optimizer’ın özellik başına lisans bayrağı yoktur. Bu, bir Pro sürümü yeteneğidir. Optimizasyon düzeyi bir çalışma zamanı parametresidir, bir lisans anahtarı değildir.

Genel API yüzeyi

composer require nextpdf/pro:^3

nextpdf/premium meta paketi nextpdf/pro kodunu yükler; bu modül NextPDF\Pro\Optimizer ad alanı altında bulunur.

Simge	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Verilen düzeyde bir optimize edici oluşturur	PdfOptimizer	Bildirilmiş yok	Kendi tarayıcı örneklerini oluşturur
PdfOptimizer::analyze	string $pdfData	Yapılandırılmış düzeyde salt okunur analiz	OptimizationResult	100,000,000 baytın üzerindeki girdide OverflowException; geçersiz PDF verisinde tarayıcılardan InvalidArgumentException	Yalnızca tahmin eder; hiçbir çıktı belgesi üretmez
PdfOptimizer::withLevel	OptimizationLevel $level	İstenen düzeyde yeni bir optimize edici döndürür	self	Bildirilmiş yok	Alıcı örnek değişmez
OptimizationLevel	Lossless, Balanced, Aggressive durumları	Agresiflik düzeylerinin string destekli enum’u	—	—	Destekleyen değerler lossless, balanced, aggressive
OptimizationLevel::label	yok	İnsan tarafından okunabilir düzey etiketi	string	Bildirilmiş yok	Görüntüleme amaçlı
OptimizationLevel::imageQuality	yok	Düzey için hedef görüntü kalitesi	int	Bildirilmiş yok	100, 75 veya 50
OptimizationLevel::deduplicateStreams	yok	Düzeyin yineleme kaldırmayı etkinleştirip etkinleştirmediği	bool	Bildirilmiş yok	Yalnızca Lossless için false
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Değişmez analiz sonucu	OptimizationResult	Bildirilmiş yok	Tüm özellikler public ve readonly’dir
OptimizationResult::savedBytes	yok	Özgün boyut eksi tahmini optimize edilmiş boyut	int	Bildirilmiş yok	Bayt
OptimizationResult::savedPercent	yok	Yüzde olarak boyut azalması	float	Bildirilmiş yok	Özgün boyut sıfır olduğunda 0.0
OptimizationResult::summary	yok	Çok satırlı, insan tarafından okunabilir rapor	string	Bildirilmiş yok	Boyutlar B, KB veya MB olarak biçimlendirilir
ObjectDeduplicator::findDuplicates	string $pdfData	Aynı nesne gövdelerini SHA-256 karmasına göre gruplar	list<DuplicateGroup>	Eksik bir %PDF başlığında, 268,435,456 baytın üzerindeki girdide veya 500,000’den fazla nesne işaretçisinde InvalidArgumentException	Yalnızca iki veya daha fazla üyeli grupları döndürür
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Grup başına yineleme sayısı çarpı nesne boyutunu toplar	int	Bildirilmiş yok	Bayt
ImageRecompressor::analyzeImages	string $pdfData	Her görüntü XObject’i için meta veri çıkarır	list<ImageAnalysis>	Eksik bir %PDF başlığında InvalidArgumentException	Açık genişlik ve yüksekliği olmayan nesneleri atlar
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Bir filtre önerir ve tasarrufları tahmin eder	ImageCompressionSuggestion	Bildirilmiş yok	Düzeye bağlı sezgisel yöntemler; davranış sözleşmesine bakın
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Değişmez yineleme grubu kaydı	DuplicateGroup	Bildirilmiş yok	İlk nesne numarası, kanonik olarak korunan nesnedir
DuplicateGroup::duplicateCount	yok	Grup boyutu eksi kanonik nesne	int	Bildirilmiş yok	Birleştirmeyle kaldırılabilir nesneler
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Görüntü başına değişmez meta veri kaydı	ImageAnalysis	Bildirilmiş yok	Alanlar, görüntü sözlüğü girdilerini yansıtır
ImageAnalysis::estimatedDpi	float $displayWidthPt	Verilen görüntüleme genişliğinde etkin DPI	float	Bildirilmiş yok	Görüntüleme genişliği sıfır veya negatif olduğunda 0.0
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Hedef DPI’nin üzerindeki alt örnekleme adaylarını işaretler	bool	Bildirilmiş yok	Kesinlikle büyüktür karşılaştırması
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Değişmez öneri kaydı	ImageCompressionSuggestion	Bildirilmiş yok	reason, insan tarafından okunabilir açıklayıcı metindir

Giriş noktası imzaları

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
}

Davranış sözleşmesi

Düzenleme

PdfOptimizer::analyze ham PDF baytlarını kabul eder ve salt okunurdur. Önce güvenilmeyen girdiyi 100,000,000 baytta sınırlar; aşırı büyük girdi, herhangi bir tarama çalışmadan önce OverflowException fırlatır. Ardından düzey izin verdiğinde yineleme kaldırma analizini çalıştırır, her zaman görüntü analizini çalıştırır ve her ikisini tek bir OptimizationResult içinde toplar. withLevel yeni bir optimize edici döndürür; örnekler asla değiştirilmez.

Düzey anlamları

Düzey	Görüntü kalitesi hedefi	Yineleme kaldırma	Amaç
Lossless	100%	Kapalı	Kalite kaybı yok; bayt kararlı çıktı amacı
Balanced	75%	Açık	Orta düzeyde kalite ödünleşimi; varsayılan
Aggressive	50%	Açık	Maksimum azalma; alt örnekleme; görünür kalite kaybı

Lossless, çıktının bayt kararlı kalabilmesi için yineleme kaldırmayı atlar. Kalite hedefi, aşağıdaki görüntü öneri aritmetiğini besler.

Yineleme kaldırma analizi

Yineleme kaldırıcı, üretim sıfır dolaylı nesne tanımlarını (N 0 obj ile endobj arası) tarar. Her gövde, çevresindeki boşluklardan arındırılır, SHA-256 ile karma alınır ve karmaya göre gruplanır. Bu nedenle yalnızca dolgu bakımından farklı olan tanımlar yine de eşleşir. Yalnızca iki veya daha fazla üyeli gruplar döndürülür. Kanonik nesne dışında tümü kaldırılabildiğinden, grup başına tahmini tasarruf, yineleme sayısı çarpı tek gövde boyutuna eşittir.

Görüntü analizi

Bir nesnenin gövdesi /Subtype /Image (iç boşluklu veya boşluksuz) içerdiğinde, nesne bir görüntü olarak değerlendirilir. Genişlik ve yükseklik gereklidir; ikisinden birini eksik olan bir nesne atlanır. Renk uzayı yoksa varsayılan olarak DeviceRGB, bileşen başına bit 8 ve filtre boş bir dizedir. Akış boyutu, stream ve endstream işaretçileri arasında ölçülür; satır içi akış bulunmadığında bunun yerine /Length değeri kullanılır.

Öneri sezgisel yöntemleri

• Lossless düzeyinde geçerli filtre korunur ve tahmini tasarruf sıfırdır.
• DCTDecode kaynakları için öneri, düzeyin kalitesinde yeniden kodlar. Tahmin, akış boyutu çarpı (1 − quality/100) çarpı 0.5’tir.
• FlateDecode kaynakları için öneri DCTDecode’a dönüştürür. Tahmin, Balanced’da akış boyutunun 40%‘ı ve Aggressive’de 60%‘ıdır.
• Başka herhangi bir filtre için veya filtre yoksa, öneri FlateDecode’a dönüştürür. Tahmin, akış boyutunun 20%‘sidir.

Sonuç aritmetiği

• Kaldırılan nesneler, tüm yineleme grupları üzerinde, kanonik ilk nesnenin ötesindeki üyelerin toplamına eşittir.
• Toplam tasarruf, yineleme kaldırma tasarrufu artı görüntü başına öneri tahminlerine eşittir.
• Tahmini optimize edilmiş boyut, özgün boyut eksi toplam tasarruftur ve sıfırda taban yapılır. Tasarruflar negatif olmadığından, tahmin asla özgün boyutu aşmaz.
• Sonrası görüntü sayısı, analiz edilmiş bir görüntü içeren her yineleme grubu için o grubun yineleme üye sayısını çıkarır. Sayı sıfırda taban yapılır.
• İşlem süresi, monoton bir saatle ölçülür ve milisaniye cinsinden bildirilir.

DPI tahmincisi, piksel genişliğini inç cinsinden görüntüleme genişliğine böler (inç başına 72 nokta). Sıfır veya negatif görüntüleme genişliği 0.0 verir. Aşırı çözünürlük yüklemi, tahmini bir hedefle, varsayılan olarak 300 DPI ile karşılaştırır.

Uç durumlar ve hata modları

• analyze yalnızca potansiyeli bildirir. Optimize edilmiş çıktıyı Writer modülüyle üretin.
• Boş girdi veya %PDF başlığıyla başlamayan girdi, InvalidArgumentException ile başarısız olur.
• 100,000,000 baytın üzerindeki girdi, herhangi bir taramadan önce, düzenleyicinin ön kapısında OverflowException ile başarısız olur.
• Yineleme kaldırıcı, bağımsız olarak 268,435,456 baytın üzerindeki girdiyi ve 500,000’den fazla nesne işaretçisini reddeder. Her ikisi de InvalidArgumentException ile hataya kapalı biçimde reddeder; hiçbir şey kesilmez veya kısmen taranmaz.
• Yalnızca üretim sıfır nesne tanımları katılır. Sıfır olmayan üretim numaralı nesneler taranmaz.
• Kapanış endobj işaretçisi olmayan bir tanım atlanır.
• Açık genişlik ve yüksekliği olmayan görüntü nesneleri, görüntü raporundan hariç tutulur.
• Tüm tasarruf rakamları, ölçülmüş yeniden sıkıştırma sonuçları değil, nesne meta verisinden türetilen sezgisel değerlerdir.
• Kayıpsız düzey kasıtlı olarak küçük azalmalar bildirir; kaliteyi korur ve yineleme kaldırmayı atlar.
• Analiz, gömülü içeriği asla çözmez, yürütmez veya işlemez. Yalnızca nesne yapısını ve meta verisini okur.
• Kullanılan tek kriptografik ilkel, yinelenen içerik gruplama için SHA-256’dır. Modül hiçbir FIPS’e özgü davranış tanımlamaz.

Uygunluk

Her iki tarayıcı da ISO 32000-2:2020’nin PDF nesne ve görüntü modeli üzerinde çalışır. Yineleme kaldırma, dolaylı nesne tanımlarını hedefler; bunların tanımlayıcı yapısı, bu sayfanın alıntı kaydında belirtilen ISO 32000-2:2020, 7.3.10’da tanımlanır. Görüntü analizi, bir görüntü sözlüğünün açıkça belirttiği parametreleri — genişlik, yükseklik ve bileşen başına bit — yine belirtilen ISO 32000-2:2020, 8.9.4’e göre okur.

Bu ifadeler, belirtilen maddelere karşı yeteneği açıklar. NextPDF hiçbir uygunluk sertifikasına sahip değildir ve bir maddenin desteklenmesi bir sertifikasyon iddiası değildir.

Geliştirme notları

• Modül kaynağı @since 1.9.0 taşır; bu başvuru, nextpdf/pro 3.1.0 ile birlikte gelen yüzeyi belgeler.
• Tüm sınıflar final’dır; sonuç ve analiz kayıtları readonly değer nesneleridir. Değiştirmek yerine yeni örnekler oluşturun.
• Varsayılan düzey Balanced’dır. Yapıcı aracılığıyla veya with tarzı yöntemle başka bir düzey seçin.
• Ön kapı girdi sınırı, NextPDF girdi yüzeyleri arasında paylaşılan bir Core girdi boyutu koruyucusuyla uygulanır.
• Analiz, zaten bellekte olan baytlar üzerinde dize tabanlıdır. Modül hiçbir dosya sistemi veya ağ erişimi gerçekleştirmez.
• Dahili mekanizma ayrıntısı, kaynak deposunun dahili belgelerinde kalır ve bu kılavuzun kapsamı dışındadır.

Yayın sınırı

Bu sayfa, yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Optimizer — iş akışı rehberliği ve kod örnekleri için yetenek sayfası.
• Writer — Derinlemesine başvuru — optimize edilmiş çıktı belgesini üretir.
• Accelerator — Derinlemesine başvuru — bu modülün anlamlarında sidecar boşaltmayla toplu optimizasyon.