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

ภาพรวมโดยสรุป

หน้านี้คือเอกสารอ้างอิงเชิงลึกสำหรับ namespace NextPDF\Enterprise\Common โดย namespace นี้จัดส่งสัญลักษณ์สาธารณะหนึ่งรายการคือ value object BoundingBox ซึ่งเป็นสี่เหลี่ยมผืนผ้าที่ทำให้เป็นค่าปกติและไม่เปลี่ยนแปลงได้สำหรับการกำหนดตำแหน่งเชิงพื้นที่บนหน้าโดยไม่ขึ้นกับความละเอียด พื้นผิว Enterprise Intelligence และ Privacy ใช้งานมันสำหรับเรขาคณิตของเซลล์ตาราง ตำแหน่งของเอนทิตี และโซนการปิดบัง โมดูลนี้ไม่ทำ I/O ไม่ถือเนื้อหาเอกสาร และไม่แตะต้องการเข้ารหัสลับ สำหรับคำแนะนำด้านเวิร์กโฟลว์ ให้อ่านหน้าความสามารถ Commonก่อน

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

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

ตัว primitive เองไม่ทำการจำกัดสิทธิ์ตามใบอนุญาต การจำกัดสิทธิ์เกิดขึ้นบนพื้นผิว Enterprise ที่ใช้งานมัน ไม่มีรายการเทียบเท่าในระดับ Core หรือ Pro ของคลาสนี้ มันจัดส่งในแพ็กเกจ nextpdf/enterprise เท่านั้นและไม่ทำซ้ำหรือแทนที่ชนิดเรขาคณิตของ Core

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

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ยกข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
BoundingBox::__construct	float $x, float $y, float $width, float $height	ตรวจสอบแต่ละค่ากับ [0.0, 1.0] จากนั้นตรวจสอบผลรวมของขอบทั้งสอง	BoundingBox	InvalidArgumentException เมื่อค่าอยู่นอกช่วงหรือผลรวมของขอบเกิน 1.0 + 1e-9	ค่าทั้งสี่กลายเป็นคุณสมบัติ public readonly
BoundingBox::area	ไม่มี	คูณ width ด้วย height	float	ไม่มีการประกาศ	คืนค่า 0.0 สำหรับกล่องแบบ degenerate
BoundingBox::contains	self $other	ทดสอบว่า $other อยู่ภายในกล่องนี้ทั้งหมดหรือไม่	bool	ไม่มีการประกาศ	ขอบขวาและขอบล่างยอมรับความคลาดเคลื่อน +1e-9 ส่วนขอบซ้ายและขอบบนเปรียบเทียบแบบตรงตัว
BoundingBox::overlaps	self $other	ทดสอบการตัดกันของสี่เหลี่ยมอย่างเคร่งครัด	bool	ไม่มีการประกาศ	ตัวถูกดำเนินการที่มีพื้นที่เป็นศูนย์ฝั่งใดฝั่งหนึ่งจะคืนค่า false

ลายเซ็นจุดเข้าใช้งาน

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

สัญญาพฤติกรรม

โมเดลพิกัด

• ค่าทั้งสี่เป็นเศษส่วนของมิติหน้า ทำให้เป็นค่าปกติในช่วง [0.0, 1.0]
• x ระบุตำแหน่งขอบซ้ายและ y ระบุตำแหน่งขอบบนของกล่อง x + width และ y + height กำหนดขอบเขตขอบขวาและขอบล่าง
• การทำให้เป็นค่าปกติทำให้ทุกการดำเนินการไม่ขึ้นกับความละเอียด กล่องเดียวกันอ้างอิงพื้นที่หน้าเดียวกันที่ขนาดการเรนเดอร์หรือ DPI ใด ๆ

การสร้าง

