با Geospatial Creator in Unity شروع کنید

ARCore Geospatial Creator for Unity به شما امکان می دهد با نمایش داده های Google Maps در قالب کاشی های سه بعدی جدید، پیش نمایش محتوای Geospatial را در ویرایشگر Unity مشاهده کنید. این به شما کمک می کند تا زمانی که برنامه خود را می سازید، مکان قرار گرفتن محتوا در دنیای واقعی را تجسم کنید.

Geospatial Creator به عنوان بخشی از ARCore Extensions for AR در دسترس است. این شروع سریع به شما نشان می دهد که چگونه از Geospatial Creator در Unity برای افزودن محتوای AR مکانی به برنامه ARCore Geospatial Sample استفاده کنید.

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

پیش نیازها

برای پیکربندی محیط Unity خود برای ایجاد تجربیات AR ، «شروع با برنامه‌های افزودنی ARCore برای بنیاد AR» را دنبال کنید.

در حالی که ARCore Extensions از نسخه های قبلی Unity پشتیبانی می کند، Geospatial Creator به Unity 2021.3 یا جدیدتر نیاز دارد.

مجوز API

برای استفاده از ARCore Geospatial API و Google Map Tiles API باید دسترسی API را تنظیم کنید.

Google Map Tiles API

Map Tiles API یک نمایش سه بعدی و واقعی از مکان های پشتیبانی شده ارائه می دهد. ما از این کاشی‌ها در ویرایشگر Unity برای پیش‌نمایش ناحیه اطراف صحنه AR شما استفاده می‌کنیم.

برای فعال کردن API و کسب اطلاعات بیشتر در مورد Map Tiles، به صفحه Map Tiles API مراجعه کنید.

ARCore Geospatial API

ARCore Geospatial API توسط برنامه شما در زمان اجرا برای ایجاد و تعامل با Geospatial Anchors استفاده می‌شود.

برای فعال کردن Geospatial API ها، ARCore API را در برنامه خود راه اندازی کنید. می‌توانید از روش‌های مجوز Keyless (توصیه‌شده) یا API Key استفاده کنید.

برنامه Geospatial Sample را گسترش دهید

برای این راهنما، ما به شما نشان خواهیم داد که چگونه از Geospatial Creator برای افزودن محتوای مکانی به برنامه ARCore Geospatial Sample استفاده کنید.

نمونه Geospatial را پیکربندی کنید

ابتدا با اپلیکیشن ARCore Geospatial Sample آشنا شوید. در یک پروژه جدید Unity، Unity Package Manager را باز کرده و بسته ARCore Extensions را انتخاب کنید. در پانل جزئیات Package Manager، Samples را گسترش دهید و نمونه Geospatial را در پروژه Unity خود وارد کنید.

قبل از اجرای برنامه، باید عملکرد ARCore و Geospatial را در پروژه خود فعال کنید. از Edit > Project Settings... > XR Plug-in Management استفاده کنید. برای فعال کردن ارائه‌دهنده پلاگین ARCore برای Android و/یا ارائه‌دهنده پلاگین ARKit برای iOS، کادرهای مناسب را علامت بزنید.

سپس، از Edit > Project Settings... > XR Plug-in Management ، پنل ARCore Extensions را باز کنید. مطمئن شوید که "Geospatial" علامت زده شده است (هنوز نیازی به فعال کردن Geospatial Creator ندارید) و اعتبار API خود را وارد کنید. برای جزئیات بیشتر به مستندات "Enable the Geospatial Unity API" برای Android و iOS مراجعه کنید.

چند تنظیمات Player مخصوص پلتفرم دیگر وجود دارد که برای هر برنامه Unity که از ARCore استفاده می کند لازم است. برای تغییرات مورد نیاز به بخش پیکربندی تنظیمات پخش کننده در اسناد ما مراجعه کنید.

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

در مرحله بعد، نحوه استفاده از Geospatial Creator را برای ایجاد و تجسم محتوای پیچیده AR از داخل Unity Editor نشان خواهیم داد. این محتوا در مکان‌های طول و عرض جغرافیایی خاص در جهان در برنامه شما ظاهر می‌شود.

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

Geospatial Creator از یک بسته Unity شخص ثالث به نام Cesium برای رندر کردن Google Map Tiles در پنجره Unity Editor's Scene استفاده می کند. قبل از فعال کردن ویژگی‌های Geospatial Creator، اجازه دهید بسته Cesium را به پروژه خود اضافه کنیم.

