استخدام علامات الارتساء الجغرافي المكاني لتحديد موضع المحتوى الحقيقي على Android NDK

تُعد المراسي الجيوفضائية نوعًا من الإعلانات الثابتة التي تتيح لك وضع محتوى ثلاثي الأبعاد على أرض الواقع.

أنواع المراسي الجيوفضائية

هناك ثلاثة أنواع من المراسي الجيوفضائية التي يتعامل كل منها مع الارتفاع بشكل مختلف:

1. علامات ارتساء WGS84:
   تتيح لك علامات الارتساء WGS84 وضع محتوى ثلاثي الأبعاد بأي خط عرض وخط طول وارتفاع محدّدين.

2. علامات ارتساء التضاريس:
   تتيح لك "علامات ارتساء التضاريس" وضع المحتوى باستخدام خطوط الطول والعرض فقط مع ارتفاع نسبة إلى التضاريس في هذا الموضع. يتم تحديد الارتفاع بالنسبة إلى الأرض أو الطابق كما هو معروف بواسطة VPS.

3. المراسي الثابتة على السطح:
   تتيح لك الإعلانات الثابتة على السطح وضع المحتوى باستخدام خطوط العرض والطول فقط مع ارتفاعه مقارنةً بسقف المبنى في هذا الموضع. يتم تحديد الارتفاع بالنسبة إلى الجزء العلوي من المبنى كما هو معروف من خلال هندسة التجوّل الافتراضي. وسيتم ضبط هذا افتراضيًا على ارتفاع التضاريس عند عدم وضعه في مبنى.

	WGS84	التضاريس	سطح
موضع أفقي	خط العرض، خط الطول	خط العرض، خط الطول	خط العرض، خط الطول
موضع رأسي	نسبةً إلى ارتفاع WGS84	نسبةً إلى مستوى التضاريس الذي تحدّده "خرائط Google"	نسبةً إلى مستوى السطح الذي تحدّده "خرائط Google"
هل يحتاج الخادم إلى أن يتم حله؟	لا	نعم	نعم

المتطلبات الأساسية

تأكد من تفعيل واجهة برمجة التطبيقات الجغرافية المكانية قبل المتابعة.

وضع المراسي الجيوفضائية

ويحتوي كل نوع من أنواع الإرساء على واجهات برمجة تطبيقات مخصّصة لإنشائها. يُرجى الاطّلاع على أنواع علامات الارتساء الجيوفضائية لمزيد من المعلومات.

إنشاء إعلان ثابت من اختبار النتائج

ويمكنك أيضًا إنشاء علامة ارتساء جيوفضائية من نتيجة اختبار نتيجة. استخدم الوضع من اختبار النتائج وحوِّله إلى ArGeospatialPose. ويمكنك استخدامها لوضع أي نوع من أنواع الارتساء الثلاثة الموضّحة.

احصل على وضعية جيوفضائية من وضع الواقع المعزّز

توفّر ArEarth_getGeospatialPose() طريقة إضافية لتحديد خط العرض وخط الطول من خلال تحويل وضع الواقع المعزّز إلى وضع جيوفضائي.

احصل على وضع الواقع المعزّز من وضعية جيوفضائية

تعمل ArEarth_getPose() على تحويل الموضع الأفقي والارتفاع والدوران الرباعي المحددَين لكوكب الأرض في ما يتعلق بإطار إحداثي من الشرق إلى الجنوب إلى وضع الواقع المعزّز بالنسبة إلى إحداثيات GL العالمية.

اختيار الطريقة التي تناسب حالة الاستخدام

كل طريقة لإنشاء مراسي لها نقاط مفاضلة مرتبطة يجب وضعها في الاعتبار:

• عند استخدام Streetscape Geometry، استخدم اختبار النتيجة لإرفاق المحتوى بالمبنى.
• أفضل مراسي تضاريس أو سطح سقف على مراسي WGS84 لأنها تستخدم قيم الارتفاع التي تحددها "خرائط Google".

تحديد خط العرض وخط الطول لموقع جغرافي

هناك ثلاث طرق يمكنك من خلالها حساب خط العرض وخط الطول للموقع:

• يمكنك استخدام أداة إنشاء الخرائط الجيوفضائية لعرض العالم وتعزيزه من خلال محتوى ثلاثي الأبعاد بدون الحاجة إلى الانتقال فعليًا إلى موقع جغرافي. ويتيح لك ذلك عرض محتوى ثلاثي الأبعاد بشكل مرئي باستخدام "خرائط Google" في Unity Editor. سيتم حساب خط العرض وخط الطول والتدوير والارتفاع للمحتوى تلقائيًا.
• استخدام "خرائط Google"
• استخدام Google Earth لاحظ أن الحصول على هذه الإحداثيات باستخدام Google Earth، على عكس خرائط Google، سيعطيك هامش خطأ يصل إلى عدة أمتار.
• الانتقال إلى الموقع الجغرافي

