Geo

لمحة سريعة

يُسقِط ⁨NextPDF Pro⁩ إحداثيات صفحة ⁨PDF⁩ على إحداثيات جغرافية ويُولِّد قاموس قياس ⁨PDF⁩ بنوع فرعي ⁨GEO⁩، بحيث يمكن لعارض أن يُبلِّغ عن الموضع في العالم الحقيقي انطلاقًا من نقطة على الصفحة.

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

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

لا يملك ⁨Geo⁩ علم ترخيص منفصلًا لكل ميزة؛ إذ يُفعِّله غلاف طبقة ⁨Pro⁩ مباشرةً.

التثبيت

composer require nextpdf/pro:^3

نظرة مفاهيمية عامة

يحمل ملف ⁨PDF⁩ الجغرافي المكاني قاموس قياس، موصوفًا في ⁨ISO 32000-2⁩ §⁨12.8.2⁩، يربط نقاط فضاء الجهاز بنظام مرجعي للإحداثيات الجغرافية. يبني ⁨NextPDF Pro⁩ تلك البيانات من كائنات قيمة غير قابلة للتغيير:

• GeoCoordinate — ثلاثية خط عرض/خط طول/ارتفاع. يتحقّق الإنشاء من خط العرض ضمن [-90, 90] وخط الطول ضمن [-180, 180]، ويوفّر تنسيقًا بصيغة درجات-دقائق-ثوانٍ وبسلسلة عشرية.
• GeoControlPoint — اقتران نقطة فضاء ⁨PDF⁩ بـ GeoCoordinate.
• ProjectionType — تعداد للإسقاطات الشائعة (جغرافي، ⁨UTM⁩، ميركاتور مستعرض، لامبرت المخروطي المطابق)، كل منها مُسقَط على رمز ⁨EPSG⁩.
• GeoRegistration — نقاط التحكّم إضافةً إلى الإسقاط والمسند الجيوديسي (الافتراضي WGS84). يتطلّب isValid() نقطتَي تحكّم على الأقل لتحويل أفيني أدنى؛ ويُصدِر toPdfMeasureDictionary() قاموس /Measure بـ /Subtype /GEO ومصفوفات نقاط التحكّم.

لماذا يعمل بهذه الطريقة

يبني ⁨NextPDF⁩ قاموس القياس من كائنات قيمة مُتحقَّق منها وغير قابلة للتغيير، لا من قاموس خام يُمرِّره المُستدعي. يرفض GeoCoordinate خط عرض أو طول خارج النطاق عند الإنشاء. ويرفض GeoRegistration::isValid() أقل من نقطتَي تحكّم، فيفشل التسجيل المُشوَّه سريعًا بدلًا من إصدار قاموس /GEO متدهور. تُحَل الإسقاطات إلى رموز ⁨EPSG⁩ قياسية عبر ProjectionType، ما يُبقي نظام الإحداثيات المرجعي صريحًا لا مُخمَّنًا. يعود المسند افتراضيًا إلى WGS84 لكنه يبقى حقلًا مُسمّى، فيكون اختيار نظام مرجعي غير افتراضي قرارًا مقصودًا. تهمّ هذه الوضعية المُغلَقة عند الفشل لأن مرجعًا جغرافيًا خاطئًا أسوأ من غيابه؛ إذ سيُبلِّغ العارض بثقة عن موضع زائف في العالم الحقيقي. خلفية التصميم: ‏واجهة برمجية ترفض التخمين.

سطح الـ ⁨API⁩

الصنف	المسؤولية
GeoCoordinate	خط عرض/طول/ارتفاع مُتحقَّق منه مع التنسيق.
GeoControlPoint	اقتران نقطة ⁨PDF⁩ ↔ نقطة جغرافية.
ProjectionType	تعداد الإسقاط برموز ⁨EPSG⁩.
GeoRegistration	بناء قاموس /Measure /GEO.

مثال شيفرة — بداية سريعة

use NextPDF\Pro\Geo\{GeoRegistration, GeoControlPoint, GeoCoordinate, ProjectionType};

$reg = new GeoRegistration(
    controlPoints: [
        new GeoControlPoint(0.0, 0.0, new GeoCoordinate(40.0, -74.0, 0.0)),
        new GeoControlPoint(600.0, 800.0, new GeoCoordinate(41.0, -73.0, 0.0)),
    ],
    projection: ProjectionType::Geographic,
);
$dict = $reg->toPdfMeasureDictionary();

مثال شيفرة — إنتاج

if (! $reg->isValid()) {
    throw new RuntimeException('Geo registration needs at least two control points.');
}
$logger->info('geo.registered', [
    'projection' => $reg->projection->value,
    'datum'      => $reg->datum,
]);

الحالات الحدّية والمزالق

• يرفض إنشاء GeoCoordinate خط عرض أو طول خارج النطاق.
• أقل من نقطتَي تحكّم يُنتج تسجيلًا غير صالح.
• المسند الافتراضي هو WGS84؛ اضبطه صراحةً لأنظمة مرجعية أخرى.

الأداء

توليد القاموس خطّي بعدد نقاط التحكّم.

ملاحظات أمنية

مُدخَل ⁨Geo⁩ بيانات إحداثيات عددية. تحقّق من نقاط التحكّم المُستمَدّة من مُدخَل غير موثوق قبل التسجيل.

المطابقة

السلوك	المرجع	الحالة
قاموس القياس الجغرافي المكاني (النوع الفرعي ⁨GEO⁩)	ISO 32000-2 §12.8.2	مُتوائم (مُعاد صياغته)

عقد السلوك

• يتحقّق GeoCoordinate من خط العرض ضمن [-90, 90] وخط الطول ضمن [-180, 180] عند الإنشاء ويوفّر تنسيقًا بصيغة درجات-دقائق-ثوانٍ وبسلسلة عشرية.
• يقرن GeoControlPoint نقطة فضاء ⁨PDF⁩ بـ GeoCoordinate.
• يحمل GeoRegistration نقاط التحكّم إضافةً إلى ProjectionType (مُسقَط على رمز ⁨EPSG⁩) ومسندًا جيوديسيًا افتراضيًا WGS84. يتطلّب isValid() نقطتَي تحكّم على الأقل؛ ويُصدِر toPdfMeasureDictionary() قاموس /Measure بـ /Subtype /GEO ومصفوفات نقاط التحكّم.
• الإحداثيات خارج النطاق أو أقل من نقطتَي تحكّم تُنتج تسجيلًا غير صالح بدلًا من مخرَج متدهور بصمت.

ملاحظة حدود ⁨Enterprise⁩

لا يغيّر ⁨Enterprise⁩ سلوك ⁨Geo⁩. يضيف ⁨Enterprise⁩ ميزات من طبقة أعلى موثَّقة بشكل منفصل؛ وهي ليست مطلوبة لتوليد قاموس قياس ⁨GeoPDF⁩.

احتياط ⁨Core⁩ / بديله

لا يوجد مكافئ في ⁨Core⁩ لتوليد قاموس قياس ⁨GeoPDF⁩. هذه إضافة في ⁨Pro⁩.

حدود النشر

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

انظر أيضًا

• ⁨Geo⁩ — مرجع متعمّق — مرجع كامل للأصناف والدوال.
• ⁨Document⁩ — تجميع الصفحة والمستند.
• التعليقات التوضيحية في ⁨Core⁩.