توصیه می کنیم آخرین نسخه بسته Cesium for Unity را از صفحه گیت هاب Cesium نصب کنید:

1. جدیدترین نسخه .tgz از پیش کامپایل شده Cesium for Unity را از صفحه انتشارات GitHub آنها دانلود کنید. نسخه پیشنهادی فعلی بسته Cesium for Unity 1.1.0 است.
2. Unity Package Manager را با کلیک بر روی منوی "Window" Unity و سپس انتخاب "Package Manager" باز کنید.
3. روی نماد "+" کلیک کنید و "افزودن بسته از tarball" را انتخاب کنید.
4. فایل Cesium for Unity .tgz دانلود شده در مرحله 1 را انتخاب کنید.
5. ممکن است از شما خواسته شود که وابستگی های اضافی مانند Text Mesh Pro را نصب کنید.

Geospatial Creator را فعال کنید

اکنون آماده فعال کردن Geospatial Creator هستید:

1. از کادر گفتگوی Build Settings، مطمئن شوید که پلتفرم انتخابی شما «Android» یا «iOS» باشد. ویژگی‌های Geospatial Creator در حال حاضر برای پلتفرم‌های دیگر در دسترس نیستند.
2. به تنظیمات پروژه > مدیریت افزونه XR > برنامه های افزودنی ARCore بروید.
3. اگر کلید(های) ARCore Android و/یا iOS API خود را در مرحله قبلی تنظیم نکرده اید، حتماً همین الان این کار را انجام دهید.
4. هر دو کلید "Geospatial" و "Geospatial Creator" را فعال کنید. پس از کلیک بر روی فعال کردن جابجایی Geospatial Creator، یک جادوگر غیر مودال نمایش داده می شود تا تأیید کند که پروژه شما با Geospatial Creator سازگار است.
5. روی "Finish" در جادوگر کلیک کنید.

پس از اتمام جادوگر، Unity مجموعه ای از اسکریپت های شما را راه اندازی می کند. قبل از ادامه منتظر بمانید تا کامپایل مجدد کامل شود. (اگر پلتفرم انتخابی شما "Android" یا "iOS" نیست، اکنون به یکی از آنها بروید.)

با کاشی‌های نقشه، مبدأ خالق مکانی را اضافه کنید

صحنه شما دقیقاً به یک شی «منشأ خالق جغرافیایی» نیاز دارد. این شی به عنوان نقطه مرجع برای تبدیل مقادیر عرض جغرافیایی، طول جغرافیایی و ارتفاع در دنیای واقعی به مختصات بازی Unity استفاده می شود.

برای افزودن مبدا خالق مکانی به صحنه خود، Game Object > XR > Geospatial Creator Origin را انتخاب کنید. شی تازه ایجاد شده به یک georeference نیاز دارد که یک عرض جغرافیایی، طول و ارتفاع خاص را به موقعیت مبدا در مختصات بازی مرتبط می کند. از قسمت Geospatial Creator Origin's Inspector ، با کلیک روی دکمه Add Cesium Georeference Component، یک مرجع جغرافیایی اضافه کنید.

توجه: اگر منوی GameObject > XR شامل Geospatial Creator Origin نیست، مطمئن شوید که در حال ساخت برای Android یا iOS هستید و ضامن‌های Geospatial و Geospatial Creator را در تنظیمات پروژه > مدیریت افزونه XR > پنل ARCore Extensions فعال کرده‌اید.

Sesium Georeference علاوه بر اینکه نقطه مرجع برای اشیاء AR شما است، یک شی Cesium 3D Tileset را به صحنه اضافه می کند. این شی Google Map Tiles را در نمای صحنه ویرایشگر نمایش می دهد و به شما امکان می دهد دقیقاً در کجای جهان محتوای AR شما ظاهر شود. فیلدی در بازرس Geospatial Creator Origin برای اضافه کردن کلید Map Tiles API وجود دارد که قبلاً تنظیم کرده‌اید . پس از تنظیم این کلید، باید کاشی های نقشه را در نمای صحنه مشاهده کنید.

اکنون فیلدهای طول و عرض جغرافیایی و ارتفاع را تغییر دهید تا در نزدیکی جایی که می خواهید محتوای AR در برنامه شما نمایش داده شود قرار گیرند.