• ตัวสร้างเป็นจุดตรวจสอบเพียงจุดเดียว พิกัดที่อยู่นอก [0.0, 1.0] จะยก InvalidArgumentException โดยข้อความจะระบุองค์ประกอบที่ผิดพลาดและค่าที่ได้รับ
• ผลรวมของขอบที่เกิน 1.0 + 1e-9 จะยก InvalidArgumentException โดยข้อความจะรายงานตัวถูกดำเนินการทั้งสองและผลรวมของมัน ความคลาดเคลื่อน 1e-9 รองรับการปัดเศษทศนิยมลอยตัวจากการคำนวณการทำให้เป็นค่าปกติต้นทาง
• อินสแตนซ์ที่สร้างแล้วไม่สามารถเปลี่ยนแปลงได้ คลาสเป็น final readonly ดังนั้นการเขียนคุณสมบัติจะล้มเหลวด้วย PHP Error และไม่สามารถสืบทอดคลาสได้

เพรดิเคต

• area() คืนค่า width * height เป็นการคำนวณบริสุทธิ์ที่ไม่มีผลข้างเคียง
• contains() คืนค่า true เมื่อกล่องอีกกล่องอยู่ภายในกล่องนี้ทั้งหมด การเปรียบเทียบขอบขวาและขอบล่างมีความคลาดเคลื่อน +1e-9 ส่วนการเปรียบเทียบขอบซ้ายและขอบบนเป็นแบบตรงตัว ทุกกล่องบรรจุตัวมันเอง และกล่องที่มีพื้นที่เป็นศูนย์สามารถถูกบรรจุได้
• overlaps() คืนค่า true เมื่อสี่เหลี่ยมตัดกันอย่างเคร่งครัด การเปรียบเทียบขอบทั้งสี่เป็นแบบเคร่งครัดโดยไม่มีความคลาดเคลื่อน หากตัวถูกดำเนินการฝั่งใดฝั่งหนึ่งมีพื้นที่เป็นศูนย์ ผลลัพธ์คือ false
• ดังนั้นการบรรจุจึงไม่ได้หมายความถึงการซ้อนทับ กล่องแบบ degenerate ที่อยู่ภายในกล่องอื่นถูกบรรจุแต่ไม่มีวันซ้อนทับ
• ไม่มีเมธอดใดทำ I/O การคงข้อมูล การเข้าถึงเครือข่าย หรือการบันทึกล็อก และไม่มีเมธอดใดถือเนื้อหาเอกสารหรือข้อมูลส่วนบุคคล ไม่มีทรัพยากรที่ผู้ปฏิบัติการเป็นเจ้าของสำหรับพื้นผิวนี้

ผู้บริโภค

โมดูล Enterprise ใช้ primitive นี้ร่วมกันแทนการนิยามเรขาคณิตแยกตามแต่ละโมดูล ใน Intelligence เอาต์พุตของ TableExtractor นำมันไปกับค่า TableCell และ KeyValuePair ใน Privacy PiiEntity RedactionFinding และ ZoneRedaction ใช้มันระบุตำแหน่งเนื้อหา และ RedactionEngine ใช้งานตำแหน่งเหล่านั้น สัญญาของพื้นผิวเหล่านั้นมีบันทึกไว้ในหน้าอ้างอิงของตนเอง

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

• องค์ประกอบที่อยู่นอกช่วง ค่าใดค่าหนึ่งในสี่ค่าที่ต่ำกว่า 0.0 หรือสูงกว่า 1.0 จะยก InvalidArgumentException ในขณะสร้าง INF และ -INF ถูกปฏิเสธด้วยตัวป้องกันเดียวกัน
• ผลรวมของขอบล้น x + width หรือ y + height ที่เกิน 1.0 + 1e-9 จะยก InvalidArgumentException ผลรวมที่อยู่ภายในความคลาดเคลื่อน 1e-9 จะสร้างสำเร็จ
• อินพุต NAN ตัวป้องกันช่วงใช้การเปรียบเทียบแบบมีลำดับ และการเปรียบเทียบแบบมีลำดับทุกครั้งกับ NAN เป็นเท็จ ดังนั้นองค์ประกอบ NAN จึงไม่ถูกปฏิเสธ อินสแตนซ์เช่นนั้นจะรายงานพื้นที่เป็น NAN และคืนค่า false จากเพรดิเคตทั้งสอง จงล้างแหล่งข้อมูลทศนิยมลอยตัวต้นทางก่อนการสร้าง
• กล่องที่มีพื้นที่เป็นศูนย์ กล่องที่มีความกว้างหรือความสูงเป็นศูนย์จะไม่มีวันซ้อนทับกับสิ่งใด รวมถึงตัวมันเอง แต่ยังคงถูกบรรจุโดยกล่องที่ไม่ใช่ degenerate ได้ จงคำนึงถึงความไม่สมมาตรนี้ในตรรกะการตัดกัน
• กล่องที่ขอบสัมผัสกัน กล่องสองกล่องที่ใช้เพียงขอบหรือมุมร่วมกันจะไม่ซ้อนทับ การทดสอบการตัดกันเป็นแบบเคร่งครัด
• ความไม่สมมาตรของความคลาดเคลื่อนในการบรรจุ กล่องด้านในที่ขอบซ้ายหรือขอบบนอยู่นอกกล่องด้านนอกไม่ว่าจำนวนเท่าใดจะไม่ผ่านการบรรจุ มีเพียงขอบขวาและขอบล่างเท่านั้นที่ได้รับส่วนเผื่อ 1e-9
• โหมด FIPS โมดูลนี้ไม่ทำการดำเนินการเชิงการเข้ารหัสลับ โหมด FIPS ไม่เปลี่ยนแปลงพฤติกรรมของมัน

