Class ARSessionOrigin
An ARSessionOrigin
is the parent for an AR setup. It contains a Camera
and
any GameObject
s created from detected features, such as planes or point clouds.
Namespace: UnityEngine.XR.ARFoundation
Syntax
public class ARSessionOrigin : MonoBehaviour
Remarks
Session space vs Unity space
Since an AR device will be used to drive the Camera
's position and rotation,
you cannot directly place the Camera
at an arbitrary position in the Unity scene.
Instead, you should position the ARSessionOrigin
. This will make the Camera
(and any detected features) relative to that as a result.
It is important to keep the Camera
and detected features in the same space relative to
each other (otherwise, detected features like planes won't appear in the correct place relative
to the Camera
). We call the space relative to the AR device's starting position
"session space" or "device space". For example, when the AR session begins, the device may
report its position as (0, 0, 0). Detected features, such as planes, will be reported relative
to this starting position. The purpose of the ARSessionOrigin
is to convert the session space
to Unity world space.
To facilitate this, the ARSessionOrigin
creates a new GameObject
called "Trackables"
as a sibling of its Camera
. This should be the parent GameObject
for all
detected features.
At runtime, a typical scene graph might look like this:
- AR Session Origin
- Camera
- Trackables
- Detected plane 1
- Detected plane 2
- Point cloud
- etc...
You can access the "trackables" GameObject
with trackablesParent.
Note that the localPosition
and localRotation
of detected trackables
remain in real-world meters relative to the AR device's starting position and rotation.
Scale
If you want to scale the content rendered by the ARSessionOrigin
you should apply
the scale to the ARSessionOrigin
's transform. This is preferrable to scaling
the content directly as that can have undesirable side-effects. Physics and NavMeshes,
for example, do not perform well when scaled very small.
Properties
camera
The Camera
to associate with the AR device. It must be a child of this ARSessionOrigin
.
Declaration
public Camera camera { get; set; }
Property Value
Type | Description |
---|---|
Camera |
Remarks
The Camera
should update its position and rotation according to the AR device.
This is typically accomplished by adding a TrackedPoseDriver
component to the
Camera
.
trackablesParent
The parent Transform
for all "trackables", e.g., planes and feature points.
Declaration
public Transform trackablesParent { get; }
Property Value
Type | Description |
---|---|
Transform |
Methods
MakeContentAppearAt(Transform, Quaternion)
Makes content
appear to have orientation rotation
relative to the Camera
.
Declaration
public void MakeContentAppearAt(Transform content, Quaternion rotation)
Parameters
Type | Name | Description |
---|---|---|
Transform | content | The |
Quaternion | rotation | The rotation the content should appear to be in, relative
to the |
Remarks
This method does not actually change the Transform
of content; instead,
it updates the ARSessionOrigin
's Transform
such that it appears the content
is in the requested orientation.
MakeContentAppearAt(Transform, Vector3)
Makes content
appear to be placed at position
.
Declaration
public void MakeContentAppearAt(Transform content, Vector3 position)
Parameters
Type | Name | Description |
---|---|---|
Transform | content | The |
Vector3 | position | The position you wish the content to appear at. This could be a position on a detected plane, for example. |
Remarks
This method does not actually change the Transform
of content; instead,
it updates the ARSessionOrigin
's Transform
such that it appears the content
is now at the given position.
MakeContentAppearAt(Transform, Vector3, Quaternion)
Makes content
appear to be placed at position
with orientation rotation
.
Declaration
public void MakeContentAppearAt(Transform content, Vector3 position, Quaternion rotation)
Parameters
Type | Name | Description |
---|---|---|
Transform | content | The |
Vector3 | position | The position you wish the content to appear at. This could be a position on a detected plane, for example. |
Quaternion | rotation | The rotation the content should appear to be in, relative
to the |
Remarks
This method does not actually change the Transform
of content; instead,
it updates the ARSessionOrigin
's Transform
such that it appears the content
is now at the given position and rotation. This is useful for placing AR
content onto surfaces when the content itself cannot be moved at runtime.
For example, if your content includes terrain or a nav mesh, then it cannot
be moved or rotated dynamically.