⁨Geo⁩ — مرجع متعمّق

نظرة سريعة

هذه الصفحة هي المرجع على مستوى العقد لوحدة ⁨NextPDF Pro Geo⁩. السطح هو أربعة كائنات قيمة غير قابلة للتغيير — GeoCoordinate وGeoControlPoint وProjectionType وGeoRegistration — إضافةً إلى GeoPdfLayer الذي يربط التسجيلات بفهارس الصفحات ويُصدر مُخرَج إطار العرض. تُنتِج الوحدة نصّ قاموس ⁨PDF⁩: قاموس /Measure مع /Subtype /GEO، وقاموس /Viewport، وقيمة مصفوفة /VP على مستوى الصفحة. التوليد تجميع سلاسل حتمي: لا استدعاء شبكي، ولا وصول إلى نظام الملفات، ولا عشوائية. تبيّن هذه الصفحة واجهة ⁨API⁩ العامة، وعقد السلوك القابل للملاحظة، وأنماط الفشل.

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

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

لا توجد راية ترخيص خاصّة بالميزة تبوّب هذه الوحدة. أصناف ⁨Geo⁩ متاحة كلّما كان nextpdf/pro مثبّتًا.

سطح واجهة ⁨API⁩ العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
GeoCoordinate	الدالة البانية: float $latitude، float $longitude، float $altitude = 0.0	يتحقّق من أنّ خط العرض ضمن [-90, 90] وخط الطول ضمن [-180, 180]	—	InvalidArgumentException عندما تكون أيٌّ من القيمتين خارج النطاق	final readonly؛ الارتفاع بالأمتار فوق مستوى سطح البحر ولا يخضع للتحقّق من النطاق
GeoCoordinate::toDms()	لا شيء	يُنسّق بصيغة درجات-دقائق-ثوانٍ مع اللواحق N/S وE/W	string	—	الثواني القريبة من الصفر تُعرض كـ 00؛ وإلّا فبمنزلتين عشريتين مع إزالة الأصفار اللاحقة
GeoCoordinate::toDecimal()	لا شيء	يُنسّق خط العرض وخط الطول إلى ست منازل عشرية، مفصولة بفاصلة	string	—	لا يُدرَج الارتفاع
GeoCoordinate::fromDms()	string $dms	يحلّل سلسلة ⁨DMS⁩؛ الثواني اختيارية؛ وتُطبَّع رموز الدرجة وعلامات الاقتباس المطبعية	self	InvalidArgumentException عندما لا تُحلَّل السلسلة، أو عندما تفشل القيم المُحلَّلة في تجاوز فحوص النطاق للدالة البانية	مصنع ساكن؛ أحرف نصف الكرة غير حسّاسة لحالة الأحرف؛ والارتفاع افتراضيًا 0.0
GeoControlPoint	الدالة البانية: float $pdfX، float $pdfY، GeoCoordinate $geo	يقرن نقطةً في فضاء مستخدم ⁨PDF⁩ (بالنقاط) بإحداثية جغرافية	—	—	final readonly؛ لا يُتحقَّق من إحداثيات ⁨PDF⁩
ProjectionType	تعداد مدعوم بسلسلة، 4 حالات	الحالات: Geographic، UTM، TransverseMercator، LambertConformal	القيم الداعمة GEO، UTM، TM، LCC	—	انظر جدول ربط الإسقاط أدناه
ProjectionType::epsgCode()	لا شيء	يربط الحالة برمز ⁨EPSG⁩ ثابت واحد	int	—	4326، 32601، 2154، أو 3347
ProjectionType::label()	لا شيء	اسم إسقاط قابل للقراءة البشرية	string	—	على سبيل المثال WGS 84 Geographic
GeoRegistration	الدالة البانية: array $controlPoints، ProjectionType $projection، string $datum = 'WGS84'	يحمل نقاط التحكّم والإسقاط والمرجع الجيوديسي	—	—	final readonly؛ لا يُتحقَّق من عدد نقاط التحكّم عند الإنشاء
GeoRegistration::isValid()	لا شيء	يتطلّب نقطتَي تحكّم على الأقل	bool	—	نقطتان هما الحدّ الأدنى للربط التآلفي
GeoRegistration::toPdfMeasureDictionary()	لا شيء	يُصدر قاموس /Measure مع /Subtype /GEO و/GCS و/GPTS و/LPTS و/Bounds	string	—	لا يفحص isValid()؛ احمِ الاستدعاء أو مرّره عبر GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex، GeoRegistration $registration	يُلحق تسجيلًا لفهرس صفحة يبدأ من الصفر	self	InvalidArgumentException عندما يكون $pageIndex سالبًا	انسيابي؛ أوّل تسجيل يُضاف لصفحةٍ يفوز وقت التوليد
GeoPdfLayer::getRegistrations()	لا شيء	يُعيد جميع التسجيلات بترتيب الإدراج	list<array{pageIndex: int, registration: GeoRegistration}>	—	يشمل التكرارات والتسجيلات غير الصالحة كما أُضيفت
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	يُصدر قاموس /Viewport مع /BBox و/Name و/Measure مضمّن	string	—	سلسلة فارغة عندما لا يوجد للصفحة تسجيل أو يكون التسجيل غير صالح
GeoPdfLayer::generateViewportArray()	int $pageIndex	يلفّ قاموس إطار العرض بأقواس بوصفه قيمة مصفوفة /VP الحرفية	string	—	سلسلة فارغة عند الغياب؛ عندئذٍ يحذف المستدعون /VP لتلك الصفحة
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer، int $pageIndex	يكتب /VP إضافةً إلى المصفوفة الحرفية وسطرًا جديدًا على المخزن المؤقّت	bool	—	true عند كتابة إدخال؛ وإلّا فلا عملية وfalse

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

