یک برنامه واقعیت افزوده (AR) با استفاده از ARCore Geospatial API جدید بسازید

1. بررسی اجمالی

ARCore چارچوب گوگل برای ایجاد تجربیات واقعیت افزوده در گوشی های هوشمند است. ARCore Geospatial API جنبه جدیدی به واقعیت افزوده می دهد و به شما این امکان را می دهد که ایستگاه های راه واقعیت افزوده خاص مکان را در اطراف مکان های دیدنی دنیای واقعی قرار دهید.

چیزی که خواهی ساخت

در این کد لبه، شما با ARCore Geospatial API شروع می کنید. متوجه خواهید شد که Geospatial API چه اطلاعاتی را می تواند به تجربه کلی AR شما ارائه دهد و چگونه می توان از این داده ها برای تقویت یک تجربه راهیابی ساده AR استفاده کرد.

چیزی که یاد خواهید گرفت

• نحوه راه اندازی یک پروژه ARCore که از Geospatial API استفاده می کند.
• نحوه درخواست داده های جغرافیایی از Geospatial API و نمایش آن با استفاده از نقشه های گوگل.
• نحوه قرار دادن لنگر متصل به مکان واقعی.

آنچه شما نیاز دارید

• یک دستگاه Android ARCore پشتیبانی شده ، که با استفاده از کابل USB به دستگاه توسعه شما متصل است، با اشکال‌زدایی USB پیکربندی شده است.
• Android Studio برای ساخت برنامه های اندروید نصب و پیکربندی شده است.
• خدمات Google Play برای AR 1.31 یا جدیدتر، نصب شده در دستگاه توسعه Android.

2. محیط توسعه خود را تنظیم کنید

Android Studio را راه اندازی کنید

برای شروع کار با Geospatial API، یک پروژه آغازین ارائه کردیم که شامل اصول اولیه یک پروژه ARCore یکپارچه با Google Maps SDK است. این به شما یک شروع سریع با Geospatial API می دهد.

1. Android Studio را راه اندازی کنید و یک پروژه را از VCS وارد کنید.
   • اگر قبلاً پروژه ای باز دارید، از File > New > Project from Version Control... استفاده کنید.
   • اگر پنجره خوش آمدید به Android Studio را می بینید، از دریافت از VCS استفاده کنید.
2. Git را انتخاب کنید و از URL https://github.com/google-ar/codelab-geospatial.git برای وارد کردن پروژه استفاده کنید.

یک پروژه Google Cloud راه اندازی کنید

Geospatial API از تصاویر StreetView همراه با مغناطیس‌سنج دستگاه و اطلاعات حسگر دوربین برای بهبود مقادیر جهت‌گیری استفاده می‌کند. برای استفاده از این سرویس، باید یک Google Cloud Project راه اندازی کنید.

1. ایجاد یک پروژه در Google Cloud Console:
   • از ایجاد پروژه در Google Cloud Platform دیدن کنید.
     
   • نام پروژه مناسب را وارد کنید (به عنوان مثال، "پروژه ARC Geospatial API")، و هر مکانی را انتخاب کنید.
   • روی ایجاد کلیک کنید.
2. API های لازم را فعال کنید:
   • در نوار کناری، APIs & Services و سپس Library را انتخاب کنید.
   • ARCore API را جستجو کنید.
   • روی Enable کلیک کنید.
   • بازگشت به کتابخانه .
   • Maps SDK for Android را جستجو کنید.
   • روی Enable کلیک کنید.
3. ایجاد اعتبارنامه کلید API:
   • در بخش APIs & Services ، Credentials را انتخاب کنید.
   • در نوار بالا، روی Create Credentials کلیک کنید، سپس کلید API را انتخاب کنید.
   • به کلیدی که ایجاد شده است توجه داشته باشید زیرا برای مرحله بعدی به آن نیاز دارید. در صورت نیاز به بازیابی آن به صفحه اعتبارنامه بازگردید.

با این مراحل، یک پروژه Google Cloud با مجوز کلید API ایجاد کرده‌اید و آماده استفاده از Geospatial API هستید.

