‏⁨Optimizer⁩ — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع المتعمّق للسطح العام لـNextPDF\Pro\Optimizer. تغطّي مُنسِّق التحليل، ومستويات التحسين، والماسحين، وكائنات قيمة النتيجة. وتنصّ على المعامِلات، والقيم الافتراضية، وحساب التقدير، وأنماط الإخفاق. والتحليل للقراءة فقط: يُقدِّر المدّخرات ولا يُنتِج أي مستند مخرَج. اقرأ صفحة إمكانية ‏⁨Optimizer⁩ أولًا للإرشاد حول سير العمل.

التوفّر والترخيص

تُشحَن هذه الإمكانية في ‏⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمظروف ترخيص من فئة ‏⁨Pro⁩. ولا يُحمِّل أي نشر يفتقر إلى ذلك الاستحقاق أصنافَ هذه الإمكانية. قارِن الإصدارات واحصل على ترخيص.

لا يملك ‏⁨Optimizer⁩ علامة ترخيص لكل ميزة. فهذه إمكانية من إصدار ‏⁨Pro⁩. ومستوى التحسين معامِل في وقت التشغيل، لا مفتاح ترخيص.

سطح واجهة برمجة التطبيقات العامة

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	تعداد مدعوم بالسلاسل النصية لمستويات الحِدّة	—	—	القيم الداعمة 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	لا شيء مُعلَن	جميع الخصائص عامة و‏⁨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	يستخرج البيانات الوصفية لكل كائن صورة من نوع ‏⁨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% من حجم التدفّق.

حساب النتيجة

• الكائنات المُزالة تساوي مجموع الأعضاء الزائدين عن الأول القانوني عبر جميع المجموعات المكرَّرة.
• إجمالي المدّخرات يساوي مدّخرات إزالة التكرار زائد تقديرات اقتراح كل صورة.
• الحجم المُحسَّن المُقدَّر هو الحجم الأصلي ناقص إجمالي المدّخرات، بحدّ أدنى صفر. والمدّخرات غير سالبة، فلا يتجاوز التقدير الحجم الأصلي أبدًا.
• يطرح عدد الصور بعدُ، لكل مجموعة مكرَّرة تحتوي على صورة مُحلَّلة، عددَ الأعضاء المكرَّرين في تلك المجموعة. والعدد بحدّ أدنى صفر.
• يُقاس زمن المعالجة بساعة رتيبة ويُبلَّغ عنه بالميلي ثانية.

يقسم مُقدِّر ‏⁨DPI⁩ عرض البكسل على عرض المعاينة بالبوصة (72 نقطة لكل بوصة). ويُنتِج عرض المعاينة الصفري أو السالب 0.0. ويقارن مُسنَد فرط الدقة التقديرَ بهدف، هو 300 ‏⁨DPI⁩ افتراضيًا.

الحالات الحدّية وأنماط الإخفاق

• يبلّغ analyze عن الإمكان فقط. أنتِج المخرَج المُحسَّن بوحدة ‏⁨Writer⁩.
• يفشل الإدخال الفارغ، أو الذي لا يبدأ بترويسة %PDF، بـInvalidArgumentException.
• يفشل الإدخال الذي يتجاوز 100,000,000 بايت بـOverflowException عند باب المُنسِّق الأمامي، قبل أي مسح.
• يرفض مُزيل التكرار مستقلًّا الإدخالَ الذي يتجاوز 268,435,456 بايت وأكثر من 500,000 علامة كائن. ويرفض كلاهما بالإغلاق الآمن بـ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⁩.
• التحليل قائم على السلاسل النصية فوق بايتات موجودة في الذاكرة أصلًا. ولا تُجري الوحدة أي وصول إلى نظام الملفات أو الشبكة.
• تبقى تفاصيل الآلية الداخلية في التوثيق الداخلي لمستودع المصدر وهي خارج نطاق هذا الدليل.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح واجهة برمجة التطبيقات العامة المدعوم فقط. أما مسارات فضاء الأسماء الداخلية، وأصناف المساعدة، وجداول الآليات، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر فخارج النطاق.

انظر أيضًا

• ‏⁨Optimizer⁩ — صفحة الإمكانية للإرشاد حول سير العمل وأمثلة الشيفرة.
• ‏⁨Writer⁩ — مرجع متعمّق — يُنتِج مستند المخرَج المُحسَّن.
• ‏⁨Accelerator⁩ — مرجع متعمّق — تحسين الدُّفعات مع إفراغ الحِمل إلى مُرافِق بدلالات هذه الوحدة.