public function __construct(
    public float $latitude,
    public float $longitude,
    public float $altitude = 0.0,
)

public function toDms(): string

public function toDecimal(): string

public static function fromDms(string $dms): self

public function __construct(
    public float $pdfX,
    public float $pdfY,
    public GeoCoordinate $geo,
)

public function __construct(
    public array $controlPoints,
    public ProjectionType $projection,
    public string $datum = 'WGS84',
)

public function isValid(): bool

public function toPdfMeasureDictionary(): string

public function addRegistration(int $pageIndex, GeoRegistration $registration): self

public function getRegistrations(): array

public function generateViewportDictionary(int $pageIndex): string

public function generateViewportArray(int $pageIndex): string

public function writeToPdfWriter(BinaryBuffer $buffer, int $pageIndex): bool

عقد السلوك

التحقّق من الإحداثيات وتنسيقها

يتحقّق GeoCoordinate عند الإنشاء ولا يتغيّر أبدًا. يرمي خط العرض خارج [-90, 90] أو خط الطول خارج [-180, 180] استثناء InvalidArgumentException مع تسمية القيمة المخالفة. يعرض toDms() كلا المحورين بصيغة درجات ودقائق مبطّنة بالأصفار وثوانٍ ولاحقة نصف الكرة. يعرض toDecimal() القيمة latitude, longitude بست منازل عشرية. يقبل fromDms() مدخل ⁨DMS⁩ بثوانٍ اختيارية، ويطبّع رموز الشرطة العلوية والشرطة العلوية المزدوجة وعلامة الدرجة وعلامات الاقتباس الذكية، ويحوّلها إلى درجات عشرية موقّعة، وينشئ نسخة جديدة. تصبح خطوط العرض الجنوبية وخطوط الطول الغربية قيمًا سالبة.

ربط الإسقاط

تحمل كل حالة ProjectionType رمز ⁨EPSG⁩ ثابتًا واحدًا وتسمية واحدة. الربط جدول مغلق، وليس سجلّ نظام مرجعي للإحداثيات.

الحالة	القيمة الداعمة	epsgCode()	label()
Geographic	GEO	4326	WGS 84 Geographic
UTM	UTM	32601	Universal Transverse Mercator
TransverseMercator	TM	2154	Transverse Mercator
LambertConformal	LCC	3347	Lambert Conformal Conic

