Class ARSessionOrigin

An ARSessionOrigin is the parent for an AR setup. It contains a Camera and any GameObjects created from detected features, such as planes or point clouds.

Inheritance

System.Object

ARSessionOrigin

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 Rig
• 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 unintended side-effects. The ARSessionOrigin has a convenience property for this: scale.

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.

scale

The scale to apply to this ARSessionOrigin. Larger values make the virtual content appear smaller. For example, a value of 10 makes the virtual content appear 10 times smaller.

Declaration

public float scale { get; set; }

Property Value

Type	Description
System.Single

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 Transform of the content you wish to affect.
Quaternion	rotation	The rotation the content should appear to be in, relative to the Camera.

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 Transform of the content you wish to affect.
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 Transform of the content you wish to affect.
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 Camera.

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.

Raycast(Ray, List<ARRaycastHit>, TrackableType, Single)

Cast a Ray against trackables, i.e., detected features such as planes.

Declaration

public bool Raycast(Ray ray, List<ARRaycastHit> hitResults, TrackableType trackableTypeMask = null, float pointCloudRaycastAngleInDegrees = 5F)

Parameters

Type	Name	Description
Ray	ray	The Ray, in Unity world space, to cast.
List<ARRaycastHit>	hitResults	Contents are replaced with the raycast results, if successful.
TrackableType	trackableTypeMask	(Optional) The types of trackables to cast against.
System.Single	pointCloudRaycastAngleInDegrees	(Optional) Used to define the angle of the cone to use when raycasting against feature points.

Returns

Type	Description
System.Boolean	True if the raycast hit a trackable in the trackableTypeMask

Raycast(Vector3, List<ARRaycastHit>, TrackableType)

Cast a ray from a point in screen space against trackables, i.e., detected features such as planes.

Declaration

public bool Raycast(Vector3 screenPoint, List<ARRaycastHit> hitResults, TrackableType trackableTypeMask = null)

Parameters

Type	Name	Description
Vector3	screenPoint	The point, in device screen pixels, from which to cast.
List<ARRaycastHit>	hitResults	Contents are replaced with the raycast results, if successful.
TrackableType	trackableTypeMask	(Optional) The types of trackables to cast against.

Returns

Type	Description
System.Boolean	True if the raycast hit a trackable in the trackableTypeMask