Optimizer — การอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

หน้านี้เป็นการอ้างอิงเชิงลึกสำหรับพื้นผิวสาธารณะของ NextPDF\Pro\Optimizer ครอบคลุมตัวจัดการวิเคราะห์ ระดับการปรับให้เหมาะสม ตัวสแกนทั้งสอง และอ็อบเจกต์ค่าผลลัพธ์ ระบุพารามิเตอร์ ค่าเริ่มต้น เลขคณิตของการประมาณการ และโหมดความล้มเหลว การวิเคราะห์เป็นแบบอ่านอย่างเดียว: มันประมาณการประหยัดและไม่สร้างเอกสารเอาต์พุต อ่านหน้าความสามารถ 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	OverflowException เมื่ออินพุตเกิน 100,000,000 ไบต์; InvalidArgumentException จากตัวสแกนเมื่อข้อมูล PDF ไม่ถูกต้อง	ประมาณการเท่านั้น; ไม่สร้างเอกสารเอาต์พุต
PdfOptimizer::withLevel	OptimizationLevel $level	คืนค่าตัวปรับให้เหมาะสมใหม่ที่ระดับที่ร้องขอ	self	ไม่ประกาศไว้	อินสแตนซ์ที่รับไม่เปลี่ยนแปลง
OptimizationLevel	เคส Lossless, Balanced, Aggressive	enum แบบ string-backed ของระดับความเข้มข้น	—	—	ค่าที่รองรับ lossless, balanced, aggressive
OptimizationLevel::label	ไม่มี	ป้ายกำกับระดับที่มนุษย์อ่านได้	string	ไม่ประกาศไว้	ใช้สำหรับแสดงผล
OptimizationLevel::imageQuality	ไม่มี	คุณภาพภาพเป้าหมายสำหรับระดับนั้น	int	ไม่ประกาศไว้	100, 75 หรือ 50
OptimizationLevel::deduplicateStreams	ไม่มี	ระดับเปิดใช้การขจัดข้อมูลซ้ำซ้อนหรือไม่	bool	ไม่ประกาศไว้	false สำหรับ Lossless เท่านั้น
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>	InvalidArgumentException เมื่อไม่มีส่วนหัว %PDF, อินพุตเกิน 268,435,456 ไบต์ หรือมีเครื่องหมายอ็อบเจกต์เกิน 500,000 ตัว	คืนค่าเฉพาะกลุ่มที่มีสมาชิกตั้งแต่สองตัวขึ้นไป
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	รวมจำนวนที่ซ้ำคูณด้วยขนาดอ็อบเจกต์ต่อกลุ่ม	int	ไม่ประกาศไว้	ไบต์
ImageRecompressor::analyzeImages	string $pdfData	แยกเมทาดาทาสำหรับทุก image XObject	list<ImageAnalysis>	InvalidArgumentException เมื่อไม่มีส่วนหัว %PDF	ข้ามอ็อบเจกต์ที่ไม่มีความกว้างและความสูงที่ระบุชัดเจน
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 ก่อนที่การสแกนใด ๆ จะทำงาน จากนั้นจะรันการวิเคราะห์การขจัดข้อมูลซ้ำซ้อนเมื่อระดับอนุญาต รันการวิเคราะห์ภาพเสมอ และรวมทั้งสองเข้าเป็น OptimizationResult เดียว withLevel คืนค่าตัวปรับให้เหมาะสมใหม่; อินสแตนซ์จะไม่ถูกแปลงสภาพ

ความหมายของระดับ

ระดับ	คุณภาพภาพเป้าหมาย	การขจัดข้อมูลซ้ำซ้อน	เจตนา
Lossless	100%	ปิด	ไม่มีการสูญเสียคุณภาพ; เจตนาให้เอาต์พุตไบต์เสถียร
Balanced	75%	เปิด	แลกคุณภาพในระดับปานกลาง; ค่าเริ่มต้น
Aggressive	50%	เปิด	ลดขนาดสูงสุด; ลดความละเอียด; สูญเสียคุณภาพที่มองเห็นได้

Lossless ข้ามการขจัดข้อมูลซ้ำซ้อนเพื่อให้เอาต์พุตคงความไบต์เสถียร คุณภาพเป้าหมายป้อนเข้าสู่เลขคณิตการแนะนำภาพด้านล่าง