تُصدر الحالة UTM رمز المنطقة 1. أمّا المشاريع التي تحتاج منطقة ⁨UTM⁩ مختلفة، أو أي رمز ⁨EPSG⁩ خارج هذا الجدول، فينبغي أن تحمل وصف نظام الإحداثيات المرجعي (⁨CRS⁩) الموثوق في سلسلة datum بصيغة ⁨Well Known Text⁩.

إصدار قاموس ⁨Measure⁩

يُصدر GeoRegistration::toPdfMeasureDictionary() قاموسًا متعدّد الأسطر: /Type /Measure و/Subtype /GEO وقاموس نظام إحداثيات /GCS و/GPTS و/LPTS و/Bounds، وفق ⁨ISO 32000-2:2020 §12.10⁩ (الجدول 269). السلوك الملموس:

• يُصدر /GCS بالصيغة << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. يأتي رمز ⁨EPSG⁩ من حالة الإسقاط. وقيمة /WKT هي سلسلة datum كما وردت تمامًا؛ والقيمة الافتراضية هي WGS84.
• يسرد /GPTS أزواج خط العرض وخط الطول بست منازل عشرية، بترتيب نقاط التحكّم.
• يسرد /LPTS أزواج pdfX/pdfY بست منازل عشرية، كما وردت تمامًا. يُعرّف ⁨ISO 32000-2:2020⁩ الجدول 269 نقاط LPTS ضمن مربّع وحدة ثنائي الأبعاد؛ وتوفير قيم مطبّعة على مربّع الوحدة هو مسؤولية المستدعي.
• القيمة /Bounds ثابتة عند [0 0 0 1 1 1 1 0]، وهي مربّع الوحدة الكامل.
• تُهرَّب سلسلة datum قبل إدراجها في السلسلة الحرفية: تتحوّل الشرطة المائلة العكسية والأقواس وأحرف التحكّم الشائعة إلى تهريباتها بالشرطة المائلة العكسية وفق ⁨ISO 32000-2:2020 §7.3.4.2⁩. ولا يمكن لسلسلة ⁨datum⁩ متأثّرة بالمستدعي أن تُنهي السلسلة الحرفية أو تحقن رموز ⁨PDF⁩ خام.

إصدار إطار العرض والصفحة

يحفظ GeoPdfLayer التسجيلات بترتيب الإدراج، مُفهرسةً بفهرس صفحة يبدأ من الصفر. يحلّ generateViewportDictionary() أوّل تسجيل للصفحة المطلوبة ويُعيد سلسلة فارغة عند عدم وجود أي تسجيل أو عندما يكون isValid() غير صحيح. يحمل القاموس المُنتَج /Type /Viewport، و/BBox محسوبًا من الحدّ الأدنى والأقصى لإحداثيات ⁨PDF⁩ لنقاط التحكّم، و/Name بالصيغة GeoViewport_Page<n>، وقاموس /Measure المضمّن. يتبع إدخال /Measure لإطار العرض ⁨ISO 32000-2:2020 §12.9⁩. يلفّ generateViewportArray() القاموس بأقواس، مُنتِجًا قيمة /VP للصفحة: مصفوفة من قواميس إطار العرض وفق ⁨ISO 32000-2:2020 §7.7.3.3⁩ (الجدول 31). يكتب writeToPdfWriter() القيمة /VP إضافةً إلى المصفوفة الحرفية على BinaryBuffer من ⁨Core⁩ ويُبلّغ عمّا إذا كُتب شيء، بحيث يمكن لتسلسل الصفحة حذف المفتاح بنظافة.

الحالات الحدّية وأنماط الفشل

