Develop

Select your platform

Use OVRSceneManager (deprecated)

Updated: Jan 22, 2025

OVRSceneManager Deprecation

As of v65, OVRSceneManager is deprecated. New features will be delivered through MR Utility Kit.

Refer to the following as guidance on which APIs to use:

New projects:

Use MR Utility Kit for new development

Existing projects:

To access the latest features, migrate yourexisting projects to MR Utility Kit.

If you don’t require the latest features or tools provided by MR Utility Kit, continue using OVRSceneManager.

Introduction

This topic shows you how to access the Scene Model through the simple-to-use Unity components OVRSceneManager and OVRSceneAnchor.

How OVRSceneManager works

The OVRSceneManager Unity component is the easiest way to access the Scene Model. It focuses on the most common use case: spawning virtual objects that the developer has provided for Scene Anchors of a user’s environment and abstracting away direct Scene data access.

To load an existing Scene Model, call OVRSceneManager.LoadSceneModel(). This call initiates the loading process, which can take multiple frames to complete. As part of the loading process, the Scene Model will instantiate prefabs for all available Scene Anchors. Two events provide the result:

SceneModelLoadedSuccessfully: Indicates that the OVRSceneManager has successfully loaded a Scene Model.

NoSceneModelToLoad: Indicates there is no Scene Model available for the OVRSceneManager to load, for example, if the user has not yet performed Space Setup, or the user denied the Spatial Data Permission

This code sample shows how to subscribe to the events and call LoadSceneModel (note that events should be unsubscribed):

void Load()
{
    var sceneManager = FindObjectOfType<OVRSceneManager>();

    sceneManager.SceneModelLoadedSuccessfully += OnLoaded;
    sceneManager.NoSceneModelToLoad += OnNotLoaded;
    sceneManager.LoadSceneModel();
}
void OnLoaded() => Debug.Log("Success");
void OnNotLoaded() => Debug.Log("Failed");

It is also possible to query whether the Scene Model contains a certain anchor classification by calling DoesRoomSetupExist(). This will not load any anchors from Scene Model and therefore not spawn any Unity game objects. This method will always return false if no Scene Model has been captured, or if the user has not granted the runtime permission.

Requesting Space Setup

An app can trigger the system’s space setup process by calling OVRSceneManager.RequestSceneCapture(). Requesting Space Setup will pause the app, launch space setup, and then resume the app when the user completes (or cancels) the setup process. Two events provide the result:

SceneCaptureReturnedWithoutError: Indicates space setup completed. Note that this includes the case where the user cancels space setup.

UnexpectedErrorWithSceneCapture: Indicates something went wrong during space setup.

Automatically loading Scene Model with OVRSceneModelLoader

To facilitate loading the Scene Model, requesting Space Setup, and handling the results, you have an extendable utility component: OVRSceneModelLoader.

The OVRSceneModelLoader component subscribes to the events provided by the OVRSceneManager.RequestSceneCapture and performs an appropriate action in response to each event. It offers reasonable default behaviors, but it is expected that developers create derived classes to override and customize these behaviors.

The default loader checks whether the Scene Model contains any anchors. If not, the loader triggers a Space Setup once. If a user fails to complete Space Setup, then a manual call to RequestSceneCapture is required by the application.

The overrideable methods are:

OnStart: The system invokes this method at the start of your application (just after Unity’s Start() method). The default implementation attempts to load an existing Scene model.

OnSceneModelLoadedSuccessfully: This method indicates the Scene Model has finished loading. The default implementation does nothing.

OnNoSceneModelToLoad: This method indicates there was no Scene Model to load, meaning a request to OVRSceneManager.LoadSceneModel concluded, but no captured scene exists or user denied the Spatial Permission. The default implementation requests Space Setup from the OVRSceneManager.

OnSceneCaptureReturnedWithoutError: A request to capture the Scene succeeded without error. The default implementation loads the Scene Model from the OVRSceneManager.

OnUnexpectedErrorWithSceneCapture: A request to capture the Scene failed. The default implementation does nothing.

Using the OVRSceneManager prefab

