فعال کردن Geospatial API برای برنامه Android NDK خود (C)

تنظیمات برنامه خود را طوری پیکربندی کنید که بتواند از Geospatial API استفاده کند.

پیش نیازها

قبل از ادامه، مطمئن شوید که مفاهیم اساسی AR و نحوه پیکربندی یک جلسه ARCore را درک کرده اید.

اگر می‌خواهید یک برنامه نمونه اجرا کنید که عملکرد توضیح داده شده در اینجا را نشان می‌دهد، به ARCore Geospatial Quickstart برای Android برای جاوا مراجعه کنید. برنامه نمونه در Quickstart به زبان جاوا نوشته شده است. نمونه کدهای موجود در این سند برای همان عملکرد نوشته شده در C هستند.

برای اطلاعات بیشتر در مورد Geospatial API به مقدمه Geospatial API مراجعه کنید.

اگر در توسعه با ARCore تازه کار هستید، برای اطلاعات در مورد نیازهای نرم افزار و سخت افزار، پیش نیازها و سایر اطلاعات ویژه پلتفرم هایی که استفاده می کنید، به شروع به کار مراجعه کنید.

مطمئن شوید که محیط توسعه شما مطابق با نیازهای ARCore SDK، همانطور که در Quickstart برای جاوا توضیح داده شده است.

ARCore API را فعال کنید

قبل از استفاده از Visual Positioning System (VPS) در برنامه خود، ابتدا باید ARCore API را در پروژه Google Cloud جدید یا موجود فعال کنید. این سرویس وظیفه میزبانی، ذخیره و رفع لنگرهای جغرافیایی را بر عهده دارد.

مجوز بدون کلید ترجیح داده می شود، اما مجوز کلید API نیز پشتیبانی می شود.

کتابخانه های مورد نیاز را به برنامه خود اضافه کنید

پس از مجاز کردن برنامه خود برای فراخوانی ARCore API، باید کتابخانه‌هایی را اضافه کنید تا ویژگی‌های Geospatial را در برنامه خود فعال کنید.

در فایل build.gradle برنامه‌تان، سرویس‌های Google Play را طوری تنظیم کنید که کتابخانه مکان سرویس‌های Play را شامل شود.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

قابلیت های Geospatial را در پیکربندی جلسه فعال کنید

قبل از ایجاد جلسه، GeospatialMode در تنظیمات جلسه خود به ENABLED تغییر دهید:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

در حالی که حالت Geospatial روی ENABLED تنظیم شده است، برنامه مجاز است اطلاعات جغرافیایی را از سیستم موقعیت یابی بصری (VPS) به دست آورد.

از کاربر بخواهید اجازه استفاده از داده های دستگاه را بدهد

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

سازگاری دستگاه را بررسی کنید

همه دستگاه‌هایی که از ARCore پشتیبانی می‌کنند، از API Geospatial نیز پشتیبانی نمی‌کنند، همانطور که در شروع سریع برای جاوا توضیح داده شد.

برای بررسی سازگاری دستگاه کاربر، با ArSession_isGeospatialModeSupported() تماس بگیرید. اگر این مقدار false را برگرداند، سعی نکنید جلسه را پیکربندی کنید (زیر)، زیرا انجام این کار باعث می‌شود که ArStatus یک AR_ERROR_UNSUPPORTED_CONFIGURATION را گزارش کند.

از کاربر برای مجوزهای مکان در زمان اجرا بخواهید

برنامه شما باید مجوزهای مکان را در زمان اجرا درخواست کند .

برای استفاده از ARCore Geospatial API، برنامه شما باید مجوزهای اضافی زیر را ثبت کند:

• ACCESS_FINE_LOCATION برای تعیین دقیق مکان کاربر.

• ACCESS_COARSE_LOCATION برای تعیین غیر دقیق مکان کاربر و مطابقت با الزامات حریم خصوصی کاربر. با این حال، Geospatial API را نمی‌توان برای کار با مکان درشت پیکربندی کرد، و زمانی که کاربر این مجوز را تنظیم کرده باشد، درخواست‌های API با شکست مواجه می‌شوند. برای اطلاعات بیشتر قسمت زیر را ببینید.

• ACCESS_INTERNET برای تماس با سرویس ARCore Geospatial API.

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

در دستگاه‌هایی که دارای Android نسخه ۱۲ یا بالاتر هستند، کاربران می‌توانند درخواست کنند که برنامه شما فقط به اطلاعات موقعیت مکانی تقریبی دسترسی داشته باشد. برای انطباق با این درخواست، برنامه شما باید مجوز ACCESS_COARSE_LOCATION را به همراه ACCESS_FINE_LOCATION پیکربندی کرده باشد، همانطور که در بالا نشان داده شده است. شما باید هر دو مجوز مکان را پیکربندی کنید .

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

در دسترس بودن Geospatial را در مکان فعلی دستگاه بررسی کنید

از آنجایی که Geospatial API از ترکیبی از VPS و GPS برای تعیین موقعیت جغرافیایی استفاده می کند، تا زمانی که دستگاه قادر به تعیین موقعیت مکانی خود باشد، API می تواند مورد استفاده قرار گیرد. در مناطقی با دقت GPS پایین، مانند فضاهای داخلی و محیط‌های شهری متراکم، API برای ایجاد حالت‌های با دقت بالا به پوشش VPS متکی است. در شرایط معمولی می توان انتظار داشت که VPS دقت موقعیتی تقریباً 5 متر و دقت چرخشی 5 درجه را ارائه دهد. از ArSession_checkVpsAvailabilityAsync() برای تعیین اینکه آیا یک مکان مشخص دارای پوشش VPS است یا خیر استفاده کنید.

Geospatial API همچنین در مناطقی که پوشش VPS ندارند قابل استفاده است. در محیط‌های بیرونی که موانع بالای سرشان کم است یا اصلاً وجود ندارد، GPS ممکن است برای ایجاد یک حالت با دقت بالا کافی باشد.

بعدش چی

• موقعیت جغرافیایی دوربین دستگاه را برای تعیین مکان دقیق دستگاه کاربر در دنیای واقعی بدست آورید .
• در دسترس بودن VPS را در مکان معین دستگاه بررسی کنید .