کلید API را با پروژه Android Studio یکپارچه کنید

برای مرتبط کردن کلید API از Google Cloud با پروژه خود، پروژه ای را که در Android Studio ایجاد کرده اید باز کنید و کلیدهای API را تغییر دهید:

1. برنامه > src > AndroidManifest.xml را باز کنید.
2. ورودی های meta-data زیر را بیابید:

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   
   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   

3. PLACEHOLDER_API_KEY با کلید API که در پروژه Google Cloud خود ایجاد کردید جایگزین کنید.

مقدار ذخیره شده در com.google.android.ar.API_KEY به این برنامه اجازه استفاده از Geospatial API را می دهد و مقدار ذخیره شده در com.google.android.geo.API_KEY به این برنامه اجازه استفاده از Google Maps SDK را می دهد.

پروژه خود را تایید کنید

اطمینان حاصل کنید که پروژه شما برای اجرا آماده است. در Android Studio، برنامه خود را اجرا کنید. شما باید بتوانید نمای دوربین را به همراه یک نقشه کار در پایین صفحه مشاهده کنید.

3. موقعیت کاربر را تعیین کنید

در این مرحله برای شروع با Geospatial API کدی را به پروژه نمونه اضافه می کنید.

جلسه ARCore را برای استفاده از Geospatial API پیکربندی کنید

برای به دست آوردن داده های مکانی، باید API Geospatial را فعال کنید. با تغییر تابع configureSession در HelloGeoActivity.kt ، GeospatialMode را در پیکربندی جلسه خود به ENABLED تغییر دهید:

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

در حالی که حالت Geospatial ENABLED است، برنامه می تواند اطلاعات Geospatial را به دست آورد.

درخواست داده از Geospatial API

در HelloGeoRenderer.kt ، خط زیر را پیدا کنید:

// TODO: Obtain Geospatial information and display it on the map.

در زیر آن، بررسی کنید که جسم زمین برای استفاده در دسترس است. این زمانی است که دارای trackingState TrackingState.ENABLED است.

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

در زیر TODO ، اطلاعات مکانی را از ARCore درخواست کنید. این خط را اضافه کنید:

val cameraGeospatialPose = earth.cameraGeospatialPose

این یک GeospatialPose به شما می دهد که حاوی این اطلاعات است:

• مکان، بیان شده در طول و عرض جغرافیایی. تخمینی از دقت مکان نیز ارائه شده است.
• ارتفاع، و برآورد دقت ارتفاع.
• هدینگ، تقریبی از جهتی که دستگاه رو به رو است و تخمینی از دقت عنوان.

نمایش اطلاعات موقعیت یابی بر روی نقشه

می توانید از GeospatialPose ذخیره شده در cameraGeospatialPose برای جابجایی نشانگری روی نقشه استفاده کنید که محل حضور کاربر را نشان می دهد. از جایی که متوقف کردید ادامه دهید و موارد زیر را اضافه کنید:

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

این به طور مداوم موقعیت نقشه را با استفاده از مقادیر بدست آمده از Geospatial API به روز می کند.

آن را امتحان کنید

در Android Studio، روی Play کلیک کنید. برای کمک به ARCore در ایجاد ردیابی، دستگاه خود را بالا نگه دارید و آن را حرکت دهید. پس از مدت کوتاهی، یک نشانگر سبز رنگ روی نقشه ظاهر می شود. این نشانگر با مشاهده محیط اطراف خود می چرخد. همچنین باید در جهت صحیح باشد: هنگامی که شما از نظر فیزیکی رو به شمال هستید، فلش نیز به سمت شمال است.

4. یک لنگر با استفاده از مختصات زمین قرار دهید

Geospatial API می تواند Anchors را در هر جفت مختصات و چرخش در دنیای واقعی قرار دهد. این به کاربران شما امکان می‌دهد هنگام بازدید از مکان‌های خاص، محتوای لنگر را ببینند.

در این مرحله با ضربه زدن روی نقشه راهی برای قرار دادن Anchor اضافه می کنید.

