راهنمای توسعه دهنده Cloud Anchors برای Unity (AR Foundation)

مهم: ARCore Cloud Anchor API به برنامه‌های افزودنی ARCore برای بنیاد AR نیاز دارد. قبل از ادامه، مطمئن شوید که برنامه‌های افزودنی را نصب و پیکربندی کرده‌اید .

با نحوه استفاده از Cloud Anchors در برنامه های خود آشنا شوید.

پیش نیازها

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

اگر با Cloud Anchors تازه کار هستید، مطمئن شوید که نحوه کار لنگرها و Cloud Anchors را درک کرده اید.

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

قبل از استفاده از Cloud Anchors در برنامه خود، ابتدا باید ARCore API را در برنامه خود فعال کنید.

مهم: برنامه‌هایی که میزبان و حل‌وفصل Cloud Anchors با TTL بیشتر از 1 روز هستند، باید از مجوز بدون کلید استفاده کنند. هنگام استفاده از کلید API، Cloud Anchors حداکثر 24 ساعت طول عمر دارد.

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

هنگامی که عملکرد Cloud Anchors در برنامه شما فعال شد، قابلیت‌های Cloud Anchors را در پیکربندی جلسه AR برنامه خود فعال کنید تا بتواند با ARCore API ارتباط برقرار کند:

میزبان یک Cloud Anchor

میزبانی با تماس با ARAnchorManager.HostCloudAnchorAsync() شروع می شود. ARCore داده های بصری، ژست های دستگاه و ژست لنگر را در ARCore API آپلود می کند. سپس API این اطلاعات را پردازش می‌کند تا یک نقشه ویژگی سه بعدی بسازد و در نهایت یک شناسه لنگر ابری منحصر به فرد را برای لنگر به دستگاه برمی‌گرداند.

توجه: داده‌های بصری آپلود شده در فضای ابری هنگام میزبانی یک لنگر در عرض 24 ساعت حذف می‌شوند و داده‌های بصری بارگذاری‌شده قبلی هرگز به دستگاه کاربر ارسال نمی‌شوند.

همچنین می توانید با استفاده از ARCore Cloud Anchor Management API طول عمر یک لنگر میزبان را افزایش دهید.

برنامه شما باید این مراحل را برای تکمیل میزبانی یک Cloud Anchor دنبال کند:

1. با ARAnchorManager.HostCloudAnchorAsync() تماس بگیرید.
2. یک کوروتین را شروع کنید تا منتظر بمانید تا Promise به نتیجه برسد. برای اطلاعات بیشتر به Coroutines in Unity مراجعه کنید.
3. وضعیت نتیجه را بررسی کنید تا مشخص شود آیا عملیات موفقیت آمیز بوده است یا اینکه در صورت عدم موفقیت، کد خطا را تفسیر کنید.
4. شناسه Cloud Anchor نتیجه را با مشتریان دیگر به اشتراک بگذارید و از آن برای حل کردن Cloud Anchor با ARAnchorManagerExtensions.ResolveCloudAnchorAsync() استفاده کنید.

کیفیت نقشه برداری نقاط ویژگی را بررسی کنید

ARCoreExtensions.FeatureMapQuality کیفیت نقاط مشخصه ای را نشان می دهد که توسط ARCore در چند ثانیه قبل از یک حالت دوربین مشخص دیده می شود. لنگرهای ابری که با استفاده از ویژگی‌های با کیفیت بالاتر میزبانی می‌شوند، عموماً با دقت بیشتری حل می‌شوند. از ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() برای بدست آوردن تخمینی برای کیفیت نقشه ویژگی برای یک ژست دوربین معین استفاده کنید.

ارزش	شرح
Insufficient	کیفیت نقاط مشخصه مشخص شده از ژست در چند ثانیه قبل پایین است. این حالت نشان می‌دهد که ARCore احتمالاً در حل Cloud Anchor با مشکلات بیشتری مواجه خواهد شد. کاربر را تشویق کنید تا دستگاه را حرکت دهد تا موقعیت دلخواه Cloud Anchor که می‌خواهد میزبانی کند، از زوایای مختلف قابل مشاهده باشد.
Sufficient	کیفیت نقاط مشخصه مشخص شده از حالت در چند ثانیه قبل احتمالاً برای ARCore برای حل موفقیت آمیز یک Cloud Anchor کافی است، اگرچه دقت پوزیشن حل شده احتمالاً کاهش می یابد. کاربر را تشویق کنید تا دستگاه را حرکت دهد تا موقعیت دلخواه Cloud Anchor که می‌خواهد میزبانی کند، از زوایای مختلف قابل مشاهده باشد.
Good	کیفیت نقاط مشخصه مشخص شده از پوز در چند ثانیه قبل احتمالاً برای ARCore کافی است تا بتواند یک Cloud Anchor را با درجه بالایی از دقت حل کند.

لنگر میزبانی شده قبلی را حل کنید

برای حل یک Cloud Anchor میزبانی شده ARAnchorManagerExtensions.ResolveCloudAnchorAsync() تماس بگیرید. ARCore API به صورت دوره ای ویژگی های بصری صحنه را با نقشه ویژگی سه بعدی لنگر مقایسه می کند تا موقعیت و جهت گیری کاربر را نسبت به لنگر مشخص کند. هنگامی که API یک تطابق پیدا کرد، حالت Cloud Anchor میزبانی شده را برمی‌گرداند.

می‌توانید حل‌وفصل چندین Cloud Anchors را به ترتیب آغاز کنید. حداکثر 40 عملیات Cloud Anchor می‌تواند در یک زمان وجود داشته باشد.

