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

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لوحدة ⁨Filter⁩ في ⁨NextPDF Pro⁩، ضمن مجال الأسماء NextPDF\Pro\Filter. يتألّف السطح من صنفين. يحلّل DecodeParms جزءًا من قاموس ⁨PDF⁩ من نوع /DecodeParms إلى كائن قيمة غير قابل للتغيير ومُتحقَّق من حدوده. ويعكس PngPredictor عائلة مُتنبِّئ ⁨PNG⁩ (الوسوم 10-15) على بايتات تدفّق مفكوكة بـ⁨FlateDecode⁩. تخدم هذه الوحدة مُستخلِصَي ⁨Diff⁩ و⁨Classifier⁩ في ⁨Pro⁩. وهي ليست إطارًا عامًّا لمرشّحات التدفّق. تبيّن هذه الصفحة واجهة برمجة التطبيقات العامة، وعقد السلوك القابل للرصد، وأنماط الإخفاق المُصنَّفة نوعيًّا. أما إرشادات الاستخدام وعيّنات الشيفرة فتوجد في صفحة قدرة ⁨Filter⁩.

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

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

لا تحجب أي علامة قدرة في وقت التشغيل هذه الوحدة. وتتوفّر أصناف ⁨Filter⁩ متى كان nextpdf/pro مُثبَّتًا.

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

الرمز	الوسائط	السلوك الافتراضي	يُعيد	يرمي أو يُخفِق بـ	ملاحظات
DecodeParms	المُنشئ: int $predictor = 1، int $columns = 1، int $colors = 1، int $bitsPerComponent = 8	الافتراضات تُرمّز «لا مُتنبِّئ»	—	—	final readonly؛ جميع الخصائص الأربع عامة وغير قابلة للتغيير
DecodeParms::fromDictionary()	string $raw — نص القاموس الخام، مع التسامح مع جسم الكائن المحيط	المفاتيح الغائبة تحتفظ بافتراضاتها؛ والمطابقة متسامحة مع المسافات البيضاء	self	InvalidArgumentException	نقطة الاختناق عند التحليل؛ والحدود مُدرَجة في عقد السلوك
DecodeParms::isPngPredictor()	لا شيء	مُسنِد نقي؛ بلا إدخال/إخراج	bool — true للمُتنبِّئ 10-15	—	تفرّع بناءً عليه قبل استدعاء المرشّح العكسي
PngPredictor	—	بلا حالة	—	—	final؛ ونقطة الدخول الوحيدة هي inverse() الساكنة
PngPredictor::inverse()	string $raw، int $columns، int $colors، int $bitsPerComponent، int $predictor	يعكس المرشحة صفًّا صفًّا بحسب وسم كل صفّ؛ والإدخال الفارغ يُعيد سلسلة فارغة	string — الحمولة المُعاد بناؤها مع تجريد وسوم المرشّح	InvalidArgumentException	يقبل المُتنبِّئ 10-15 فقط؛ ومُتنبِّئ ⁨TIFF⁩ خارج النطاق

تواقيع نقاط الدخول

public function __construct(
    public int $predictor = 1,
    public int $columns = 1,
    public int $colors = 1,
    public int $bitsPerComponent = 8,
) {}

public static function fromDictionary(string $raw): self

public function isPngPredictor(): bool

public static function inverse(
    string $raw,
    int $columns,
    int $colors,
    int $bitsPerComponent,
    int $predictor,
): string

عقد السلوك

تحليل /DecodeParms

يطابق DecodeParms::fromDictionary() أربعة مفاتيح معروفة كأعداد صحيحة في نص القاموس الخام: /Predictor و/Columns و/Colors و/BitsPerComponent. وهذه هي وسائط المُتنبِّئ التي يُعرِّفها ⁨ISO 32000-2:2020 §7.4.4.4⁩ للمرشّحين LZWDecode وFlateDecode. والمطابقة متسامحة مع المسافات البيضاء وتصمد أمام رموز ⁨PDF⁩ المحيطة. وتحتفظ المفاتيح الغائبة بافتراضاتها: المُتنبِّئ 1، والأعمدة 1، والألوان 1، والبِتّات لكل مكوّن 8. أما القيم الحاضرة فيُتحقَّق منها بمبدأ الإخفاق المُغلَق في وقت التحليل، قبل أن تصل أي هندسة إلى تخصيص صفّ المرشّح العكسي:

• تُرفَض أي قيمة سالبة حاضرة لأي مفتاح معروف.
• يُرفَض /Columns الأكبر من 1,000,000.
• يُرفَض /Colors الأكبر من 32.
• يُرفَض /BitsPerComponent خارج {1, 2, 4, 8, 16}.
• تُرفَض خطوة الصفّ المشتقّة الأكبر من 64,000,000 بايت.