การวิเคราะห์การขจัดข้อมูลซ้ำซ้อน

ตัวขจัดข้อมูลซ้ำซ้อนสแกนนิยามอ็อบเจกต์ทางอ้อมของเจเนอเรชันศูนย์ (N 0 obj ถึง endobj) เนื้อความแต่ละส่วนถูกตัดช่องว่างรอบข้างออก แฮชด้วย SHA-256 และจัดกลุ่มตามแฮช นิยามที่ต่างกันเพียงการเติมช่องว่างจึงยังตรงกัน คืนค่าเฉพาะกลุ่มที่มีสมาชิกตั้งแต่สองตัวขึ้นไป การประหยัดโดยประมาณต่อกลุ่มเท่ากับจำนวนที่ซ้ำคูณด้วยขนาดเนื้อความเดี่ยว เนื่องจากอ็อบเจกต์ทั้งหมดยกเว้นอ็อบเจกต์หลักสามารถลบออกได้

การวิเคราะห์ภาพ

อ็อบเจกต์จะถูกถือว่าเป็นภาพเมื่อเนื้อความมี /Subtype /Image (มีหรือไม่มีช่องว่างภายในก็ได้) ต้องมีความกว้างและความสูง; อ็อบเจกต์ที่ขาดอย่างใดอย่างหนึ่งจะถูกข้าม พื้นที่สีมีค่าเริ่มต้นเป็น DeviceRGB บิตต่อองค์ประกอบเป็น 8 และตัวกรองเป็นสตริงว่างเมื่อไม่มี ขนาดสตรีมวัดระหว่างเครื่องหมาย stream และ endstream; เมื่อไม่พบสตรีมแบบอินไลน์ จะใช้ค่า /Length แทน

ฮิวริสติกการแนะนำ

• ที่ระดับ Lossless ตัวกรองปัจจุบันจะถูกเก็บไว้และการประหยัดโดยประมาณเป็นศูนย์
• สำหรับแหล่ง DCTDecode คำแนะนำจะเข้ารหัสใหม่ที่คุณภาพของระดับนั้น การประมาณการคือขนาดสตรีมคูณ (1 − quality/100) คูณ 0.5
• สำหรับแหล่ง FlateDecode คำแนะนำจะแปลงเป็น DCTDecode การประมาณการคือ 40% ของขนาดสตรีมที่ Balanced และ 60% ที่ Aggressive
• สำหรับตัวกรองอื่นใด หรือไม่มีตัวกรอง คำแนะนำจะแปลงเป็น FlateDecode การประมาณการคือ 20% ของขนาดสตรีม

เลขคณิตของผลลัพธ์

• อ็อบเจกต์ที่ลบออกเท่ากับผลรวมของสมาชิกที่เกินจากตัวหลักตัวแรก ในทุกกลุ่มซ้ำซ้อน
• การประหยัดรวมเท่ากับการประหยัดจากการขจัดข้อมูลซ้ำซ้อนบวกกับการประมาณการแนะนำรายภาพ
• ขนาดที่ปรับให้เหมาะสมโดยประมาณคือขนาดดั้งเดิมลบการประหยัดรวม โดยจำกัดขั้นต่ำที่ศูนย์ การประหยัดไม่ติดลบ ดังนั้นการประมาณการจึงไม่เกินขนาดดั้งเดิม
• จำนวนภาพหลังจะลบจำนวนสมาชิกที่ซ้ำของกลุ่มนั้น สำหรับแต่ละกลุ่มซ้ำซ้อนที่มีภาพที่วิเคราะห์แล้ว จำนวนถูกจำกัดขั้นต่ำที่ศูนย์
• เวลาประมวลผลวัดด้วยนาฬิกาแบบ monotonic และรายงานเป็นมิลลิวินาที

ตัวประมาณ DPI หารความกว้างพิกเซลด้วยความกว้างการแสดงผลเป็นนิ้ว (72 พอยต์ต่อนิ้ว) ความกว้างการแสดงผลที่เป็นศูนย์หรือติดลบให้ผลเป็น 0.0 เพรดิเคตความละเอียดเกินเปรียบเทียบการประมาณการกับเป้าหมาย ซึ่งเป็น 300 DPI โดยค่าเริ่มต้น