ความสอดคล้อง

โมดูลนี้ไม่ได้นำมาตรฐานเชิงบรรทัดฐานใดมาใช้และไม่กล่าวอ้างความสอดคล้องใด ๆ เป็น geometry primitive ที่ผ่านการตรวจสอบความถูกต้องแล้ว ความหมายเชิงปริภูมิพิกัด PDF สำหรับคุณลักษณะที่ใช้งานมันมีบันทึกไว้ในหน้าของคุณลักษณะเหล่านั้น NextPDF ไม่ถือการรับรองใด ๆ และไม่มอบการรับรองใด ๆ การสนับสนุนไม่ใช่ความสอดคล้อง และความสอดคล้องไม่ใช่การรับรอง ไม่มีข้อจำกัดด้านการควบคุมการส่งออกที่นำมาใช้กับพื้นผิวนี้ และเอกสารอ้างอิงนี้ไม่ใช่ความเห็นทางกฎหมาย

หมายเหตุการพัฒนา

• คลาสนี้มีให้ใช้งานตั้งแต่ nextpdf/enterprise 2.2.0 พื้นผิวสาธารณะของมันไม่เปลี่ยนแปลงใน 3.1.0
• แปลงพิกัดปริภูมิหน้าแบบสัมบูรณ์เป็นเศษส่วนสัมพัทธ์กับหน้าก่อนการสร้าง คลาสนี้ตรวจสอบช่วง ไม่ใช่ความหมาย มันไม่สามารถตรวจจับพื้นที่ที่ดูสมเหตุสมผลแต่ผิดได้
• อินสแตนซ์เป็น value object ธรรมดาและสร้างได้ด้วยต้นทุนต่ำ อย่านำมารวมกลุ่มหรือแคช
• อินสแตนซ์สองตัวที่มีพิกัดเหมือนกันจะเทียบว่าเท่ากันภายใต้ความเท่ากันแบบหลวม (==) ส่วนเอกลักษณ์แบบเคร่งครัด (===) จะแยกแยะพวกมัน ในการทดสอบควรใช้การเปรียบเทียบพิกัด
• สำหรับเรขาคณิตนอกเหนือจากเพรดิเคตบูลีน ให้อนุมานขอบจากคุณสมบัติสาธารณะ ขอบขวา x + width ขอบล่าง y + height
• เมื่อทดสอบขอบเขตความคลาดเคลื่อน ให้ตรวจสอบทั้งสองฝั่งของ 1e-9 บนตัวป้องกันผลรวมของขอบและบนการเปรียบเทียบขอบขวา/ล่างของการบรรจุ

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

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

ดูเพิ่มเติม

• หน้าความสามารถ Common
• Intelligence — เอกสารอ้างอิงเชิงลึก
• Privacy — เอกสารอ้างอิงเชิงลึก
• Validation — เอกสารอ้างอิงเชิงลึก
• Evidence — เอกสารอ้างอิงเชิงลึก