Optimizer — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu chuyên sâu cho bề mặt công khai của NextPDF\Pro\Optimizer. Nó bao quát bộ điều phối phân tích, các mức tối ưu hóa, hai bộ quét, và các đối tượng giá trị kết quả. Nó nêu rõ tham số, giá trị mặc định, số học ước tính, và các chế độ lỗi. Việc phân tích là chỉ-đọc: nó ước tính khoản tiết kiệm và không tạo ra tài liệu đầu ra nào. Hãy đọc trang năng lực Optimizer trước để có hướng dẫn quy trình.

Tình trạng khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope bậc Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Optimizer không có cờ giấy phép theo từng tính năng. Đây là một năng lực của phiên bản Pro. Mức tối ưu hóa là một tham số lúc chạy, không phải một công tắc giấy phép.

Bề mặt API công khai

composer require nextpdf/pro:^3

Metapackage nextpdf/premium cài đặt phần mã nextpdf/pro; module này nằm trong namespace NextPDF\Pro\Optimizer.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Dựng một optimizer ở mức đã cho	PdfOptimizer	Không khai báo gì	Tự dựng các thể hiện bộ quét của riêng nó
PdfOptimizer::analyze	string $pdfData	Phân tích chỉ-đọc ở mức đã cấu hình	OptimizationResult	OverflowException khi đầu vào trên 100,000,000 byte; InvalidArgumentException từ các bộ quét khi dữ liệu PDF không hợp lệ	Chỉ ước tính; không tạo tài liệu đầu ra
PdfOptimizer::withLevel	OptimizationLevel $level	Trả về một optimizer mới ở mức được yêu cầu	self	Không khai báo gì	Thể hiện nhận lời gọi không bị thay đổi
OptimizationLevel	các case Lossless, Balanced, Aggressive	Enum nền chuỗi cho các mức độ quyết liệt	—	—	Các giá trị nền lossless, balanced, aggressive
OptimizationLevel::label	không có	Nhãn mức dễ đọc cho người	string	Không khai báo gì	Dùng để hiển thị
OptimizationLevel::imageQuality	không có	Chất lượng ảnh mục tiêu cho mức	int	Không khai báo gì	100, 75, hoặc 50
OptimizationLevel::deduplicateStreams	không có	Liệu mức có bật khử trùng lặp hay không	bool	Không khai báo gì	false chỉ với Lossless
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Kết quả phân tích bất biến	OptimizationResult	Không khai báo gì	Mọi thuộc tính đều public và readonly
OptimizationResult::savedBytes	không có	Kích thước gốc trừ kích thước tối ưu ước tính	int	Không khai báo gì	Byte
OptimizationResult::savedPercent	không có	Phần trăm giảm kích thước	float	Không khai báo gì	0.0 khi kích thước gốc bằng không
OptimizationResult::summary	không có	Báo cáo nhiều dòng dễ đọc cho người	string	Không khai báo gì	Kích thước định dạng theo B, KB, hoặc MB
ObjectDeduplicator::findDuplicates	string $pdfData	Nhóm các thân đối tượng giống hệt nhau theo băm SHA-256	list<DuplicateGroup>	InvalidArgumentException khi thiếu header %PDF, đầu vào trên 268,435,456 byte, hoặc hơn 500,000 dấu đối tượng	Chỉ trả về các nhóm có từ hai thành viên trở lên
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Cộng số lượng bản trùng nhân với kích thước đối tượng theo từng nhóm	int	Không khai báo gì	Byte
ImageRecompressor::analyzeImages	string $pdfData	Trích xuất metadata cho mọi image XObject	list<ImageAnalysis>	InvalidArgumentException khi thiếu header %PDF	Bỏ qua các đối tượng không có chiều rộng và chiều cao tường minh
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Đề xuất một filter và ước tính khoản tiết kiệm	ImageCompressionSuggestion	Không khai báo gì	Heuristic phụ thuộc vào mức; xem hợp đồng hành vi
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Bản ghi nhóm-trùng-lặp bất biến	DuplicateGroup	Không khai báo gì	Số đối tượng đầu tiên là đối tượng chuẩn được giữ lại
DuplicateGroup::duplicateCount	không có	Kích thước nhóm trừ đối tượng chuẩn	int	Không khai báo gì	Các đối tượng có thể loại bỏ bằng cách gộp
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Bản ghi metadata theo từng ảnh bất biến	ImageAnalysis	Không khai báo gì	Các trường phản chiếu các mục của image dictionary
ImageAnalysis::estimatedDpi	float $displayWidthPt	DPI hữu hiệu tại chiều rộng hiển thị đã cho	float	Không khai báo gì	0.0 khi chiều rộng hiển thị bằng không hoặc âm
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Đánh dấu các ứng viên hạ mẫu vượt DPI mục tiêu	bool	Không khai báo gì	So sánh lớn hơn nghiêm ngặt
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Bản ghi khuyến nghị bất biến	ImageCompressionSuggestion	Không khai báo gì	reason là văn bản giải thích dễ đọc cho người

