با نحوه استفاده از Cloud Anchors در برنامه های خود آشنا شوید.
پیش نیازها
قبل از ادامه، مطمئن شوید که مفاهیم اساسی AR و نحوه پیکربندی یک جلسه ARCore را درک کرده اید.
اگر با Cloud Anchors تازه کار هستید، مطمئن شوید که نحوه کار لنگرها و Cloud Anchors را درک کرده اید.
ARCore API را فعال کنید
قبل از استفاده از Cloud Anchors در برنامه خود، ابتدا باید ARCore API را در برنامه خود فعال کنید.
قابلیت‌های Cloud Anchor را در پیکربندی جلسه فعال کنید
هنگامی که عملکرد Cloud Anchors در برنامه شما فعال شد، قابلیت‌های Cloud Anchors را در پیکربندی جلسه AR برنامه خود فعال کنید تا بتواند با ARCore API ارتباط برقرار کند:
// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);
// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);
// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
AR_CLOUD_ANCHOR_MODE_ENABLED);
// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);میزبان یک Cloud Anchor
میزبانی با تماس با ArSession_hostCloudAnchorAsync() شروع می شود. ARCore داده های بصری، ژست های دستگاه و ژست لنگر را در ARCore API آپلود می کند. سپس API این اطلاعات را پردازش می‌کند تا یک نقشه ویژگی سه‌بعدی ایجاد کند، و در نهایت یک شناسه لنگر ابری منحصر به فرد برای لنگر به دستگاه برمی‌گرداند.
همچنین می توانید با استفاده از ARCore Cloud Anchor Management API طول عمر یک لنگر میزبان را افزایش دهید.
برنامه شما باید این مراحل را برای تکمیل میزبانی یک Cloud Anchor دنبال کند:
- با
ArSession_hostCloudAnchorAsync()تماس بگیرید. - منتظر تماس باشید، یا به طور مداوم وضعیت آینده را بررسی کنید تا زمانی که انجام شود.
- وضعیت نتیجه را بررسی کنید تا مشخص شود آیا عملیات موفقیت آمیز بوده است یا اینکه در صورت عدم موفقیت، کد خطا را تفسیر کنید.
- شناسه Cloud Anchor نتیجه را با سایر مشتریان به اشتراک بگذارید و از آن برای حل کردن Cloud Anchor با
ArSession_resolveCloudAnchorAsync()استفاده کنید.
کیفیت نقشه برداری نقاط ویژگی را بررسی کنید
ArFeatureMapQuality کیفیت نقاط مشخصه ای را نشان می دهد که توسط ARCore در چند ثانیه قبل از یک حالت دوربین مشخص دیده می شود. لنگرهای ابری که با استفاده از ویژگی‌های با کیفیت بالاتر میزبانی می‌شوند، عموماً با دقت بیشتری حل می‌شوند. از ArSession_estimateFeatureMapQualityForHosting() برای به دست آوردن تخمینی برای کیفیت نقشه ویژگی برای یک ژست دوربین معین استفاده کنید.
| ارزش | توضیحات |
|---|---|
INSUFFICIENT | کیفیت نقاط مشخصه مشخص شده از ژست در چند ثانیه قبل پایین است. این حالت نشان می‌دهد که ARCore احتمالاً در حل Cloud Anchor با مشکلات بیشتری مواجه خواهد شد. کاربر را تشویق کنید تا دستگاه را حرکت دهد تا موقعیت دلخواه Cloud Anchor که می‌خواهد میزبانی کند، از زوایای مختلف قابل مشاهده باشد. |
SUFFICIENT | کیفیت نقاط مشخصه مشخص شده از حالت در چند ثانیه قبل احتمالاً برای ARCore برای حل موفقیت آمیز یک Cloud Anchor کافی است، اگرچه دقت پوزیشن حل شده احتمالاً کاهش می یابد. کاربر را تشویق کنید تا دستگاه را حرکت دهد تا موقعیت دلخواه Cloud Anchor که می‌خواهد میزبانی کند، از زوایای مختلف قابل مشاهده باشد. |
GOOD | کیفیت نقاط مشخصه مشخص شده از پوز در چند ثانیه قبل احتمالاً برای ARCore کافی است تا بتواند یک Cloud Anchor را با درجه بالایی از دقت حل کند. |
لنگر میزبانی شده قبلی را حل کنید
برای حل یک Cloud Anchor میزبانی شده، ArSession_resolveCloudAnchorAsync() را فراخوانی کنید. ARCore API به صورت دوره ای ویژگی های بصری صحنه را با نقشه ویژگی سه بعدی لنگر مقایسه می کند تا موقعیت و جهت گیری کاربر را نسبت به لنگر مشخص کند. هنگامی که API یک تطابق پیدا کرد، حالت Cloud Anchor میزبانی شده را برمی‌گرداند.
می‌توانید حل‌وفصل چندین Cloud Anchors را به ترتیب آغاز کنید. حداکثر 40 عملیات Cloud Anchor می‌تواند در یک زمان وجود داشته باشد.
یک عملیات را لغو کنید یا یک Cloud Anchor را حذف کنید
برای لغو عملیات Cloud Anchor در انتظار ArFuture_cancel() فراخوانی کنید. با ArAnchor_detach() تماس بگیرید تا ردیابی متوقف شود و یک Cloud Anchor از قبل حل شده فراموش شود. ارجاع به انکر باید به طور جداگانه با فراخوانی ArAnchor_release() منتشر شود.
وضعیت نتیجه عملیات Cloud Anchor را بررسی کنید
از ArCloudAnchorState برای بررسی وضعیت نتیجه میزبانی یا عملیات حل، از جمله خطاها استفاده کنید.
| ارزش | توضیحات |
|---|---|
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND | حل نشد زیرا ARCore API نتوانست شناسه Cloud Anchor ارائه شده را پیدا کند. |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED | میزبانی انجام نشد زیرا سرور نتوانست مجموعه داده را برای لنگر داده شده با موفقیت پردازش کند. بعد از اینکه دستگاه اطلاعات بیشتری از محیط جمع آوری کرد، دوباره امتحان کنید. |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE | ARCore API غیرقابل دسترسی بود. این ممکن است به دلایل مختلفی اتفاق بیفتد. ممکن است دستگاه در حالت هواپیما باشد یا اتصال اینترنت کار نمی کند. درخواست ارسال شده به سرور ممکن است بدون پاسخ به پایان رسیده باشد. ممکن است اتصال شبکه بد، در دسترس نبودن DNS، مشکلات فایروال یا هر چیز دیگری که ممکن است بر توانایی دستگاه برای اتصال به ARCore API تأثیر بگذارد، وجود داشته باشد. |
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL | یک کار میزبانی یا حل برای این لنگر با یک خطای داخلی به پایان رسید. برنامه نباید سعی کند از این خطا بازیابی کند. |
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED | عیب یابی مجوز ARCore API را ببینید. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW | Cloud Anchor قابل حل نیست زیرا نسخه SDK مورد استفاده برای حل انکر جدیدتر از نسخه استفاده شده برای میزبانی آن است و با آن ناسازگار است. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD | Cloud Anchor قابل حل نیست زیرا نسخه SDK مورد استفاده برای حل انکر قدیمی تر از نسخه استفاده شده برای میزبانی آن است و با آن ناسازگار است. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED | برنامه سهمیه درخواست اختصاص داده شده به پروژه Google Cloud داده شده را تمام کرده است. شما باید سهمیه اضافی برای ARCore API برای پروژه خود را از Google Developers Console درخواست کنید. |
AR_CLOUD_ANCHOR_STATE_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 در برنامه‌تان، مستندات مرجع Android NDK را بررسی کنید.