زمانی که روی نقشه ضربه می زند، اقدامی را تنظیم کنید

این پروژه دارای یک تابع onMapClick است که با کلیک بر روی قطعه نقشه، با طول و عرض جغرافیایی فراخوانی می شود. تابع onMapClick را در HelloGeoRenderer.kt پیدا کنید.

مطمئن شوید که شی زمین می تواند مورد استفاده قرار گیرد

قبل از ایجاد لنگرها بر روی زمین، مطمئن شوید که TrackingState جسم زمینی TRACKING است، به این معنی که موقعیت زمین مشخص است. همچنین مطمئن شوید که EarthState آن ENABLED است، به این معنی که هیچ مشکلی با Geospatial API مواجه نشده است. این خطوط را داخل onMapClick اضافه کنید:

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

موقعیت لنگر جدید را تعیین کنید

پس از تأیید اینکه شی زمین در حال ردیابی است، earthAnchor قبلی را در صورت وجود جدا کنید. در مراحل بعدی earthAnchor با یک لنگر جدید جایگزین می‌کنید:

earthAnchor?.detach()

سپس، از cameraGeospatialPose برای تعیین ارتفاع لنگر جدید استفاده کنید. از جفت مختصات ضربه زدن روی نقشه به عنوان موقعیت لنگر استفاده کنید.

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

createAnchor یک Anchor ثابت بر روی مختصات ژئودتیکی با یک چرخش مشخص ایجاد می کند. این لنگر تلاش می کند تا در مختصات و ارتفاع مشخص ثابت و ثابت بماند.

متغیرهای [qx, qy, qz, qw] چرخش لنگر بیان شده به صورت کواترنیون‌ها ، در سیستم مختصات شرق-بالا-جنوب (EUS) را تعیین می‌کنند. شما از مقادیر مختلفی برای چرخش لنگر استفاده می کنید، اما در این مثال، از یک کواترنیون واحد برای چرخش پیش فرض استفاده کنید. یک چرخش کواترنیون واحد دارای لنگر است که X+ به سمت شرق، Y+ به سمت بالا از مرکز زمین و Z+ به سمت جنوب اشاره می کند.

نشانگر قرار داده شده را روی نقشه نشان دهید

در نهایت، یک نشانگر جدید را جابجا کنید که نشانگر محل قرارگیری آن را نشان می دهد:

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

آن را امتحان کنید

در Android Studio، روی Play کلیک کنید. دستگاه خود را بالا نگه دارید و برای کمک به ARCore در ایجاد ردیابی آن را حرکت دهید. پس از مدت کوتاهی، یک نشانگر سبز رنگ روی نقشه ظاهر می شود که موقعیت فعلی شما را نشان می دهد.

ضربه زدن روی نقشه از Geospatial API برای قرار دادن یک لنگر استفاده می کند که در یک مکان واقعی ثابت می شود. سعی کنید لنگر را نزدیک مکان فعلی خود قرار دهید تا بتوانید آن را در نمای AR ببینید. همانطور که در محیط خود پیمایش می کنید باید پایدار بماند.

5. نتیجه گیری

در این کد لبه، یاد گرفتید که چگونه از Geospatial API برای ایجاد یک تجربه واقعیت افزوده ساده که به دنیای واقعی گره خورده است استفاده کنید.

آنچه را پوشش داده ایم

• نحوه راه اندازی یک پروژه Google Cloud با فعال بودن Geospatial API.
• نحوه بدست آوردن اطلاعات Geospatial در پروژه ARCore و نمایش آن بر روی نقشه
• نحوه قرار دادن لنگر در دنیای واقعی با استفاده از موقعیت جغرافیایی.

منابع اضافی

برای جزئیات بیشتر در مورد مفاهیم جغرافیایی و SDK های مورد استفاده در این کد لبه، به این منابع اضافی مراجعه کنید:

• مستندات ARCore Geospatial API
• سیستم ژئودتیک جهانی (WGS)
• Google Maps SDK برای اندروید