استخدام علامات الارتساء الجغرافي المكاني لتحديد موضع المحتوى في الواقع على حزمة تطوير البرامج (SDK) لنظام التشغيل Android (Kotlin/Java)

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

أنواع نقاط الربط الجغرافية

هناك ثلاثة أنواع من نقاط الربط الجغرافية، يتعامل كلّ نوع منها مع الارتفاع بشكلٍ مختلف:

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

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

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

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

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

وضع عناصر مرجعية جغرافية

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   

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

   

   

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

   

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

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

استخدام Google Earth

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

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

1. انتقِل إلى Google Earth على الكمبيوتر المكتبي.

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

   

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

   

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

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

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

7. انقر على سهم الرجوع في لوحة المشروع واختَر إجراءات إضافية.

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

   

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

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

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

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

يمكنك احتساب ارتفاع موقع جغرافي من خلال الانتقال إليه وإجراء قياسات محلّية.

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

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

نقاط تثبيت WGS84

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

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

وضع عنصر تثبيت WGS84 في العالم الحقيقي

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

هناك بضع طرق لتحديد ارتفاع موقع جغرافي لوضع نقاط تثبيت:

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

إنشاء إعلان ثابت في أسفل الصفحة

بعد الحصول على خطوط الطول والعرض والارتفاع ورباعي الأبعاد للّفة، استخدِم Earth.createAnchor() لتثبيت المحتوى في الإحداثيات الجغرافية التي تحدّدها.

if (earth != null && earth.getTrackingState() == TrackingState.TRACKING) {
  Anchor anchor =
    earth.createAnchor(
      /* Location values */
      latitude,
      longitude,
      altitude,
      /* Rotational pose values */
      qx,
      qy,
      qz,
      qw);

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

if (earth.trackingState == TrackingState.TRACKING) {
  val anchor =
    earth.createAnchor(
      /* Location values */
      latitude,
      longitude,
      altitude,
      /* Rotational pose values */
      qx,
      qy,
      qz,
      qw
    )

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

نقاط تثبيت التضاريس

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

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

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

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

استخدِم Config.PlaneFindingMode لاختيار كيفية رصد تطبيقك للطائرات.

إنشاء عنصر تثبيت في ميزة "تضاريس Google Earth" باستخدام واجهة برمجة التطبيقات Async API الجديدة

لإنشاء عنصر تثبيت لسطح الأرض ووضعه، اتصل بالرقم Earth.resolveAnchorOnTerrainAsync().

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

final ResolveAnchorOnTerrainFuture future =
  earth.resolveAnchorOnTerrainAsync(
    latitude,
    longitude,
    /* altitudeAboveTerrain= */ 0.0f,
    qx,
    qy,
    qz,
    qw,
    (anchor, state) -> {
      if (state == TerrainAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    });

var future =
  earth.resolveAnchorOnTerrainAsync(
    latitude,
    longitude,
    altitudeAboveTerrain,
    qx,
    qy,
    qz,
    qw,
    { anchor, state ->
      if (state == TerrainAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    }
  )

الاطّلاع على "حالة المستقبل"

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

التحقّق من حالة عنصر التثبيت "التضاريس" للنتيجة المستقبلية

ينتمي Anchor.TerrainAnchorState إلى العملية غير المتزامنة وهو جزء من النتيجة النهائية المستقبلية.

switch (terrainAnchorState) {
  case SUCCESS:
    // A resolving task for this Terrain anchor has finished successfully.
    break;
  case ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the Geospatial API.
    break;
  case ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.TerrainAnchorState#error_not_authorized
    // for troubleshooting steps.
    break;
  case ERROR_INTERNAL:
    // The Terrain anchor could not be resolved due to an internal error.
    break;
  default:
    // not reachable
    break;
}

when (state) {
  TerrainAnchorState.SUCCESS -> {
    // A resolving task for this Terrain anchor has finished successfully.
  }
  TerrainAnchorState.ERROR_UNSUPPORTED_LOCATION -> {
    // The requested anchor is in a location that isn't supported by the Geospatial API.
  }
  TerrainAnchorState.ERROR_NOT_AUTHORIZED -> {
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.TerrainAnchorState#error_not_authorized
    // for troubleshooting steps.
  }
  TerrainAnchorState.ERROR_INTERNAL -> {
    // The Terrain anchor could not be resolved due to an internal error.
  }
  else -> {
    // Default.
  }
}

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

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

إنشاء شريط إعلاني على السطح باستخدام واجهة Async API الجديدة

لن يكون العنصر الثابت جاهزًا على الفور ويجب حلّه.

لإنشاء وتد تثبيت على سطح المنزل ووضعه، اتصل على Earth.resolveAnchorOnRooftopAsync(). على غرار علامات ارتساء التضاريس، ستصل أيضًا إلى FutureState المستقبل. يمكنك بعد ذلك الاطّلاع على نتيجة "المستقبل" للوصول إلى Anchor.RooftopAnchorState.

final ResolveAnchorOnRooftopFuture future =
  earth.resolveAnchorOnRooftopAsync(
    latitude,
    longitude,
    /* altitudeAboveRooftop= */ 0.0f,
    qx,
    qy,
    qz,
    qw,
    (anchor, state) -> {
      if (state == RooftopAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    });

var future =
  earth.resolveAnchorOnRooftopAsync(
    latitude,
    longitude,
    altitudeAboveRooftop,
    qx,
    qy,
    qz,
    qw,
    { anchor, state ->
      if (state == RooftopAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    }
  )

الاطّلاع على "حالة المستقبل"

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

التحقّق من حالة تثبيت Rooftop ضمن نتيجة Future

تنتمي Anchor.RooftopAnchorState إلى العملية غير المتزامنة وهي جزء من النتيجة المستقبلية النهائية.

switch (rooftopAnchorState) {
  case SUCCESS:
    // A resolving task for this Rooftop anchor has finished successfully.
    break;
  case ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the Geospatial API.
    break;
  case ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API.
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.RooftopAnchorState#error_not_authorized
    // for troubleshooting steps.
    break;
  case ERROR_INTERNAL:
    // The Rooftop anchor could not be resolved due to an internal error.
    break;
  default:
    // not reachable
    break;
}

when (state) {
  RooftopAnchorState.SUCCESS -> {
    // A resolving task for this Rooftop anchor has finished successfully.
  }
  RooftopAnchorState.ERROR_UNSUPPORTED_LOCATION -> {
    // The requested anchor is in a location that isn't supported by the Geospatial API.
  }
  RooftopAnchorState.ERROR_NOT_AUTHORIZED -> {
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.RooftopAnchorState#error_not_authorized
    // for troubleshooting steps.
  }
  RooftopAnchorState.ERROR_INTERNAL -> {
    // The Rooftop anchor could not be resolved due to an internal error.
  }
  else -> {
    // Default.
  }
}

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

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