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

تعتبر علامات ارتساء الموقع الجغرافي المكاني نوع من الارتساء الذي يسمح لك بوضع محتوى ثلاثي الأبعاد في العالم الحقيقي.

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

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

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

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

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

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

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

وضع علامات ارتساء الجغرافيا المكانية

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

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

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

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

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

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

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

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

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

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

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

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

• يمكنك استخدام Geospatial Creator لعرض محتوى ثلاثي الأبعاد حول العالم وتعزيزه بدون الحاجة إلى الانتقال إلى موقع جغرافي فعليًا. يتيح لك ذلك وضع محتوى مجسم ثلاثي الأبعاد بشكل مرئي باستخدام "خرائط 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 على أرض الواقع

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

هناك عدة طرق لتحديد ارتفاع الموقع من أجل وضع علامات ارتساء الموقع:

• إذا كان الموقع الجغرافي للارتساء قريبًا من المستخدم فعليًا، يمكنك استخدام ارتفاع مشابه لارتفاع جهاز المستخدم.
• بعد الحصول على خط العرض وخط الطول، استخدِم Elevelation API للحصول على ارتفاع استنادًا إلى مواصفات EGM96. يجب تحويل ارتفاع واجهة برمجة التطبيقات EGM96 إلى واجهة برمجة التطبيقات WGS84 للمقارنة مع ارتفاع GeospatialPose. راجع GeoidEval الذي يحتوي على سطر أوامر وواجهة HTML. تقدم واجهة برمجة التطبيقات للخرائط تقارير عن خطوط الطول والعرض وفقًا لمواصفات 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 لاختيار الطريقة التي يرصد بها تطبيقك الطائرات.

إنشاء إعلان ارتساء لتضاريس التضاريس باستخدام واجهة برمجة التطبيقات 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 مرتبط. يُرجى الاطّلاع على الجدول أعلاه.

التحقّق من حالة تثبيت السطح في نتيجة المستقبل

تنتمي 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.
  }
}

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

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