Chữ ký điểm vào

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
}

Hợp đồng hành vi

Điều phối

PdfOptimizer::analyze nhận byte PDF thô và là chỉ-đọc. Trước tiên nó giới hạn đầu vào không tin cậy ở 100,000,000 byte; đầu vào quá cỡ làm phát sinh OverflowException trước khi bất kỳ lần quét nào chạy. Sau đó nó chạy phân tích khử trùng lặp khi mức cho phép, luôn chạy phân tích ảnh, và tổng hợp cả hai vào một OptimizationResult. withLevel trả về một optimizer mới; các thể hiện không bao giờ bị biến đổi.

Ngữ nghĩa của mức

Mức	Chất lượng ảnh mục tiêu	Khử trùng lặp	Ý định
Lossless	100%	Tắt	Không mất chất lượng; chủ ý đầu ra ổn định byte
Balanced	75%	Bật	Đánh đổi chất lượng vừa phải; giá trị mặc định
Aggressive	50%	Bật	Giảm tối đa; hạ mẫu; mất chất lượng thấy rõ

Lossless bỏ qua khử trùng lặp để đầu ra có thể giữ ổn định byte. Chất lượng mục tiêu là đầu vào cho số học gợi ý ảnh bên dưới.

Phân tích khử trùng lặp

Bộ khử trùng lặp quét các định nghĩa đối tượng gián tiếp thế hệ-không (N 0 obj cho tới endobj). Mỗi thân được cắt bỏ khoảng trắng xung quanh, băm bằng SHA-256, và nhóm theo băm. Do đó các định nghĩa chỉ khác nhau ở phần đệm vẫn khớp nhau. Chỉ các nhóm có từ hai thành viên trở lên được trả về. Khoản tiết kiệm ước tính cho mỗi nhóm bằng số lượng bản trùng nhân với kích thước một thân, vì mọi đối tượng ngoài đối tượng chuẩn đều có thể loại bỏ.

Phân tích ảnh

Một đối tượng được coi là ảnh khi thân của nó chứa /Subtype /Image (có hoặc không có khoảng trắng bên trong). Chiều rộng và chiều cao là bắt buộc; một đối tượng thiếu một trong hai sẽ bị bỏ qua. Không gian màu mặc định là DeviceRGB, số bit trên mỗi thành phần là 8, và filter là chuỗi rỗng khi vắng mặt. Kích thước stream được đo giữa các dấu stream và endstream; khi không tìm thấy stream nội tuyến, giá trị /Length được dùng thay thế.

Heuristic gợi ý

• Ở mức Lossless, filter hiện tại được giữ nguyên và khoản tiết kiệm ước tính bằng không.
• Với nguồn DCTDecode, gợi ý mã hóa lại ở chất lượng của mức. Ước tính bằng kích thước stream nhân với (1 − quality/100) nhân với 0.5.
• Với nguồn FlateDecode, gợi ý chuyển sang DCTDecode. Ước tính bằng 40% kích thước stream ở Balanced và 60% ở Aggressive.
• Với bất kỳ filter nào khác, hoặc không có filter, gợi ý chuyển sang FlateDecode. Ước tính bằng 20% kích thước stream.

Số học kết quả

• Số đối tượng loại bỏ bằng tổng, trên tất cả các nhóm trùng lặp, của các thành viên ngoài đối tượng chuẩn đầu tiên.
• Tổng khoản tiết kiệm bằng khoản tiết kiệm khử trùng lặp cộng với các ước tính gợi ý theo từng ảnh.
• Kích thước tối ưu ước tính bằng kích thước gốc trừ tổng khoản tiết kiệm, giới hạn dưới ở không. Khoản tiết kiệm không âm, nên ước tính không bao giờ vượt quá kích thước gốc.
• Số ảnh-sau trừ đi, với mỗi nhóm trùng lặp có chứa một ảnh đã phân tích, số thành viên trùng của nhóm đó. Số đếm được giới hạn dưới ở không.
• Thời gian xử lý được đo bằng đồng hồ đơn điệu và báo cáo theo mili-giây.