استخدام "خرائط Google"

للحصول على خط العرض وخط الطول لموقع باستخدام "خرائط Google"، يمكنك إجراء ما يلي:

1. انتقل إلى خرائط Google على كمبيوتر مكتبي.

   

2. انتقِل إلى الطبقات > المزيد.

   

   

3. يمكنك تغيير نوع الخريطة إلى القمر الصناعي ومحو مربع الاختيار عرض الكرة الأرضية في أسفل يمين الشاشة.

   

   سيؤدي ذلك إلى فرض منظور ثنائي الأبعاد وإزالة الأخطاء المحتملة التي قد تأتي من عرض ثلاثي الأبعاد بزاوية.

4. على الخريطة، انقر بزر الماوس الأيمن على الموقع الجغرافي واختَر خط الطول/خط العرض لنسخه إلى الحافظة.

استخدام Google Earth

يمكنك حساب خط العرض وخط الطول لموقع ما من Google Earth بالنقر على موقع في واجهة المستخدم وقراءة البيانات من تفاصيل العلامة الموضعية.

ملاحظة: سيؤدي الحصول على هذه الإحداثيات باستخدام Google Earth، على عكس استخدام "خرائط Google"، إلى الحصول على هامش خطأ يصل إلى عدة أمتار. ننصحك باستخدام "خرائط Google" وElevation API لمعرفة خط العرض وخط الطول لأحد المواقع الجغرافية.

للحصول على خط العرض وخط الطول لموقع باستخدام Google Earth:

1. انتقِل إلى Google Earth على جهاز كمبيوتر سطح المكتب.

2. انتقِل إلى قائمة الهامبرغر واختَر نمط الخريطة.

   

3. أوقِف مفتاح التبديل المباني الثلاثية الأبعاد.

   

4. بعد إيقاف مفتاح المباني ثلاثية الأبعاد، انقر على رمز الدبوس لإضافة علامة موضعية في الموقع الجغرافي المحدد.

5. حدّد مشروعًا يحتوي على علامتك الموضعية، ثمّ انقر على حفظ.

6. في حقل العنوان للعلامة الموضعية، أدخِل اسمًا للعلامة الموضعية.

7. انقر على سهم الرجوع في جزء المشروع واختر قائمة إجراءات أخرى.

8. اختر تصدير كملف KML من القائمة.

   

يسجّل ملف KLM خط العرض وخط الطول والارتفاع لعلامة موضعية في العلامة <coordinates> مفصولة بفواصل، على النحو التالي:

<coordinates>-122.0755182435043,37.41347299422944,7.420342565583832</coordinates>

لا تستخدِم خط العرض وخط الطول من العلامات <LookAt> التي تحدِّد موضع الكاميرا وليس موقعها الجغرافي.

الانتقال إلى الموقع الجغرافي

ويمكنك حساب ارتفاع الموقع عن طريق الذهاب إلى هناك فعليًا وإجراء ملاحظة محلية.

الحصول على دوران دوران التناوب

تستخلص ArGeospatialPose_getEastUpSouthQuaternion() الاتجاه من الوضع الجيوفضائي وتخرج شكل رباعي يمثّل مصفوفة دوران تحوِّل متجهًا من الهدف إلى نظام الإحداثيات من الشرق إلى الجنوب (EUS). تشير X+ إلى الشرق، بينما Y+ تشير إلى أعلى، وZ+ نقطة جنوبًا. تتم كتابة القيم بالترتيب {x, y, z, w}.

روابط WGS84

نقطة الارتساء WGS84 هي نوع من الإرساء الذي يسمح لك بوضع محتوى ثلاثي الأبعاد في أي خط عرض وخط طول وارتفاع محدد. حيث يعتمد على الوضعية، والتوجيه، لكي يتم وضعها في العالم الحقيقي. يتكون الموضع من خط عرض وخط طول وارتفاع محددين في نظام الإحداثيات WGS84. يتكون الاتجاه من تدوير رباعي.

يتم تسجيل الارتفاع بالأمتار فوق المقطع الناقص من المرجع WGS84 بحيث لا يكون مستوى سطح الأرض لا عند الصفر. تطبيقك مسؤول عن توفير هذه الإحداثيات لكل علامة ارتساء تم إنشاؤها.

