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

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

หน้านี้เป็นการอ้างอิงระดับสัญญาสำหรับโมดูล NextPDF Pro Filter เนมสเปซ NextPDF\Pro\Filter พื้นผิวประกอบด้วยสองคลาส DecodeParms แจงส่วนย่อยของพจนานุกรม /DecodeParms ของ PDF ให้เป็นออบเจ็กต์ค่าที่เปลี่ยนแปลงไม่ได้และตรวจสอบขอบเขตแล้ว PngPredictor ย้อนตระกูลตัวทำนาย PNG (แท็ก 10-15) บนไบต์สตรีมที่ผ่าน FlateDecode โมดูลนี้ให้บริการแก่ตัวแยก Pro Diff และ Classifier ไม่ใช่เฟรมเวิร์กฟิลเตอร์สตรีมทั่วไป หน้านี้ระบุ API สาธารณะ สัญญาพฤติกรรมที่สังเกตได้ และโหมดความล้มเหลวแบบมีชนิด แนวทางการใช้งานและตัวอย่างโค้ดอยู่ที่ หน้าความสามารถ Filter

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้จัดส่งใน NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การนำไปใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอใบอนุญาต

ไม่มีแฟล็กความสามารถขณะรันที่จำกัดโมดูลนี้ คลาส Filter พร้อมใช้งานเมื่อใดก็ตามที่ติดตั้ง nextpdf/pro แล้ว

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมปริยาย	คืนค่า	ยกข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
DecodeParms	คอนสตรัคเตอร์: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	ค่าปริยายหมายถึง “ไม่มีตัวทำนาย”	—	—	final readonly; คุณสมบัติทั้งสี่เป็น public และเปลี่ยนแปลงไม่ได้
DecodeParms::fromDictionary()	string $raw — ข้อความพจนานุกรมดิบ ยอมรับส่วนตัวออบเจ็กต์ที่ล้อมรอบได้	คีย์ที่ไม่มีจะคงค่าปริยายไว้; การจับคู่ยอมรับช่องว่าง	self	InvalidArgumentException	จุดคอขวดขณะแจง; ขอบเขตระบุไว้ในสัญญาพฤติกรรม
DecodeParms::isPngPredictor()	ไม่มี	เพรดิเคตบริสุทธิ์; ไม่มี I/O	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	passthrough
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 ไบต์เดียวกัน และขอบเขตตามสัดส่วนอินพุตที่ปฏิเสธสไตรด์ที่ประกาศไว้ซึ่งใหญ่กว่าอินพุตทั้งหมดก่อนจะจัดสรรบัฟเฟอร์แถวใดๆ

ความเป็นดีเทอร์มินิสติก

จุดเข้าทั้งสองเป็นฟังก์ชันสแตติกบริสุทธิ์ของอินพุต ไม่มี I/O ไม่มีการบันทึกล็อก และไม่มีสถานะส่วนกลาง เวลาทำงานเป็นเชิงเส้นตามความยาวอินพุตด้วยค่าคงที่ต่อไบต์ขนาดเล็ก การแจง /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 คือฟังก์ชัน Predictor 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
• โมดูลนี้ถูกใช้โดยตัวแยก Pro Diff และ Classifier เมื่ออินพุตของพวกมันมีตัวทำนาย
• แตกกิ่งจาก isPngPredictor() ก่อนเรียก inverse(); ตัวทำนาย 1 และตัวทำนาย TIFF ไม่ต้องการการย้อน PNG
• โมดูลนี้จำกัดการจัดสรรต่อแถวของตนเอง ผู้เรียกที่ย้อนตัวทำนายบนสตรีมที่ไม่น่าเชื่อถือควรจำกัดขนาดอินพุตที่คลายการบีบอัดแล้วที่ต้นทางด้วย เช่นเดียวกับที่ตัวแยก Pro ทำ
• ตัวทำนายแบบตายตัว (10-14) และ Optimum (15) ใช้เส้นทางโค้ดเดียวกัน; แท็กรายแถวขับเคลื่อนการสร้างใหม่ในทั้งสองกรณี
• รายละเอียดกลไกภายในอยู่ในเอกสารภายในของที่เก็บซอร์สและอยู่นอกขอบเขตของคู่มือนี้

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

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

ดูเพิ่มเติม

• Filter (ความสามารถ) — การติดตั้ง เริ่มต้นอย่างรวดเร็ว และตัวอย่างการใช้งานระดับโปรดักชัน
• Diff — การอ้างอิงเชิงลึก — ผู้ใช้ตัวย้อนฟิลเตอร์
• Classifier — การอ้างอิงเชิงลึก — ผู้ใช้ตัวย้อนฟิลเตอร์