Bộ ước tính DPI chia chiều rộng điểm ảnh cho chiều rộng hiển thị tính theo inch (72 point trên một inch). Chiều rộng hiển thị bằng không hoặc âm cho ra 0.0. Vị từ vượt-độ-phân-giải so sánh ước tính với một mục tiêu, mặc định 300 DPI.

Trường hợp biên & chế độ lỗi

• analyze chỉ báo cáo tiềm năng. Hãy tạo đầu ra đã tối ưu bằng module Writer.
• Đầu vào rỗng, hoặc đầu vào không bắt đầu bằng header %PDF, thất bại với InvalidArgumentException.
• Đầu vào trên 100,000,000 byte thất bại với OverflowException ngay tại cửa trước của bộ điều phối, trước bất kỳ lần quét nào.
• Bộ khử trùng lặp độc lập từ chối đầu vào trên 268,435,456 byte và hơn 500,000 dấu đối tượng. Cả hai đều từ chối theo kiểu fail-closed với InvalidArgumentException; không có gì bị cắt cụt hoặc quét một phần.
• Chỉ các định nghĩa đối tượng thế hệ-không tham gia. Các đối tượng có số thế hệ khác không sẽ không được quét.
• Một định nghĩa không có dấu endobj kết thúc sẽ bị bỏ qua.
• Các đối tượng ảnh không có chiều rộng và chiều cao tường minh bị loại khỏi báo cáo ảnh.
• Mọi con số tiết kiệm đều là heuristic suy ra từ metadata đối tượng, không phải kết quả nén lại đã đo.
• Mức lossless chủ ý báo cáo các khoản giảm nhỏ; nó bảo toàn chất lượng và bỏ qua khử trùng lặp.
• Việc phân tích không bao giờ giải mã, thực thi, hay kết xuất nội dung được nhúng. Nó chỉ đọc cấu trúc đối tượng và metadata.
• Nguyên thủy mã hóa duy nhất được dùng là SHA-256, để nhóm nội dung trùng lặp. Module không định nghĩa hành vi đặc thù FIPS nào.

Tính phù hợp

Cả hai bộ quét đều hoạt động trên mô hình đối tượng và ảnh PDF của ISO 32000-2:2020. Khử trùng lặp nhắm vào các định nghĩa đối tượng gián tiếp; cấu trúc định danh của chúng được định nghĩa trong ISO 32000-2:2020, 7.3.10, được trích dẫn trong bản ghi trích dẫn của trang này. Phân tích ảnh đọc các tham số mà một image dictionary nêu tường minh — chiều rộng, chiều cao, và số bit trên mỗi thành phần — theo ISO 32000-2:2020, 8.9.4, cũng được trích dẫn.

Các phát biểu này mô tả năng lực đối chiếu với các điều khoản được trích dẫn. NextPDF không nắm giữ chứng nhận phù hợp nào, và việc hỗ trợ một điều khoản không phải là một tuyên bố chứng nhận.

Ghi chú phát triển

• Mã nguồn module mang @since 1.9.0; tài liệu tham chiếu này mô tả bề mặt như được phát hành trong nextpdf/pro 3.1.0.
• Mọi lớp đều là final; các bản ghi kết quả và phân tích là các đối tượng giá trị readonly. Hãy dựng thể hiện mới thay vì biến đổi.
• Mức mặc định là Balanced. Chọn mức khác thông qua constructor hoặc phương thức kiểu with.
• Giới hạn đầu vào ở cửa trước được thực thi bởi một bộ bảo vệ kích-thước-đầu-vào của Core dùng chung trên các bề mặt đầu vào NextPDF.
• Việc phân tích dựa trên chuỗi trên các byte đã có sẵn trong bộ nhớ. Module không thực hiện truy cập hệ thống tệp hay mạng.
• Chi tiết cơ chế nội bộ được giữ trong tài liệu nội bộ của kho mã nguồn và nằm ngoài phạm vi của cẩm nang này.

Ranh giới công bố

Trang này chỉ mô tả hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket đều nằm ngoài phạm vi.

Xem thêm

• Optimizer — trang năng lực cho hướng dẫn quy trình và mẫu mã.
• Writer — Tài liệu tham chiếu chuyên sâu — tạo ra tài liệu đầu ra đã tối ưu.
• Accelerator — Tài liệu tham chiếu chuyên sâu — tối ưu hóa theo lô với offload sidecar theo ngữ nghĩa của module này.