ردیابی_اشیاء_مکانی_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 این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • 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_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID پشتیبانی می‌کند ، باید از اجزای مکانی زیر به عنوان اجزای تضمین‌شده‌ی موجودیت‌های کشف‌شده توسط این قابلیت پشتیبانی کند و باید آن‌ها را در xrEnumerateSpatialCapabilityComponentTypesEXT شمارش کند -

  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT
  • قابلیت ردیابی شیء بدون یک مؤلفه برچسب معنایی بی‌معنی است. در حالی که این افزونه XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID XR_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) که از مرکز پایین اشیاء شروع می‌شود، نشان داده شده است.

جهت‌گیری سه‌بعدی ماوس با جهت‌گیری سه‌بعدی صفحه‌ی نگهدارنده هم‌راستا است. این محدوده‌ها، کیبورد و ماوس و پایه‌ی لپ‌تاپ را به‌طور کامل در بر می‌گیرند.

جهت‌یابی شیء فضایی XR اندروید

شکل ۳۴. نمونه‌ای از جهت‌گیری شیءگرا.

ساختار لیست کامپوننت برای پرس و جو از داده‌ها

ساختار 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_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

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۵-۰۶-۲۶ (کایل چن)

    • توضیحات اولیه افزونه
  • نسخه ۲، ۲۰۲۵-۱۲-۰۴ (کایل چن)

    • قالب مثال را به سبک جدید به‌روزرسانی کنید.