• يرمي خط العرض أو خط الطول خارج النطاق استثناء InvalidArgumentException عند الإنشاء؛ ولا وجود لإحداثية صالحة جزئيًا.
• يرمي fromDms() عند تعذّر تحليل المدخل. وتمرّ القيم المُحلَّلة عبر الدالة البانية، لذا فإنّ سلسلة صحيحة نحويًا بقيم خارج النطاق ترمي أيضًا.
• لا تحمل صيغة ⁨DMS⁩ ارتفاعًا؛ ويُنتِج fromDms() دائمًا الارتفاع 0.0.
• يُبلّغ GeoRegistration بأقلّ من نقطتَي تحكّم عن isValid() غير صحيح، ومع ذلك يظلّ toPdfMeasureDictionary() يُصدر قاموسًا بمصفوفات نقاط قصيرة. احمِ الاستدعاءات المباشرة بـ isValid()، أو مرّر الإصدار عبر GeoPdfLayer الذي يكبت التسجيلات غير الصالحة.
• يحتفظ getRegistrations() بجميع التسجيلات المكرّرة لفهرس صفحة واحد؛ ويستخدم توليد إطار العرض أوّل تسجيل مُضاف.
• يرمي فهرس صفحة سالب استثناء InvalidArgumentException؛ وفهارس الصفحات تبدأ من الصفر.
• نقاط التحكّم التي تتشارك قيمة ⁨X⁩ أو ⁨Y⁩ تُنتِج /BBox منحلًّا بعرض صفري أو ارتفاع صفري. وفّر نقاطًا تمتدّ على كلا المحورين.
• كل المُخرَجات نصّ مُولَّد. ولا يُكتب شيء إلى القرص أو الشبكة، والمدخل المتطابق يُنتِج مخرجًا متطابقًا.
• لا تحدث أي عملية تشفيرية في هذه الوحدة، لذا لا يوجد سلوك خاصّ بوضع ⁨FIPS⁩.

المطابقة

الادّعاء	المعيار	البند
يُصدر قاموس القياس بالنوع الفرعي GEO، مع أزواج خط العرض وخط الطول GPTS وقيم LPTS المقترنة.	ISO 32000-2:2020	§12.10
يحمل قاموس إطار العرض إدخالات BBox وName وMeasure.	ISO 32000-2:2020	§12.9
تُصدر قيمة VP للصفحة بوصفها مصفوفة من قواميس إطار العرض.	ISO 32000-2:2020	§7.7.3.3
يهرّب إدراج المرجع (datum) الأحرفَ الوصفية للسلسلة الحرفية.	ISO 32000-2:2020	§7.3.4.2

جميع البنود مُعاد صياغتها؛ ولا يُعيد ⁨NextPDF⁩ إنتاج النصّ المعياري. هذه بيانات قدرات، وليست شهادات. لا يحمل ⁨NextPDF⁩ أي شهادة ولا يمنح أيًّا منها. رموز ⁨EPSG⁩ قيم تمثيلية ثابتة لكل حالة إسقاط، ويحمل إدخال /WKT سلسلة ⁨datum⁩ المُوفَّرة بدلًا من وصف ⁨Well Known Text⁩ مُولَّد؛ وكلا البيانين مبنيّ على المنتج. تحقّق من مُخرَجات ⁨GeoPDF⁩ المُصدَرة في معالِجات ⁨PDF⁩ التفاعلية المستهدفة قبل الاعتماد على القياس من جهة العارض.

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

• متاح منذ nextpdf/pro ⁨1.9.0⁩؛ والحالي في nextpdf/pro 3.1.0.
• تحقّق من isValid() قبل استدعاء toPdfMeasureDictionary() مباشرةً؛ ويُجري GeoPdfLayer هذا الفحص نيابةً عنك.
• عندما يحلّل المستهلكون النهائيون /WKT، مرّر وصف ⁨Well Known Text⁩ كاملًا بوصفه datum؛ فالقيمة الافتراضية WGS84 تسمية مرجع فقط.
• طبّع مدخلات LPTS على مربّع الوحدة قبل إنشاء نقاط التحكّم عندما تختلف حدود إطار العرض عن قيم فضاء ⁨PDF⁩ لديك.
• كلفة الإصدار خطّية بعدد نقاط التحكّم؛ والبحث في GeoPdfLayer خطّي بعدد التسجيلات.
• يتكامل writeToPdfWriter() مع تسلسل الصفحة عبر NextPDF\Support\BinaryBuffer من ⁨Core⁩.

حدود النشر

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

اطّلع أيضًا

• ⁨Geo⁩ (القدرة) — التثبيت، ونظرة مفاهيمية عامة، وعيّنات بدء سريع.
• ⁨Document⁩ — المرجع المتعمّق — سطح تركيب المستند والصفحة.