กรณีขอบและโหมดความล้มเหลว

• analyze รายงานเฉพาะศักยภาพเท่านั้น สร้างเอาต์พุตที่ปรับให้เหมาะสมด้วยโมดูล Writer
• อินพุตว่างเปล่า หรืออินพุตที่ไม่ได้ขึ้นต้นด้วยส่วนหัว %PDF จะล้มเหลวด้วย InvalidArgumentException
• อินพุตที่เกิน 100,000,000 ไบต์จะล้มเหลวด้วย OverflowException ที่ประตูหน้าของตัวจัดการ ก่อนการสแกนใด ๆ
• ตัวขจัดข้อมูลซ้ำซ้อนปฏิเสธอินพุตที่เกิน 268,435,456 ไบต์และเครื่องหมายอ็อบเจกต์เกิน 500,000 ตัวโดยอิสระ ทั้งสองปฏิเสธแบบ fail-closed ด้วย InvalidArgumentException; ไม่มีการตัดทอนหรือสแกนบางส่วน
• เฉพาะนิยามอ็อบเจกต์ของเจเนอเรชันศูนย์เท่านั้นที่เข้าร่วม อ็อบเจกต์ที่มีหมายเลขเจเนอเรชันไม่เป็นศูนย์จะไม่ถูกสแกน
• นิยามที่ไม่มีเครื่องหมายปิด endobj จะถูกข้าม
• อ็อบเจกต์ภาพที่ไม่มีความกว้างและความสูงที่ระบุชัดเจนจะถูกแยกออกจากรายงานภาพ
• ตัวเลขการประหยัดทั้งหมดเป็นฮิวริสติกที่ได้จากเมทาดาทาของอ็อบเจกต์ ไม่ใช่ผลการบีบอัดใหม่ที่วัดได้
• ระดับ lossless รายงานการลดขนาดเล็กน้อยโดยตั้งใจ; มันรักษาคุณภาพและข้ามการขจัดข้อมูลซ้ำซ้อน
• การวิเคราะห์ไม่ถอดรหัส รัน หรือเรนเดอร์เนื้อหาที่ฝังอยู่ มันอ่านโครงสร้างอ็อบเจกต์และเมทาดาทาเท่านั้น
• พรีมิทีฟการเข้ารหัสลับเดียวที่ใช้คือ SHA-256 สำหรับการจัดกลุ่มเนื้อหาซ้ำ โมดูลนี้ไม่นิยามพฤติกรรมเฉพาะของ FIPS

ความสอดคล้องกับมาตรฐาน

ตัวสแกนทั้งสองทำงานบนแบบจำลองอ็อบเจกต์และภาพของ PDF ตาม ISO 32000-2:2020 การขจัดข้อมูลซ้ำซ้อนมุ่งเป้าที่นิยามอ็อบเจกต์ทางอ้อม; โครงสร้างตัวระบุของมันถูกนิยามไว้ใน 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
• ขอบเขตอินพุตที่ประตูหน้าถูกบังคับใช้โดยการ์ดขนาดอินพุตของ Core ที่ใช้ร่วมกันในทุกพื้นผิวอินพุตของ NextPDF
• การวิเคราะห์ทำงานบนสตริงเหนือไบต์ที่อยู่ในหน่วยความจำแล้ว โมดูลนี้ไม่เข้าถึงระบบไฟล์หรือเครือข่าย
• รายละเอียดกลไกภายในอยู่ในเอกสารภายในของที่เก็บซอร์สและอยู่นอกขอบเขตของคู่มือนี้

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทางเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าตั๋วอยู่นอกขอบเขต

ดูเพิ่มเติม

• Optimizer — หน้าความสามารถสำหรับคำแนะนำเวิร์กโฟลว์และตัวอย่างโค้ด
• Writer — การอ้างอิงเชิงลึก — สร้างเอกสารเอาต์พุตที่ปรับให้เหมาะสม
• Accelerator — การอ้างอิงเชิงลึก — การปรับให้เหมาะสมแบบชุดพร้อมการถ่ายโอนงานแบบ sidecar ตามความหมายของโมดูลนี้