ردیابی_اشیاء_مکانی_XR_ANDROID
رشته نام
XR_ANDROID_spatial_object_tracking
نوع افزونه
افزونه نمونه
شماره داخلی ثبت شده
۷۸۶ عدد
بازنگری
۲
وضعیت تصویب
تصویب نشده
وابستگیهای افزونه و نسخه
XR_EXT_spatial_entity
آخرین تاریخ اصلاح
۲۰۲۵-۰۶-۲۵
وضعیت آیپی
هیچ ادعای مالکیت معنوی شناختهشدهای وجود ندارد.
مشارکتکنندگان
کایل چن، گوگل
نیهاو جین، گوگل
لوانا چن، گوگل
اسپنسر کوئین، گوگل
نمای کلی
این افزونه بر اساس XR_EXT_spatial_entity ساخته شده و یک قابلیت مکانی برای ردیابی مجموعهای از اشیاء فیزیکی از پیش تعریف شده بدون نیاز به مجموعه داده ورودی از برنامه تعریف میکند. به عنوان مثال، سیستم میتواند صفحه کلید، ماوس و سایر اشیاء موجود در محیط را ردیابی کند و سپس موقعیت و وسعت این اشیاء را به برنامه گزارش دهد.
مجوزها
برنامههای اندروید باید مجوز android.permission.SCENE_UNDERSTANDING_COARSE را در فایل مانیفست خود داشته باشند، زیرا این افزونه به هندسه محیط بستگی دارد. مجوز android.permission.SCENE_UNDERSTANDING_COARSE یک مجوز خطرناک محسوب میشود.
(سطح حفاظت: خطرناک)
پشتیبانی زمان اجرا
اگر زمان اجرا از ردیابی شیء پشتیبانی میکند، باید این را با شمارش XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID در xrEnumerateSpatialCapabilitiesEXT نشان دهد.
پیکربندی
ساختار XrSpatialCapabilityConfigurationObjectTrackingANDROID به صورت زیر تعریف میشود:
typedef struct XrSpatialCapabilityConfigurationObjectTrackingANDROID {
XrStructureType type;
const void* next;
XrSpatialCapabilityEXT capability;
uint32_t enabledComponentCount;
const XrSpatialComponentTypeEXT* enabledComponents;
uint32_t activeSemanticLabelCount;
const XrSpatialObjectSemanticLabelANDROID* activeSemanticLabels;
} XrSpatialCapabilityConfigurationObjectTrackingANDROID;
توضیحات اعضا
-
typeنوع XrStructureType این ساختار است. -
nextNULLیا اشارهگری به ساختار بعدی در یک زنجیره ساختار است. -
capabilityیک XrSpatialCapabilityEXT است و بایدXR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROIDباشد. -
enabledComponentCountیکuint32_tاست که تعداد عناصر موجود در آرایهenabledComponentsرا توصیف میکند. این مقدار باید بزرگتر از 0 باشد. -
enabledComponentsیک اشارهگر به آرایهای از XrSpatialComponentTypeEXT است. -
activeSemanticLabelCountیکuint32_tاست که تعداد عناصر موجود در آرایهactiveSemanticLabelsرا توصیف میکند. این مقدار میتواند 0 باشد، به این معنی که همه برچسبهای معنایی فعال هستند، یا میتواند بزرگتر از 0 باشد، که در این صورت از آرایهactiveSemanticLabelsبرای تعیین اینکه کدام برچسبهای معنایی فعال هستند استفاده میشود. -
activeSemanticLabelsیک اشارهگر به آرایه XrSpatialObjectSemanticLabelANDROID است که اشیاء فعال در ردیابی را نشان میدهد. اگرactiveSemanticLabelCountبرابر با ۰ باشد، باید null باشد. و اگرactiveSemanticLabelCountبزرگتر از ۰ باشد، باید non-null باشد، به این معنی که برای تعیین اینکه کدام برچسبهای معنایی فعال هستند، استفاده میشود.
برنامهها میتوانند قابلیت مکانی XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID را با اضافه کردن یک اشارهگر به ساختار XrSpatialCapabilityConfigurationObjectTrackingANDROID در XrSpatialContextCreateInfoEXT :: capabilityConfigs فعال کنند.
اگر capability XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.
برنامهها میتوانند برچسبهای معنایی مورد نظر خود را در activeSemanticLabels که مایل به ردیابی آنها هستند، مشخص کنند. اگر هیچ برچسب معنایی در activeSemanticLabels مشخص نشده باشد و activeSemanticLabelCount برابر با ۰ باشد، تمام برچسبهای معنایی به طور پیشفرض برای ردیابی فعال هستند.
کاربرد معتبر (ضمنی)
- افزونهی
XR_ANDROID_spatial_object_trackingباید قبل از استفاده از XrSpatialCapabilityConfigurationObjectTrackingANDROID فعال شود. -
typeبایدXR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_ANDROIDباشد. -
nextبایدNULLیا یک اشارهگر معتبر به ساختار بعدی در یک زنجیره ساختار باشد. -
capabilityباید یک مقدار معتبر XrSpatialCapabilityEXT باشد. -
enabledComponentsباید اشارهگری به آرایهای ازenabledComponentCountبا مقادیر معتبر XrSpatialComponentTypeEXT باشد. -
activeSemanticLabelsباید اشارهگری به آرایهای از مقادیر معتبرactiveSemanticLabelCountدر XrSpatialObjectSemanticLabelANDROID باشد. - پارامتر
enabledComponentCountباید بزرگتر از0باشد. - پارامتر
activeSemanticLabelCountباید بزرگتر از0باشد.
قطعات تضمین شده
یک زمان اجرای که از XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID پشتیبانی میکند ، باید از اجزای مکانی زیر به عنوان اجزای تضمینشدهی موجودیتهای کشفشده توسط این قابلیت پشتیبانی کند و باید آنها را در xrEnumerateSpatialCapabilityComponentTypesEXT شمارش کند -
-
XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT - قابلیت ردیابی شیء بدون یک مؤلفه برچسب معنایی بیمعنی است. در حالی که این افزونه
XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROIDXR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROIDبه عنوان یکی از مؤلفههای برچسب معنایی ممکن برای پشتیبانی در زمان اجرا تعریف میکند، سایر افزونهها ممکن است انواع مؤلفههای جدیدی را تعریف کنند تا کلاسهای مختلفی از برچسبهای معنایی را ارائه دهند که یک شیء ردیابی شده را توصیف میکنند.
کامپوننت سهبعدی محدود
مولفه سهبعدی محدود، مرکز و محدوده شیء نمایش داده شده توسط موجودیتی که روی آن قرار دارد را فراهم میکند. برای جزئیات بیشتر به بخش سهبعدی محدود مراجعه کنید.
کامپوننت برچسب معنایی شیء
دادههای کامپوننت
typedef enum XrSpatialObjectSemanticLabelANDROID {
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_ANDROID = 0,
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_KEYBOARD_ANDROID = 1,
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_MOUSE_ANDROID = 2,
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAPTOP_BASE_ANDROID = 3,
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialObjectSemanticLabelANDROID;
شمارش XrSpatialObjectSemanticLabelANDROID مجموعهای از برچسبهای معنایی را برای یک شیء توصیف میکند.
توضیحات شمارشی
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_ANDROID
زمان اجرا قادر به طبقهبندی این موجودیت نبود.
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_KEYBOARD_ANDROID
این موجودیت یک صفحه کلید است.
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_MOUSE_ANDROID
آن موجود یک موش است.
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAPTOP_BASE_ANDROID
دستگاه مورد نظر یک لپتاپ است.
جهت گیری فضایی اشیا
جهتگیری اشیاء در تصویر زیر (با xyz = rgb) که از مرکز پایین اشیاء شروع میشود، نشان داده شده است.
جهتگیری سهبعدی ماوس با جهتگیری سهبعدی صفحهی نگهدارنده همراستا است. این محدودهها، کیبورد و ماوس و پایهی لپتاپ را بهطور کامل در بر میگیرند.
شکل ۳۴. نمونهای از جهتگیری شیءگرا.
ساختار لیست کامپوننت برای پرس و جو از دادهها
ساختار XrSpatialComponentObjectSemanticLabelListANDROID به صورت زیر تعریف شده است:
typedef struct XrSpatialComponentObjectSemanticLabelListANDROID {
XrStructureType type;
void* next;
uint32_t semanticLabelCount;
XrSpatialObjectSemanticLabelANDROID* semanticLabels;
} XrSpatialComponentObjectSemanticLabelListANDROID;
توضیحات اعضا
-
typeنوع XrStructureType این ساختار است. -
nextباNULLیا اشارهگری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشدهاند. -
semanticLabelCountیکuint32_tاست که تعداد عناصر موجود در آرایهsemanticLabelsرا توصیف میکند. -
semanticLabelsآرایهای از XrSpatialObjectSemanticLabelANDROID است.
برنامه میتواند با اضافه کردن XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_ANDROID در XrSpatialComponentDataQueryConditionEXT :: componentTypes و اضافه کردن XrSpatialComponentObjectSemanticLabelListANDROID به زنجیره اشارهگر بعدی XrSpatialComponentDataQueryResultEXT ، کامپوننت برچسب معنایی موجودیتهای مکانی را در XrSpatialSnapshotEXT جستجو کند.
اگر XrSpatialComponentObjectSemanticLabelListANDROID در زنجیره بعدی XrSpatialComponentDataQueryResultEXT :: next باشد اما XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID در XrSpatialComponentDataQueryConditionEXT :: componentTypes گنجانده نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE از xrQuerySpatialComponentDataEXT بازگرداند.
اگر semanticLabelCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT از xrQuerySpatialComponentDataEXT برگرداند.
کاربرد معتبر (ضمنی)
- افزونهی
XR_ANDROID_spatial_object_trackingباید قبل از استفاده از XrSpatialComponentObjectSemanticLabelListANDROID فعال شود. -
typeبایدXR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_ANDROIDباشد. -
nextبایدNULLیا یک اشارهگر معتبر به ساختار بعدی در یک زنجیره ساختار باشد. -
semanticLabelsباید اشارهگری به آرایهای از مقادیرsemanticLabelCountXrSpatialObjectSemanticLabelANDROID باشد. - پارامتر
semanticLabelCountباید بزرگتر از0باشد.
پیکربندی
اگر XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID برای برخی قابلیتها در XrSpatialCapabilityComponentTypesEXT :: componentTypes شمارش شده باشد، برنامه میتواند با قرار دادن enum در لیست XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents از ساختار مشتق شده XrSpatialCapabilityConfigurationBaseHeaderEXT از قابلیتی که از این مولفه پشتیبانی میکند، آن را فعال کند.
این کامپوننت برای قرار گرفتن در زنجیره بعدی XrSpatialCapabilityConfigurationBaseHeaderEXT به هیچ پیکربندی خاصی نیاز ندارد.
کد مثال
پیکربندی قابلیت ردیابی شیء
کد مثال زیر نحوه پیکربندی قابلیت ردیابی شیء را هنگام ایجاد یک زمینه مکانی نشان میدهد.
// Check if object tracking capability is supported
uint32_t capabilityCount = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID) == capabilities.end()) {
return;
}
// Enumerate supported components for object tracking capability
XrSpatialCapabilityComponentTypesEXT objectComponents{
.type = XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT,
};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID, &objectComponents));
std::vector<XrSpatialComponentTypeEXT> objectCapabilityComponents(objectComponents.componentTypeCountOutput);
objectComponents.componentTypeCapacityInput = objectCapabilityComponents.size();
objectComponents.componentTypes = objectCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID, &objectComponents));
// Create a spatial context
XrSpatialContextEXT spatialContext{XR_NULL_HANDLE};
// Enable the 2 guaranteed components (bounded 3D, semantic label) of the object tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID,
};
// Specify some semantic labels to be active and tracked
std::vector<XrSpatialObjectSemanticLabelANDROID> activeSemanticLabels =
{
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_KEYBOARD_ANDROID,
XR_SPATIAL_OBJECT_SEMANTIC_LABEL_MOUSE_ANDROID,
};
XrSpatialCapabilityConfigurationObjectTrackingANDROID objectTrackingConfig{
.type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_ANDROID,
.capability = XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID,
.enabledComponentCount = static_cast<uint32_t>(enabledComponents.size()),
.enabledComponents = enabledComponents.data(),
// Specify the count of active semantic labels and the pointer to the array of
// active semantic labels.
// If the `activeSemanticLabelCount` is 0 and `activeSemanticLabels` is NULL,
// all labels will be set to active by default.
.activeSemanticLabelCount = static_cast<uint32_t>(activeSemanticLabels.size()),
.activeSemanticLabels = activeSemanticLabels.data(),
};
std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&objectTrackingConfig),
};
XrSpatialContextCreateInfoEXT spatialContextCreateInfo{
.type = XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT,
.capabilityConfigCount = capabilityConfigs.size(),
.capabilityConfigs = capabilityConfigs.data(),
};
XrFutureEXT createContextFuture {XR_NULL_FUTURE_EXT};
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));
waitUntilReady(createContextFuture);
XrCreateSpatialContextCompletionEXT completion{
.type = XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT,
};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS) {
return;
}
spatialContext = completion.spatialContext;
// ...
// Discover entities with the spatial context
// ...
CHK_XR(xrDestroySpatialContextEXT(spatialContext));
کشف موجودیتهای مکانی و جستجوی دادههای کامپوننت
کد مثال زیر نحوهی کشف موجودیتهای مکانی برای یک context پیکربندیشده با XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID و پرسوجو از دادههای مؤلفهی آن را نشان میدهد.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID,
};
auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
.type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
.componentTypeCount = static_cast<uint32_t>(snapshotComponents.size()),
.componentTypes = snapshotComponents.data(),
};
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));
waitUntilReady(future);
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{
.type = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
.baseSpace = localSpace,
.time = time,
.future = future,
};
XrCreateSpatialDiscoverySnapshotCompletionEXT completion{
.type = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT,
};
CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
if (completion.futureResult == XR_SUCCESS) {
// Query for the semantic label component data
XrSpatialComponentDataQueryConditionEXT queryCond{
.type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
.componentTypeCount = static_cast<uint32_t>(snapshotComponents.size()),
.componentTypes = snapshotComponents.data(),
};
XrSpatialComponentDataQueryResultEXT queryResult{
.type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};
CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));
std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();
queryResult.entityStateCapacityInput = entityStates.size();
queryResult.entityStates = entityStates.data();
std::vector<XrBoxf> bounded3D(queryResult.entityIdCountOutput);
XrSpatialComponentBounded3DListEXT bounded3DList{
.type = XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT,
.boundCount = static_cast<uint32_t>(bounded3D.size()),
.bounds = bounded3D.data(),
};
queryResult.next = &bounded3DList;
std::vector<XrSpatialObjectSemanticLabelANDROID> semanticLabels(queryResult.entityIdCountOutput);
XrSpatialComponentObjectSemanticLabelListANDROID semanticLabelsList{
.type = XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_ANDROID,
.semanticLabelCount = static_cast<uint32_t>(semanticLabels.size()),
.semanticLabels = semanticLabels.data(),
};
queryResult.next = &semanticLabelsList;
CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));
for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
if (entityStates[i] != XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
continue;
}
// 3D bounds for entity entityIds[i] is bounded3D[i].extents centered on bounded3D[i].center.
// semantic label for entity entityIds[i] is semanticLabels[i].
}
CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
}
};
while (1) {
// ...
// For every frame in frame loop
// ...
XrFrameState frameState; // previously returned from xrWaitFrame
const XrTime time = frameState.predictedDisplayTime;
// Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
XrEventDataBuffer event = {
.type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
if (event.type == XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT) {
const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
*reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
// Discover spatial entities for the context that we received the "discovery
// recommended" event for.
discoverSpatialEntities(eventdata.spatialContext, time);
}
}
// ...
// Finish frame loop
// ...
}
سازههای جدید
Enum های جدید
ثابتهای شمارشی جدید
-
XR_ANDROID_SPATIAL_OBJECT_TRACKING_EXTENSION_NAME -
XR_ANDROID_spatial_object_tracking_SPEC_VERSION گسترش XrSpatialCapabilityEXT :
-
XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID
-
بسط XrSpatialComponentTypeEXT :
-
XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID
-
گسترش XrStructureType :
-
XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_ANDROID -
XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_ANDROID
-
مسائل
تاریخچه نسخه
نسخه ۱، ۲۰۲۵-۰۶-۲۶ (کایل چن)
- توضیحات اولیه افزونه
نسخه ۲، ۲۰۲۵-۱۲-۰۴ (کایل چن)
- قالب مثال را به سبک جدید بهروزرسانی کنید.