يُعيد isPngPredictor() القيمة true عندما يكون المُتنبِّئ المُحلَّل من 10 إلى 15. أما المُتنبِّئ 1 (بلا تنبّؤ) والمُتنبِّئ 2 (مجموعة ⁨TIFF⁩) فيُعيدان false.

هندسة الصفّ

يستهلك PngPredictor::inverse() تدفّق بايتات مفكوكًا بـ⁨FlateDecode⁩ يسبق كلَّ صفّ فيه وسم مرشّح بحجم بايت واحد. ويُصدِر الحمولة المُعاد بناؤها مع تجريد الوسوم. وعرض حمولة الصفّ هو ceil(columns * colors * bitsPerComponent / 8) بايت؛ وتضيف خطوة الصفّ بايت وسم واحدًا. وإزاحة الجار الأيسر (البايتات لكل بكسل) هي max(1, floor(colors * bitsPerComponent / 8))، ولذلك تُقرَّب التعبئات الأصغر من البايت إلى بايت واحد. وتعمل المرشحة على بايتات كاملة بصرف النظر عن عمق البِتّ، مطابقةً لدلالات مرشّح ⁨PNG⁩.

إعادة بناء كل صفّ

الوسم	المرشّح	إعادة البناء
0	None	تمرير مباشر
1	Sub	recon[x] = filt[x] + recon[x-bpp]
2	Up	recon[x] = filt[x] + prior[x]
3	Average	recon[x] = filt[x] + floor((recon[x-bpp] + prior[x]) / 2)
4	Paeth	recon[x] = filt[x] + Paeth(left, up, up-left)

تُؤخَذ كل المجاميع بمعامل 256. وبالنسبة للصفّ الأول، وللبايتات الواقعة يسار البكسل الأول، يُقرأ الجار المفقود بقيمة صفر، وفق ⁨W3C PNG §9.2⁩. والعملية العكسية مدفوعة كليًّا بوسم كل صفّ. وهذا هو السلوك المطابق لكلٍّ من المُتنبِّئات الثابتة (10-14) و⁨Optimum⁩ (15) وفق ⁨ISO 32000-2:2020 §7.4.4.4⁩، ولذا يُتسامَح مع تباين الوسوم بين الكُتّاب.

طبقات التحقّق

يجري التحقّق من الوسائط في طبقتين بحسب التصميم. فـDecodeParms هو نقطة الاختناق عند التحليل ويرفض المقادير العدائية أولًا. ويحتفظ PngPredictor::inverse() بفحوصه الخاصة كطبقة ثانية: فحوص المدى على الوسائط الأربع جميعها، وحُرّاس الطفحان الذين يقارنون العوامل المفردة بـPHP_INT_MAX قبل تكوين حاصل ضرب الخطوة، وسقف الصفّ ذاته البالغ 64,000,000 بايت، وحدّ متناسب مع الإدخال يرفض أي خطوة مُعلَنة أكبر من الإدخال بأكمله قبل تخصيص أي مخزن صفّ.

الحتمية

كلتا نقطتَي الدخول دالّتان ساكنتان نقيّتان لمُدخلاتهما. لا يوجد إدخال/إخراج، ولا تسجيل، ولا حالة عامة. وزمن التشغيل خطّي في طول الإدخال بثابت صغير لكل بايت. وتحليل /DecodeParms هو بضع مطابقات محدودة لتعبيرات نمطية. والميزانيات مُبيَّنة في performance_budget بالمقدّمة (‏⁨frontmatter⁩).

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

يرفع كل إخفاق في هذه الوحدة InvalidArgumentException مع تسمية القيمة المخالفة في الرسالة.