The OVRSceneManager and OVRSceneModelLoader components are available through a prefab, also called OVRSceneManager.

Search for the OVRSceneManager prefab in the Project tab, and drag it into your Unity scene.

Create prefabs for the plane and volume prefab.

The plane prefab must have the OVRSceneAnchor and OVRScenePlane components. Create a Unity Plane object under the prefab’s root node with Y rotation of 180 degrees to have a plane placed in the right location.

The volume prefab must have the OVRSceneAnchor and OVRSceneVolume components. Create a Unity Cube object under the prefab’s root node with a Z position of -0.5 to have a cube placed in the right location (the anchor origin is at the top of the cube).

Drag the created prefabs on the Plane Prefab and Volume Prefab properties of the OVRSceneManager.

If you want to instead spawn objects by classification type, use Prefab Overrides. This option can be used in conjunction with the Plane Prefab and Volume Prefab modes, but takes precedence.

Use Active Rooms Only to only load the rooms the user is currently in. As rooms may overlap depending on how they were scanned, multiple rooms may be loaded depending on the user’s location.

OVRSceneAnchor

The OVRSceneAnchor component represents the Scene Anchors of the Scene Model. It contains multiple components to provide the data, each of which has a duplicate Unity component type (for example, the Scene Bounded2D component is represented by the OVRScenePlane Unity component).

OVRSceneAnchors are created by the OVRSceneManager and cannot be created by the user. The OVRSceneManager is responsible to periodically updating the location of every anchor through the parameter MaxSceneAnchorUpdatesPerFrame. In order to do this, OVRSceneManager keeps a reference to each spawned OVRSceneAnchor in the scene.

In order to access all of the spawned OVRSceneAnchors, wait until the Scene Model has been loaded, and then use the static helper method OVRSceneAnchor.GetSceneAnchors(). It is recommended to use this method to find specific anchors (such as rooms), instead of using Unity’s FindObjectsOfType<T>().

Further scene model Unity components

OVRSceneManager spawns OVRSceneAnchors when the Scene Model has been loaded, and adds the relevant Unity components that provide further data of the Scene Anchor. For example, when spawning a wall, the OVRSceneManager will spawn the supplied Plane Prefab object (with type OVRSceneAnchor) and add the components OVRScenePlane and OVRSemanticClassification if they are not present.

OVRSceneRoom

OVRSceneRoom represents the anchors that are part of the structures that make up a room, providing direct access to the created Unity game objects for the ceiling, floor and walls. All invisible wall faces are also classified as wall faces, and are accessible in the OVRSceneRoom’s walls. The order of the walls is the order in which the user drew them. To access the wall shape as a closed polyline, use the Boundary on the floor’s OVRScenePlane.

When OVRSceneManager instantiates user-supplied prefabs for scene anchors, it creates a hierarchy which uses OVRSceneRoom as the container game object. OVRSceneRooms can be spawned as top-level game objects, or parented to another game object using OVRSceneManager.InitialAnchorParent. You can iterate over scene anchors or scene rooms using the Unity Transform.

OVRScenePlane

A scene plane (OVRScenePlane) represents the two-dimensional bounds of a scene anchor. The system automatically adds a scene plane to any scene anchor with a two-dimensional boundary. For example, floors, ceilings, and walls have an OVRScenePlane component, as do surfaces on things like tables and couches. OVRScenePlanes may optionally include a Boundary: floor scene anchors have a boundary which represents the closed polyline of the walls.

When you instantiate a scene plane, the system sets the localScale of each direct child transform of the prefab according to the 2D extents of the plane. The localScale is set in meters. Setting the localScale enables things like stretching a wall prefab to the actual dimensions of the wall. If an offset exists between the pivot and center of the plane, child transforms may also have their localPosition modified.

OVRScenePlaneMeshFilter

Each scene plane has a 2D boundary, accessible via the OVRScenePlaneMeshFilter. This component generates a planar mesh from the 2D boundary, which you can use for rendering, physics, or any other purpose.

In the case of an OVRScenePlane which has the semantic classification for FLOOR, the Boundary represents the closed polyline of the walls.

