OpenXRFbSpatialEntity
Inherits: RefCounted
Represents a spatial entity in Meta's Scene Understanding and Spatial Anchor APIs.
Description
Represents a spatial entity in Meta's Scene Understanding and Spatial Anchor APIs.
A spatial entity can be a spatial anchor created by the application or an element of the real-world environment (sometimes called a "scene anchor"), such as walls, floor, ceiling, furniture, or even a mesh created using the headset's depth sensor, as a result of the user going through the scene capture process.
Properties
Dictionary |
|
|
StringName |
|
Methods
Node3D |
create_collision_shape ( ) const |
MeshInstance3D |
create_mesh_instance ( ) const |
create_spatial_anchor ( Transform3D transform ) static |
|
void |
destroy ( ) |
void |
erase_from_storage ( StorageLocation location=0 ) |
PackedVector2Array |
get_boundary_2d ( ) const |
Rect2 |
get_bounding_box_2d ( ) const |
AABB |
get_bounding_box_3d ( ) const |
Array |
get_contained_uuids ( ) const |
Dictionary |
get_room_layout ( ) const |
PackedStringArray |
get_semantic_labels ( ) const |
Array |
get_supported_components ( ) const |
Array |
get_triangle_mesh ( ) const |
bool |
is_component_enabled ( ComponentType component ) const |
bool |
is_component_supported ( ComponentType component ) const |
bool |
is_tracked ( ) const |
void |
save_to_storage ( StorageLocation location=0 ) |
void |
set_component_enabled ( ComponentType component, bool enabled ) |
void |
share_with_users ( OpenXRFbSpatialEntityUser[] users ) |
void |
track ( ) |
void |
untrack ( ) |
Signals
openxr_fb_spatial_entity_created ( bool succeeded )
Emitted when the operation to create a spatial entity is completed. See create_spatial_anchor.
openxr_fb_spatial_entity_erased ( bool succeeded, int location )
Emitted when the operation to erase a spatial entity from storage is completed. See erase_from_storage.
openxr_fb_spatial_entity_saved ( bool succeeded, int location )
Emitted when the operation to save a spatial entity to storage is completed. See save_to_storage.
openxr_fb_spatial_entity_set_component_enabled_completed ( bool succeeded, int component, bool enabled )
Emitted when the operation to enable or disable a component on the spatial entity is completed. See set_component_enabled.
Emitted when the operation to share a spatial entity is completed. See share_with_users.
Enumerations
enum StorageLocation:
StorageLocation STORAGE_LOCAL = 0
Storage on the local headset.
StorageLocation STORAGE_CLOUD = 1
Storage in the cloud.
enum ComponentType:
ComponentType COMPONENT_TYPE_LOCATABLE = 0
The spatial entity's location can be tracked. See track.
ComponentType COMPONENT_TYPE_STORABLE = 1
The spatial entity can be stored. See save_to_storage and erase_from_storage.
ComponentType COMPONENT_TYPE_SHARABLE = 2
The spatial entity can be shared with other users. See share_with_users.
ComponentType COMPONENT_TYPE_BOUNDED_2D = 3
The spatial entity has 2D boundary data. See get_bounding_box_2d and get_boundary_2d.
ComponentType COMPONENT_TYPE_BOUNDED_3D = 4
The spatial entity has 3D boundary data. See get_bounding_box_3d.
ComponentType COMPONENT_TYPE_SEMANTIC_LABELS = 5
The spatial entity has semantic labels. See get_semantic_labels.
ComponentType COMPONENT_TYPE_ROOM_LAYOUT = 6
The spatial entity has room layout data. See get_room_layout.
ComponentType COMPONENT_TYPE_CONTAINER = 7
The spatial entity contains other spatial entities. See get_contained_uuids.
ComponentType COMPONENT_TYPE_TRIANGLE_MESH = 8
The spatial entity has triangle mesh data. See get_triangle_mesh.
Property Descriptions
Dictionary custom_data = {}
void set_custom_data ( Dictionary value )
Dictionary get_custom_data ( )
Game or application-specific data about the spatial entity.
StringName uuid = &""
StringName get_uuid ( )
The UUID of the spatial entity.
Method Descriptions
Node3D create_collision_shape ( ) const
Creates a CollisionShape3D node with the shape and position of the spatial entity, if it has that data. Otherwise, it will return null.
The spatial entity must have one of the components COMPONENT_TYPE_TRIANGLE_MESH, COMPONENT_TYPE_BOUNDED_3D, or COMPONENT_TYPE_BOUNDED_2D enabled, which can be checked by calling is_component_enabled.
The underlying data can be accessed via get_triangle_mesh, get_bounding_box_3d, or get_bounding_box_2d.
MeshInstance3D create_mesh_instance ( ) const
Creates a MeshInstance3D node with the shape and position of the spatial entity, if it has that data. Otherwise, it will return null.
The spatial entity must have one of the compenents COMPONENT_TYPE_TRIANGLE_MESH, COMPONENT_TYPE_BOUNDED_3D, or COMPONENT_TYPE_BOUNDED_2D enabled, which can be checked by calling is_component_enabled.
The underlying data can be accessed via get_triangle_mesh, get_bounding_box_3d, or get_bounding_box_2d.
OpenXRFbSpatialEntity create_spatial_anchor ( Transform3D transform ) static
Creates a new spatial anchor at the given position (relative to the current XROrigin3D).
The OpenXRFbSpatialEntity object will be returned immediately, but anchor creation is asynchronous, and so the anchor won't really exist until after openxr_fb_spatial_entity_created is emitted with arguments indicating success.
Rather than using this method directly, it's recommended to use an :ref:`OpenXRFbSpatialAnchorManager<class_openxrfbspatialanchormanager>` node instead! It can help with many of the follow-up steps necessary for using spatial anchors in practice.
void destroy ( )
Untracks and destroys a spatial entity, such that it will no longer be tracked by XRServer or the headset.
This does not remove the entity from storage, which must be done via erase_from_storage.
void erase_from_storage ( StorageLocation location=0 )
Removes the spatial entity from the given storage location.
The component COMPONENT_TYPE_STORABLE must be enabled, which can be checked by calling is_component_enabled, or set by calling set_component_enabled.
This is an asynchronous operation - the openxr_fb_spatial_entity_erased signal will be emitted when completed with an argument indicating if it was successful or not.
PackedVector2Array get_boundary_2d ( ) const
Gets the 2D boundary of the spatial entity as an array of Vector2s.
The component COMPONENT_TYPE_BOUNDED_2D must be enabled, which can be checked by calling is_component_enabled.
Use create_mesh_instance or create_collision_shape to create a node using this data.
Rect2 get_bounding_box_2d ( ) const
Gets the 2D boundary of the spatial entity as a Rect2.
The component COMPONENT_TYPE_BOUNDED_2D must be enabled, which can be checked by calling is_component_enabled.
Use create_mesh_instance or create_collision_shape to create a node using this data.
AABB get_bounding_box_3d ( ) const
Gets the 3D boundary of the spatial entity as an AABB.
The component COMPONENT_TYPE_BOUNDED_3D must be enabled, which can be checked by calling is_component_enabled.
Use create_mesh_instance or create_collision_shape to create a node using this data.
Array get_contained_uuids ( ) const
Gets an array of the UUIDs of the spatial entities that are contained in this spatial entity.
The component COMPONENT_TYPE_CONTAINER must be enabled, which can be checked by calling is_component_enabled.
The actual OpenXRFbSpatialEntity objects can be obtained using OpenXRFbSpatialEntityQuery.
Dictionary get_room_layout ( ) const
Gets a Dictionary containing the following keys:
floor(StringName): the UUID of the spatial entity representing the floor.ceiling(StringName): the UUID of the spatial entity representing the ceiling.walls(Array of StringNames): the UUIDs of the spatial entities representing the walls.
The component COMPONENT_TYPE_ROOM_LAYOUT must be enabled, which can be checked by calling is_component_enabled.
The actual OpenXRFbSpatialEntity objects can be obtained using OpenXRFbSpatialEntityQuery.
PackedStringArray get_semantic_labels ( ) const
Gets an array of the semantic labels used by this spatial entity.
The component COMPONENT_TYPE_SEMANTIC_LABELS must be enabled, which can be checked by calling is_component_enabled.
Array get_supported_components ( ) const
Gets an array of ComponentTypes where are supported by this spatial entity.
Array get_triangle_mesh ( ) const
Gets an array in the same format as used by ArrayMesh, representing a triangle mesh covering the spatial entity.
The component COMPONENT_TYPE_TRIANGLE_MESH must be enabled, which can be checked by calling is_component_enabled.
Use create_mesh_instance or create_collision_shape to create a node using this data.
bool is_component_enabled ( ComponentType component ) const
Checks if the given component is enabled on this spatial entity.
bool is_component_supported ( ComponentType component ) const
Checks if the given component is supported by this spatial entity.
bool is_tracked ( ) const
Checks if this spatial entity is being tracked by XRServer.
See track for more information.
void save_to_storage ( StorageLocation location=0 )
Saves the spatial entity in the given storage location.
The component COMPONENT_TYPE_STORABLE must be enabled, which can be checked by calling is_component_enabled, or set by calling set_component_enabled.
This is an asynchronous operation - the openxr_fb_spatial_entity_saved signal will be emitted when completed with an argument indicating if it was successful or not.
Note: OpenXRFbSpatialEntityBatch can be used to save multiple spatial entities in a single operation.
void set_component_enabled ( ComponentType component, bool enabled )
Sets a particular component as enabled or disabled on this spatial entity.
You can check if the given component is supported by calling is_component_supported, however, not all component types can be enabled or disabled even if supported.
This is an asynchronous operation - the openxr_fb_spatial_entity_set_component_enabled_completed signal will be emitted when completed with an argument indicating if it was successful or not.
Shares this spatial entity with the given users.
The component COMPONENT_TYPE_SHARABLE must be enabled, which can be checked by calling is_component_enabled, or set by calling set_component_enabled.
The spatial entity must have already been saved to the cloud, using save_to_storage.
This is an asynchronous operation - the openxr_fb_spatial_entity_shared signal will be emitted when completed with an argument indicating if it was successful or not.
Note: OpenXRFbSpatialEntityBatch can be used to share multiple spatial entities in a single operation.
void track ( )
Starts tracking this spatial entity on XRServer.
The component COMPONENT_TYPE_LOCATABLE must be enabled, which can be checked by calling is_component_enabled, or set by calling set_component_enabled.
Once a spatial entity is being tracked, an XRAnchor3D node can be created with its XRAnchor3D.tracker property set to the uuid of this spatial entity, and it will be moved to the correct position based on the headset's tracking.
Use untrack to stop tracking a spatial anchor on XRServer.
void untrack ( )
Stops tracking this spatial entity on XRServer.
See track for more information.