یک عملیات را لغو کنید یا یک Cloud Anchor را حذف کنید

زمانی که کامپوننت ARCloudAnchor از شی بازی حاوی آن حذف شود ARCloudAnchor.OnDestroy() به طور خودکار فراخوانی می شود. این شیء اصلی Cloud Anchor را جدا کرده و آزاد می کند.

وضعیت نتیجه عملیات Cloud Anchor را بررسی کنید

از CloudAnchorState برای بررسی وضعیت نتیجه میزبانی یا عملیات حل، از جمله خطاها استفاده کنید.

ارزش	شرح
ErrorResolvingCloudIdNotFound	حل نشد زیرا ARCore API نتوانست شناسه Cloud Anchor ارائه شده را پیدا کند.
ErrorHostingDatasetProcessingFailed	میزبانی انجام نشد زیرا سرور نتوانست مجموعه داده را برای لنگر داده شده با موفقیت پردازش کند. بعد از اینکه دستگاه اطلاعات بیشتری از محیط جمع آوری کرد، دوباره امتحان کنید.
ErrorHostingServiceUnavailable	ARCore API غیرقابل دسترسی بود. این ممکن است به دلایل مختلفی اتفاق بیفتد. ممکن است دستگاه در حالت هواپیما باشد یا اتصال اینترنت کار نمی کند. درخواست ارسال شده به سرور ممکن است بدون پاسخ به پایان رسیده باشد. ممکن است اتصال شبکه بد، در دسترس نبودن DNS، مشکلات فایروال یا هر چیز دیگری که ممکن است بر توانایی دستگاه برای اتصال به ARCore API تأثیر بگذارد، وجود داشته باشد.
ErrorInternal	یک کار میزبانی یا حل برای این لنگر با یک خطای داخلی به پایان رسید. برنامه نباید سعی کند از این خطا بازیابی کند.
ErrorNotAuthorized	به دلیل مجوز نامعتبر، برنامه نمی تواند با ARCore API ارتباط برقرار کند. تنظیمات پروژه > XR > برنامه های افزودنی ARCore را برای استراتژی مجوز معتبر بررسی کنید.
ErrorResolvingPackageTooNew	Cloud Anchor قابل حل نیست زیرا بسته ARCore Extensions مورد استفاده برای حل کردن Cloud Anchor جدیدتر از نسخه مورد استفاده برای میزبانی آن است و با آن ناسازگار است.
ErrorResolvingPackageTooOld	Cloud Anchor قابل حل نیست زیرا بسته ARCore Extensions که برای حل کردن Cloud Anchor استفاده می‌شود قدیمی‌تر از نسخه مورد استفاده برای میزبانی آن است و با آن ناسازگار است.
ErrorResourceExhausted	برنامه سهمیه درخواست اختصاص داده شده به پروژه Google Cloud داده شده را تمام کرده است. شما باید سهمیه اضافی برای ARCore API برای پروژه خود را از Google Developers Console درخواست کنید.
Success	یک کار میزبانی یا حل و فصل برای این لنگر با موفقیت انجام شد.

سهمیه های API برای درخواست هاست و حل و فصل

ARCore API دارای سهمیه های زیر برای پهنای باند درخواست است:

نوع سهمیه	بیشترین	مدت زمان	اعمال می شود
تعداد لنگرها	نامحدود	N/A	پروژه
درخواست های میزبان لنگر	30	دقیقه	آدرس IP و پروژه
لنگر حل و فصل درخواست	300	دقیقه	آدرس IP و پروژه

بهترین روش ها برای یک تجربه کاربری خوب

به کاربران دستور دهید تا برای اطمینان از تجربه کاربری خوب در برنامه خود، موارد زیر را انجام دهند:

• چند ثانیه بعد از شروع جلسه صبر کنید و قبل از اقدام به میزبانی لنگر (با قرار دادن یک شی و غیره) بمانید. این به ردیابی مدتی زمان برای تثبیت می دهد.
• هنگام انتخاب مکانی برای میزبانی لنگر، سعی کنید منطقه ای با ویژگی های بصری پیدا کنید که به راحتی از یکدیگر قابل تشخیص باشند. برای بهترین نتیجه، از سطوح بازتابنده یا سطوحی که فاقد ویژگی های بصری هستند، مانند دیوارهای سفید خالی اجتناب کنید.

• دوربین را در مرکز مورد نظر آموزش دهید و دستگاه را در اطراف مرکز مورد نظر حرکت دهید تا از زوایای مختلف محیط را ترسیم کنید و تقریباً همان فاصله فیزیکی خود را حفظ کنید. این به گرفتن داده‌های بصری بیشتر کمک می‌کند و حل‌وفصل را قوی‌تر می‌کند.

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

• هنگام میزبانی و حل و فصل Cloud Anchors اطمینان حاصل کنید که در محیط واقعی نور کافی وجود دارد.

سیاست استهلاک

• برنامه‌های ساخته شده با ARCore SDK 1.12.0 یا بالاتر تحت پوشش خط‌مشی لغو Cloud Anchor API هستند.
• برنامه‌های ساخته شده با ARCore SDK 1.11.0 یا پایین‌تر، به دلیل استفاده SDK از ARCore API قدیمی‌تر و منسوخ، قادر به میزبانی یا حل کردن Cloud Anchors نیستند.

بعدش چی

• برای راه‌های بیشتر استفاده از ARCore در برنامه‌تان ، اسناد مرجع ARCore Extensions for AR Foundation را بررسی کنید.