• يرفض fromDictionary() أي قيمة سالبة حاضرة لأي مفتاح معروف.
• يرفض fromDictionary() القيمة /Columns الأكبر من 1,000,000 والقيمة /Colors الأكبر من 32.
• يرفض fromDictionary() القيمة /BitsPerComponent خارج {1, 2, 4, 8, 16} وخطوة صفّ مشتقّة أكبر من 64,000,000 بايت.
• يرفض inverse() أي مُتنبِّئ خارج 10-15. ولا يُعكَس مُتنبِّئ ⁨TIFF⁩ (2) هنا أبدًا؛ تفرّع بناءً على isPngPredictor() أولًا.
• يرفض inverse() القيمة columns أو colors الأقل من 1، والقيمة bitsPerComponent خارج المجموعة القانونية.
• يرفض inverse() أي هندسة يطفح حاصل ضرب خطوتها عن عدد المنصّة الصحيح، قبل أي تخصيص.
• يرفض inverse() أي خطوة صفّ أكبر من سقف الصفّ البالغ 64,000,000 بايت، بصرف النظر عن طول الإدخال الفعلي.
• يُعيد inverse() سلسلة فارغة للإدخال الفارغ؛ وليس ذلك خطأً.
• يُخفِق inverse() عند خطوة صفّ مُعلَنة أكبر من الإدخال بأكمله، معتبِرًا إياها صفًّا مقتطعًا عند الإزاحة 0.
• يُخفِق inverse() عند صفّ جزئي زائل في النهاية، معتبِرًا إياه صفًّا مقتطعًا، مع تسمية الإزاحة وعدد البايتات.
• يُخفِق inverse() عند وسم مرشّح غير معروف لكل صفّ (ليس 0-4)، مع قيمة الوسم وإزاحة الصفّ.
• يظهر عدم التطابق بين هندسة /DecodeParms المُعلَنة والتخطيط الفعلي للتدفّق على هيئة خطأ وسيط أو اقتطاع، ولا يظهر أبدًا على هيئة مُخرَج تالف بصمت.
• يستخدم مرشّح ⁨Average⁩ القسمة الصحيحة، مطابقًا دلالات ⁨floor⁩ في مواصفة ⁨PNG⁩.
• لا تجري أي عملية تشفير في هذه الوحدة. والسلوك متطابق في عمليات النشر المقيَّدة بـ⁨FIPS⁩.

المطابقة

الادّعاء	المعيار	البند
تختار وسيطة المرشّح /Predictor خوارزمية المُتنبِّئ؛ وتأتي القيم المسموح بها من جدول قيم المُتنبِّئ.	ISO 32000-2:2020	§7.4.4.4
يُعرِّف ⁨PDF⁩ مجموعتَي مُتنبِّئ: مجموعة ⁨TIFF⁩ هي دالّة المُتنبِّئ 2 الوحيدة؛ ومجموعة ⁨PNG⁩ هي الوسوم 10-15.	ISO 32000-2:2020	§7.4.4.4
القيم الصالحة لـ/BitsPerComponent هي 1 و2 و4 و8 و16 بقيمة افتراضية 8؛ و/Colors تساوي 1 أو أكثر بقيمة افتراضية 1؛ و/Columns قيمتها الافتراضية 1.	ISO 32000-2:2020	§7.4.4.4
تعمل دوالّ إعادة البناء لأنواع المرشّح 0-4 على أساس البايت بمعامل 256؛ وتُقرأ بايتات اليسار والصفّ السابق الغائبة بقيمة صفر.	W3C PNG (Third Edition)	§9.2
يحسب نوع المرشّح ⁨Paeth⁩ الدالّة PaethPredictor للجيران الأيسر والأعلى والأعلى-يسار ويختار الأقرب.	W3C PNG (Third Edition)	§9.4

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

ملاحظات التطوير

• يُشحَن الصنفان منذ nextpdf/pro ⁨3.0.0⁩ وهما حاليّان في 3.1.0.
• تستهلك هذه الوحدةَ مُستخلِصاتُ ⁨Diff⁩ و⁨Classifier⁩ في ⁨Pro⁩ عندما تحمل مُدخلاتها مُتنبِّئًا.
• تفرّع بناءً على isPngPredictor() قبل استدعاء inverse()؛ فالمُتنبِّئ 1 ومُتنبِّئ ⁨TIFF⁩ لا يحتاجان إلى عكس ⁨PNG⁩.
• تحدّ الوحدة تخصيصها لكل صفّ بنفسها. ومع ذلك ينبغي للمستدعين الذين يعكسون المُتنبِّئات على تدفّقات غير موثوقة أن يحدّوا حجم الإدخال المفكوك عند المنبع، كما تفعل مُستخلِصات ⁨Pro⁩.
• تتشارك المُتنبِّئات الثابتة (10-14) و⁨Optimum⁩ (15) مسار شيفرة واحدًا؛ ووسم كل صفّ يقود إعادة البناء في الحالتين.
• تبقى تفاصيل الآلية الداخلية في التوثيق الداخلي لمستودع المصدر، وهي خارج نطاق هذا الدليل.

حدود النشر

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

انظر أيضًا

• ‏⁨Filter⁩ (القدرة) — التثبيت والبدء السريع وعيّنات الاستخدام الإنتاجي.
• ‏⁨Diff⁩ — مرجع متعمّق — مستهلِك للمرشّح العكسي.
• ‏⁨Classifier⁩ — مرجع متعمّق — مستهلِك للمرشّح العكسي.