وضع ارتساء WGS84 في العالم الحقيقي

تحديد ارتفاع موقع جغرافي

في ما يلي بعض الطرق لتحديد ارتفاع موقع ما لوضع المراسي:

• إذا كان موقع الإرساء قريبًا من المستخدم، يمكنك استخدام ارتفاع مشابه لارتفاع جهاز المستخدم.
• بعد حصولك على خط العرض وخط الطول، يمكنك استخدام Elegation API للحصول على الارتفاع بناءً على مواصفات EGM96. يجب تحويل ارتفاع EGM96 في Maps API إلى WGS84 للمقارنة مع الارتفاع في ArGeospatialPose. يمكنك الاطّلاع على GeoidEval الذي يحتوي على كل من سطر الأوامر وواجهة HTML. تعرض واجهة برمجة تطبيقات الخرائط معلومات خطوط الطول والعرض وفقًا لمواصفات WGS84 بشكل غير تقليدي.
• يمكنك الحصول على خط العرض وخط الطول والارتفاع للموقع الجغرافي من Google Earth. سيؤدي ذلك إلى ظهور هامش خطأ يصل إلى عدة أمتار. استخدِم خط العرض وخط الطول والارتفاع من علامات <coordinates>، وليس علامات <LookAt>، في ملف KML.
• إذا كانت هناك نقطة ارتساء حالية قريبة وإذا لم تكن في منحدر شديد، قد تتمكن من استخدام الارتفاع من ArGeospatialPose للكاميرا بدون استخدام مصدر آخر، مثل Maps API.

إنشاء إعلان ثابت

بعد تحديد خطوط الطول والعرض والارتفاع والدوران الربعي، استخدِم ArEarth_acquireNewAnchor() لإرساء المحتوى إلى الإحداثيات الجغرافية التي تحددها.

float eus_quaternion_4[4] = {qx, qy, qz, qw};
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArAnchor* earth_anchor = NULL;
    ArStatus status = ArEarth_acquireNewAnchor(ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude,
        eus_quaternion_4, &earth_anchor);

    // Attach content to the anchor specified by geodetic location and
    // pose.
  }
}

ملاحظة: لا يمكن إنشاء علامات ارتساء ضمن 0.1 درجة للقطب الشمالي أو القطب الجنوبي (90 درجة أو -90 درجة). في حال تحديد ارتساء هذا، يتعذّر إنشاء مراسي.

مثبتات التضاريس

علامة ارتساء التضاريس هي نوع من علامات الإرساء تتيح لك وضع كائنات الواقع المعزّز باستخدام خطوط الطول والعرض فقط، والاستفادة من المعلومات الواردة من VPS لمعرفة الارتفاع الدقيق فوق سطح الأرض.

بدلاً من إدخال الارتفاع المطلوب، يمكنك توفير الارتفاع فوق التضاريس. وعندما تكون القيمة صفرًا، ستكون المرساة في مستوى سطح الأرض.

ضبط وضع البحث عن طائرة

إنّ تحديد مستوى الوصول إلى المستوى اختياري وليس مطلوبًا لاستخدام علامات الارتساء. تجدر الإشارة إلى استخدام المستويات الأفقية فقط. ستساعد المستوىات الأفقية في المحاذاة الديناميكية لمرتكزات التضاريس على الأرض.

يمكنك استخدام ArPlaneFindingMode لاختيار كيفية رصد تطبيقك للطائرات.

إنشاء علامة ارتساء للتضاريس باستخدام واجهة برمجة التطبيقات الجديدة غير المتزامنة

لإنشاء علامة ارتساء للتضاريس ووضعها، اتصل بالرقم ArEarth_resolveAnchorOnTerrainAsync().

لن تكون علامة الارتساء جاهزة على الفور ويجب حلّها. وبعد حلّ المشكلة، ستكون متاحة في ArResolveAnchorOnTerrainFuture.

تحقَّق من حالة ارتساء التضاريس باستخدام ArResolveAnchorOnTerrainFuture_getResultTerrainAnchorState(). يمكنك الحصول على الإعلان الثابت الذي تم حلّه باستخدام ArResolveAnchorOnTerrainFuture_acquireResultAnchor().

float eus_quaternion_4[4] = {qx, qy, qz, qw};
void* context = NULL;
ArResolveAnchorOnTerrainCallback callback = NULL;
ArResolveAnchorOnTerrainFuture* future = NULL;
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArStatus status = ArEarth_resolveAnchorOnTerrainAsync(
        ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude_above_terrain, eus_quaternion_4,
        context, callback, &future);
  }
}