OVRSceneVolume

A scene volume (OVRSceneVolume) represents the three-dimensional bounds of a scene anchor. The system automatically adds a scene volume to any scene anchor with 3D boundary extents. You can see examples of this functionality in the user-defined volumes labeled OTHER in space setup.

When you instantiate a scene volume, the system sets the localScale of each direct child transform of the prefab according to the 3D extents of the volume. The localScale is set in meters. During this process, the system will stretch prefabs to the dimensions of the volume. If an offset exists between the pivot and the center point of the top face of the volume, child transforms may also have their localPosition modified.

OVRSceneVolumeMeshFilter

A scene anchor may optionally have a triangle mesh representation, accessible via the OVRSceneVolumeMeshFilter. This component populates a Unity MeshFilter component with a Mesh on startup, and optionally bakes a MeshCollider component if it is attached (using the default cooking options).

Creating the mesh and baking the collider are performed using the Unity job system in order to avoid blocking the main thread due to a large number of triangles. Use the property IsCompleted in order to know when the process has finished.

Currently, only scene anchors with a semantic classification of GLOBAL_MESH contain a OVRSceneVolumeMeshFilter.

OVRSemanticClassification

A scene anchor may have one or more string labels that provide additional semantic information describing the anchor’s object type, for example, COUCH or WALL_FACE. The system automatically adds OVRSemanticClassification to scene anchors that have semantic labels.

OVRSceneObjectTransformType

If you want more control over how child objects within a prefab are scaled and offset by OVRScenePlane and OVRSceneVolume, add the OVRSceneObjectTransformType component on the child objects to choose who applies the transform.

When OVRScenePlane and OVRSceneVolume set the localScale and localPosition of the child objects, they do so in the following order: firstly, by checking whether OVRSceneObjectTransformType is defined on the child; then by seeing whether the OVRSceneVolume is modifying the scale/offset; and lastly, by looking at the OVRScenePlane values for scale and offset.

Anchor pivots

2D planes and 3D volumes use the following pivot rules for each scene anchor. Note that in the design-time scene descriptions below, you place the prefabs at +90 degrees to accommodate the default OpenXR coordinate system (a Cartesian right-handed coordinate system). For more information, see the OpenXR Spec section 2.18, Coordinate System.

Plane pivots

A 2D plane’s pivot is at the center of the plane, with +Z pointing in the direction of the plane’s normal. So, for example, an OVRScenePlane representing a floor will have its +Z pointing up. In the following graphics, the X vector is red, the Y vector is green, and the Z vector is blue.

Walls are oriented such that +Z points out from the wall and +Y is always up.

Volume pivots

The pivot for an OVRSceneVolume is in the middle of its top surface. Since the normal of the top surface points upward, +Z is also up in this case.

Composite

Some objects are represented by both a plane and a volume, such as tables and couches. The plane represents the flat area of the object, such as a couch seat, while the volume corresponds to the bounding box which contains the entire object. The pivot is always at the center of the plane, while an offset is used to capture the difference between the pivot of the plane and pivot of the volume.

In the case of a table, the plane is at the top face of the volume, resulting in an offset of 0. In the case of a couch, the plane is within the volume, resulting in a non-zero offset for the volume. In this example image, the offset is the difference between the plane pivot axes and the sphere at the center of the volume’s top face.

Scene Mesh

The Scene Mesh is a low-fidelity, high-coverage artifact which describes the boundary between free and occupied space in a room. It is generated automatically during the space setup experience, and available for applications to query using the OVRSceneManager. If the space setup falls back to the manual mode, then a Scene Mesh will not be in the Scene Model.

In order to spawn an object for the Scene Mesh, you must use the Prefab Overrides. This is because it is considered neither as a Plane Prefab, nor as a Volume Prefab. Select the label GLOBAL_MESH and add your prefab.

Accessing the mesh data is done through the OVRSceneVolumeMeshFilter, which populates a Unity MeshFilter at runtime with a mesh retrieved from the system. Optionally, a MeshRenderer needs to be added to visualize this mesh, and a MeshCollider for physics and collisions.