نکته: با پیدا کردن آن مکان در Google Maps و کلیک راست می‌توانید طول و عرض جغرافیایی بیشتر مکان‌ها را پیدا کنید. انتخاب طول و عرض جغرافیایی از منوی زمینه، مقادیر را در کلیپ بورد شما کپی می کند.

نمای صحنه در ویرایشگر اکنون باید کاشی های نقشه را در طول و عرض جغرافیایی مشخص شده مبدا نشان دهد. در زمان اجرا، فرض می‌کنیم برنامه شما از دوربین AR استفاده می‌کند، بنابراین Geospatial Creator قبلاً شیء Cesium 3D Map Tileset را با تگ «EditorOnly» پیکربندی کرده است. به همین دلیل، کاشی ها در زمان اجرا در بازی شما دانلود یا رندر نمی شوند. این را می توان از بازرس شی Cesium3DTileset تغییر داد. برای کسب اطلاعات بیشتر در مورد Georeference Cesium و GameObjects 3D Tileset، به اسناد Cesium for Unity مراجعه کنید.

نکته: محتوای نمای صحنه شما، از جمله کاشی های نقشه، ممکن است توسط عناصر رابط کاربری برنامه شما مسدود شود. می‌توانید با استفاده از منوی کشویی لایه‌ها در گوشه سمت راست بالای Unity Editor، لایه UI را در نمای صحنه ویرایشگر، بدون غیرفعال کردن UI در زمان اجرا، پنهان کنید.

یک Geospatial Creator Anchor اضافه و قرار دهید

اکنون آماده قرار دادن محتوای AR در صحنه خود هستید! روی GameObject > XR > Geospatial Creator Anchor کلیک کنید تا یک لنگر به سلسله مراتب صحنه خود اضافه کنید. از بازرس Anchor، می توانید طول جغرافیایی، طول و ارتفاع دقیق را مشخص کنید. تبدیل جسم بلافاصله به موقعیت صحیح در صحنه شما به روز می شود و می توانید دقیقاً در کجای جهان شی ظاهر شود.

همانطور که طول و عرض جغرافیایی لنگر را تنظیم می کنید، مکانی را انتخاب کنید که نزدیک است تا بتوانید اعتبار آن را در زمان اجرا در مکان صحیح قرار دهید. هنگام تنظیم ارتفاع یک لنگر ایجاد کننده جغرافیایی، سه گزینه دارید:

• زمین لنگر را در سطح زمین در عرض و طول جغرافیایی مشخص شده قرار می دهد. سطح زمین در زمان اجرا توسط سیستم موقعیت یابی بصری تعیین می شود. اگر با API های Geospatial ARCore تازه کار هستید، "Terrain" انتخاب خوبی است، زیرا لنگر مستقیماً روی زمین با درجه بالایی از دقت عمودی حل می شود. فیلد "Altitude Offset" به شما امکان می دهد لنگر را بر حسب متر در بالا یا زیر سطح زمین قرار دهید. به عنوان مثال، تعیین افست "1.0" باعث می شود لنگر یک متر بالاتر از زمین "شناور" شود.
• پشت بام لنگر را نسبت به بالای هر سازه در عرض و طول جغرافیایی معین قرار می دهد. مانند لنگر زمین، فیلد "Altitude Offset" به شما امکان می دهد لنگر را نسبت به موقعیت سقف، بر حسب متر به بالا یا پایین حرکت دهید.
• WGS84 لنگر را بر اساس سیستم مختصات WGS84 بر حسب متر در ارتفاع مطلق معین قرار می دهد. قرار دادن جسم به این صورت ممکن است نیاز به آزمون و خطا داشته باشد، زیرا ارتفاع "0" در WSG84 لزوماً نشان دهنده میانگین سطح دریا نیست و ممکن است با ارتفاع GPS مطابقت نداشته باشد. همچنین، در حالی که طول و عرض جغرافیایی کاشی های سه بعدی رندر شده بسیار دقیق است، تلاش برای قرار دادن شی در سطح زمین با استفاده از کاشی های سه بعدی به عنوان مرجع می تواند منجر به خطای ارتفاع تا چندین متر شود.

برای کسب اطلاعات بیشتر در مورد انواع مختلف ARCore Geospatial Anchors، به راهنمای توسعه دهنده Geospatial مراجعه کنید.