ملاحظة: لا يمكن إنشاء علامات ارتساء ضمن 0.1 درجة من القطب الشمالي أو الجنوبي (90 درجة أو -90 درجة). في حال تحديد مثل هذا الارتساء، سيعرض ArEarth_resolveAnchorOnTerrainAsync() خطأ AR_ERROR_INVALID_ARGUMENT وسيتعذّر إنشاء علامة الارتساء.

الاطّلاع على وضع المستقبل

سيكون للمستقبل ArFutureState مرتبط به.

الحالة	الوصف
AR_FUTURE_STATE_PENDING	لا تزال العملية في انتظار المراجعة.
AR_FUTURE_STATE_DONE	اكتملت العملية والنتيجة متاحة.
AR_FUTURE_STATE_CANCELLED	تم إلغاء العملية.

التحقق من حالة ارتساء التضاريس للنتيجة المستقبلية

تنتمي السمة ArTerrainAnchorState إلى العملية غير المتزامنة، كما أنّها جزء من النتيجة المستقبلية النهائية.

switch (terrain_anchor_state) {
  case AR_TERRAIN_ANCHOR_STATE_SUCCESS:
    // A resolving task for this anchor has been successfully resolved.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the
    // Geospatial API.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/c/group/ar-anchor#:~:text=from%20this%20error.-,AR_TERRAIN_ANCHOR_STATE_ERROR_NOT_AUTHORIZED,-The%20authorization%20provided
    // for troubleshooting steps.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_INTERNAL:
    // The Terrain anchor could not be resolved due to an internal error.
    break;
  default:
    break;
}

مثبّتات تثبيت الأسطح

مراسي الأسطح هي نوع من المراسي وهي تشبه إلى حدٍ بعيد مراسي التضاريس أعلاه. والفرق هو أنك ستقدم الارتفاع فوق السطح بدلاً من الارتفاع فوق التضاريس.

ملاحظة: تحتوي بعض المواقع الجغرافية على معلومات سطحية أكثر دقة من مواقع أخرى. لمزيد من المعلومات، يمكنك الاطّلاع على قسم الجودة في Streetscape Geometry.

إنشاء إعلان ثابت على السطح باستخدام واجهة برمجة التطبيقات الجديدة غير المتزامنة

لن تكون علامة الارتساء جاهزة على الفور ويجب حلّها.

لإنشاء علامة ارتساء على السطح ووضعها، اتصل بـ ArEarth_resolveAnchorOnRooftopAsync(). على غرار "إرساء التضاريس"، ستصل أيضًا إلى ArFutureState في المستقبل. ثم يمكنك الاطلاع على النتيجة المستقبلية للوصول إلى ArRooftopAnchorState.

استخدِم ArEarth_resolveAnchorOnRooftopAsync() لإنشاء ArResolveAnchorOnRooftopFuture.

يمكنك التحقّق من حالة الإرساء على السطح باستخدام ArResolveAnchorOnRooftopFuture_getResultRooftopAnchorState().

يمكنك الحصول على الإعلان الثابت الذي تم حلّه باستخدام ArResolveAnchorOnRooftopFuture_acquireResultAnchor().

float eus_quaternion_4[4] = {qx, qy, qz, qw};
void* context = NULL;
ArResolveAnchorOnRooftopCallback callback = NULL;
ArResolveAnchorOnRooftopFuture* future = NULL;
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArStatus status = ArEarth_resolveAnchorOnRooftopAsync(
        ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude_above_rooftop, eus_quaternion_4,
        context, callback, &future);
  }
}

الاطّلاع على وضع المستقبل

سيكون للمستقبل ArFutureState مرتبطة به. يمكنك الاطّلاع على الجدول أعلاه.

التحقّق من حالة ارتساء "السطح" لنتيجة المستقبل

تنتمي السمة ArRooftopAnchorState إلى العملية غير المتزامنة، كما أنّها جزء من النتيجة المستقبلية النهائية.

switch (rooftop_anchor_state) {
  case AR_ROOFTOP_ANCHOR_STATE_SUCCESS:
    // A resolving task for this anchor has been successfully resolved.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the
    // Geospatial API.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/c/group/ar-anchor#:~:text=from%20this%20error.-,AR_ROOFTOP_ANCHOR_STATE_ERROR_NOT_AUTHORIZED,-The%20authorization%20provided
    // for troubleshooting steps.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_INTERNAL:
    // The Rooftop anchor could not be resolved due to an internal error.
    break;
  default:
    break;
}

الخطوات التالية

• تأكَّد من فهم حصة استخدام واجهة برمجة التطبيقات الجيوفضائية.