هر دو لنگر زمین و پشت بام دارای میدان ارتفاع WGS84 هستند. این مقدار فقط در حالت ویرایشگر برای تنظیم ارتفاع شی در نمای صحنه استفاده می شود. ارتفاع زمین و پشت بام فقط در زمان اجرا تعیین می شود، بنابراین فیلد WGS84 Altitude به شما امکان می دهد لنگر را در یک ارتفاع خاص در حین توسعه برنامه تجسم کنید. میدان ارتفاع WGS84 در زمان اجرا برای لنگرهای زمین و پشت بام نادیده گرفته می شود.

هندسه را به لنگر اضافه کنید

اگر اکنون برنامه را بسازید و اجرا کنید، لنگر را در برنامه فعال AR خود نخواهید دید. دلیلش این است که هیچ هندسه ای به آن متصل نیست. بیایید یک 3D اولیه ساده به لنگر اضافه کنیم: در سلسله مراتب صحنه، روی شی AR Geospatial Creator Anchor خود کلیک راست کنید. از منوی زمینه، 3D Object > Cube را انتخاب کنید. شما باید یک مکعب خاکستری را در نمای صحنه خود به عنوان فرزند لنگر خود ببینید. اگر تصمیم دارید موقعیت یا چرخش شی را در ویرایشگر جابه‌جا کنید، توصیه می‌کنیم شی ریشه Anchor را به جای کودک Cube primitive منتقل کنید. این به کاهش خطا در ترجمه از طول و عرض جغرافیایی به مختصات بازی کمک می کند.

البته می‌توانید هندسه پیچیده‌تر و اجزای دلخواه و کودکان را نیز به لنگر اضافه کنید.

اپلیکیشن خود را بسازید و اجرا کنید

وقت آن است که لنگر خود را در دنیای واقعی ببینید! سعی کنید برنامه خود را بسازید و اجرا کنید، سپس به مکانی بروید که انتظار دارید مکعب را ببینید. اونجا هست؟ تبریک می‌گوییم، شما آماده‌اید تا تجربیات AR پیچیده‌تری را با Geospatial Creator ایجاد کنید!

اگر مشکلی دارید، به راهنمای عیب‌یابی مراجعه کنید.

اکنون زمان بسیار خوبی برای اضافه کردن لنگرهای AR Geospatial Creator با هندسه های مختلف است. سعی کنید چندین لنگر روی پشت بام و زمین و افست آنها را آزمایش کنید. اسکریپت هایی را برای متحرک سازی یا فعال کردن تعامل با اشیاء اضافه کنید.

درک Geospatial Creator Anchors و کلاس ARGeospatialAnchor

هنگام ساخت تجربیات AR پیچیده و تعاملی، درک رابطه بین Geospatial Creator Anchors و کلاس ARGeospatialAnchor C# ARCore مفید است:

یک ARGeospatialAnchor فقط در زمان اجرا با فراخوانی یکی از توابع در ARAnchorManager ایجاد می شود و تنها زمانی می توان آنها را ایجاد کرد که جلسه AR تثبیت شود. می‌توان Geospatial Creator Anchor را به‌عنوان مکان‌هایی در نظر گرفت که در صحنه شما وجود دارد و منتظر است تا جلسه AR برای حل اشیاء ARGeospatialAnchor آماده شود. پس از آماده شدن جلسه، مکان نگهدار به طور خودکار با ARAnchorManager تماس می گیرد تا ARGeospatialAnchor را ایجاد و حل کند.

بلافاصله پس از حل شدن لنگر زمان اجرا، لنگر خالق مکانی در سلسله مراتب صحنه خود را به عنوان یک کودک به GameObject جدید متصل می کند. این بدان معنی است که هر مؤلفه یا فرزندان Geospatial Creator Anchor به زیر مؤلفه ها یا نوه های GameObject جدید ARGeospatialAnchor تبدیل می شوند. برای مثال، transform یک هندسه اولیه متصل به Geospatial Creator Anchor از transform ARGeospatialAnchor به ارث می‌رسد و بنابراین در محل مورد انتظار در جلسه AR زمان اجرا قرار می‌گیرد.

اگر نیاز به شناسایی ARGeospatialAnchor GameObject های خاصی در زمان اجرا دارید، می توانید صحنه را برای اشیایی جستجو کنید که ویژگی name آنها با لنگر ایجاد شده با استفاده از Geospatial Creator مطابقت دارد. اگر جلسه AR مقدار دهی اولیه شود، parent آن شی، شی ARGeospatialAnchor مربوطه خواهد بود.

عیب یابی

چرا لنگر من حرکت می کند؟

ممکن است متوجه شوید، به‌ویژه زمانی که برنامه برای اولین بار راه‌اندازی می‌شود، ممکن است به نظر برسد که لنگر به آرامی "دریفت" یا حتی چندین متر به طور ناگهانی می‌پرد. این زمانی اتفاق می افتد که جلسه VPS هنوز در حال تعیین و اصلاح مکان دقیق دوربین است. همانطور که دقت افقی و عمودی در چندین فریم بهبود می یابد، لنگر در مکان دقیق تری دوباره ترسیم می شود و توهم حرکت را ایجاد می کند. ممکن است بخواهید تا زمانی که دقت مکان به حد معینی برسد، شی را متفاوت (یا اصلاً) رندر کنید. برای انجام این کار، می توانید ویژگی ARCoreEarthManager.CameraGeospatialPose را برای تعیین دقت به روز رسانی فریم فعلی پرس و جو کنید.

چرا لنگر من در ارتفاع اشتباه ظاهر می شود؟

هنگام استفاده از نوع ارتفاع "دستی" برای لنگرهای خالق مکانی، ارتفاع لنگر مطابق WGS84 (بر حسب متر) تنظیم می شود. در یک مکان معین، ممکن است بین سطح زمین ظاهری نشان داده شده در کاشی های نقشه و سطح زمین واقعی که توسط سیستم موقعیت یابی بصری (VPS) گوگل گزارش شده است، اختلاف تا چندین متر وجود داشته باشد. اگر به نظر می رسد که یک لنگر مکانی در زمان اجرا به درستی قرار ندارد، توصیه می کنیم ارتفاع VPS را شخصاً با استفاده از پوشش اشکال زدایی در برنامه نمونه اعتبارسنجی کنید. سپس می توانید ارتفاع را در ویرایشگر Unity تغییر دهید تا با ارتفاع VPS شناخته شده در آن مکان مطابقت داشته باشد.

کاشی های نقشه به درستی در نمای صحنه ویرایشگر رندر نمی شوند

اگر به نظر می‌رسد که Cesium3DTileset در حال بارگذاری کاشی‌ها است، اما در نمای صحنه شما به رنگ سرخابی جامد رندر شده‌اند، بسته Shader Graph Unity را به پروژه خود اضافه کنید. این بسته توسط Cesium مورد نیاز است، اگرچه پروژه‌هایی که از رندر داخلی Unity استفاده می‌کنند به طور پیش‌فرض شامل آن نمی‌شوند.

برای افزودن Shader Graph، Unity Package Manager ( پنجره > Package Manager ) را باز کنید. با انتخاب "Packages: Unity Registry" از منوی کشویی در بالای پنجره Package Manager، مطمئن شوید که بسته های موجود در Unity Package Registry را مرور می کنید. پکیج com.unity.shadergraph را جستجو کنید و آخرین نسخه را نصب کنید. پس از بارگیری بسته، کاشی های سه بعدی باید دوباره بارگیری شوند و در نمای صحنه به درستی رندر شوند.

این برنامه در زمان اجرا به جای نمای دوربین، یک صفحه سیاه نمایش می دهد

خط لوله رندر جهانی (URP) Unity به طور پیش فرض برای دوربین AR پیکربندی نشده است. اگر در زمان اجرا به جای خروجی دوربین یک صفحه سیاه می بینید، باید AR Background Renderer Feature به هر URP Renderer در صحنه خود اضافه کنید.

برای افزودن این ویژگی، "رندر" را در پروژه خود جستجو کنید. برای هر شی URP Renderer، روی دکمه "Add Renderer Feature" در Inspector کلیک کنید و AR Background Renderer را اضافه کنید.

چرا لنگرهایی که دور از مبدا قرار گرفته اند به نظر می رسد اشتباه قرار گرفته اند؟

تبدیل مختصات WGS84 به مختصات بازی Unity به دلیل دقت محاسباتی ممیز شناور در معرض خطا است، که با اطمینان از اینکه مبدا شما در نزدیکی لنگرهای واقعیت افزوده است، می‌تواند به حداقل برسد. مسافت بیش از 20 کیلومتر ممکن است منجر به عدم دقت شود. اگر تجربه AR شما مسافت های طولانی را در بر می گیرد، توصیه می کنیم از چندین صحنه با یک لنگر منحصر به فرد در هر صحنه استفاده کنید.