Table of Contents

Creating and configuring ar session

To use ar in unity, you need to first create and configure an ar session in the scene. this article introduces several main methods for creating and configuring ar sessions. generally, after successfully creating a session, you can see the following structure in the hierarchy view:

alt text

Before you start

Creating a session with default configuration

Right-click on a blank area in the hierarchy view, and use the menu easyar sense > [ ar function ] > ar session ([ function ] preset) to create a preset session. the session is pre-configured with frame source and frame filter components suitable for that function.

In scripts, you can use <xref:u:easyar.arsessionfactory.createsession(easyar.arsessionfactory.arsessionpreset,easyar.arsessionfactory.resources)?displayproperty=namewithtype> to create a session.

For example, using the menu easyar sense > image tracking > ar session (image tracking preset) creates a session for image tracking.

alt text

The corresponding script code is:

ARSessionFactory.CreateSession(ARSessionFactory.ARSessionPreset.ImageTracking);

Note that when using <xref:u:easyar.arsessionfactory.arsessionpreset.sparsespatialmapbuilder?displayproperty=namewithtype> and <xref:u:easyar.arsessionfactory.arsessionpreset.densespatialmapbuilder?displayproperty=namewithtype> presets, resource parameters need to be passed simultaneously. for example, the following code creates a session for sparse spatial mapping and specifies the point cloud material:

ARSessionFactory.CreateSession(ARSessionFactory.ARSessionPreset.SparseSpatialMapBuilder, new ARSessionFactory.Resources { SparseSpatialMapPointCloudMaterial = PointCloudMaterial });

If the script only runs in the editor, you can also use default editor resources:

ARSessionFactory.CreateSession(ARSessionFactory.ARSessionPreset.SparseSpatialMapBuilder, ARSessionFactory.Resources.EditorDefault());

The menu easyar sense > ar session (preset) > ** lists all available preset sessions for reference.

alt text

Note

multiple sessions running simultaneously in the same scene will conflict with each other, so at most one enabled (<xref:unityengine.gameobject.activeinhierarchy?displayproperty=namewithtype> == true) session can remain in the scene.

Adding components

the frame source and frame filter components of the session can be added and removed as needed after the session is created.

in the hierarchy view, select ar session (easyar) and right-click, then use the menu easyar sense > [ ar function ] > ** to add frame source and frame filter components suitable for that function.

in scripts, you can use <xref:u:easyar.arsessionfactory.addframesource``1(unityengine.gameobject,system.boolean)?displayproperty=namewithtype> to add a frame source component, or use <xref:u:easyar.arsessionfactory.addframefilter``1(unityengine.gameobject,easyar.arsessionfactory.resources)?displayproperty=namewithtype> to add a frame filter component.

for example, using the menu easyar sense > image tracking > frame filter : image tracker adds a new image tracker to the currently selected session.

alt text

the corresponding script code is:

ARSessionFactory.AddFrameFilter<ImageTrackerFrameFilter>(session);
Caution

adding components must be completed before assemble. after the session starts executing assemble or after assemble is completed, any addition or removal of components will cause the session to enter the <xref:u:easyar.arsession.sessionstate.broken> state and stop working.

note that when adding <xref:u:easyar.sparsespatialmapbuilderframefilter> and <xref:u:easyar.densespatialmapbuilderframefilter>, resource parameters need to be passed simultaneously. for example, the following code creates a <xref:u:easyar.sparsespatialmapbuilderframefilter> for sparse spatial mapping and specifies the point cloud material:

ARSessionFactory.AddFrameFilter<SparseSpatialMapBuilderFrameFilter>(session, new ARSessionFactory.Resources { SparseSpatialMapPointCloudMaterial = PointCloudMaterial })

if the script only runs in the editor, you can also use default editor resources:

ARSessionFactory.AddFrameFilter<SparseSpatialMapBuilderFrameFilter>(session, ARSessionFactory.Resources.EditorDefault());

after creating the frame filter, you can use <xref:u:easyar.arsessionfactory.setupframefilters(system.collections.generic.list{unityengine.gameobject},easyar.arsessionfactory.arsessionpreset)?displayproperty=namewithtype> to adjust the frame filter parameters according to the preset configuration.

for example, the following code adds a new image tracker to the session and configures it with the preset parameters of <xref:u:easyar.arsessionfactory.arsessionpreset.imagetrackingmotionfusion?displayproperty=namewithtype>.

var filter = ARSessionFactory.AddFrameFilter<ImageTrackerFrameFilter>(session);
ARSessionFactory.SetupFrameFilters(new() { filter }, ARSessionFactory.ARSessionPreset.ImageTrackingMotionFusion);

when creating with the menu, parameters cannot be adjusted according to presets; you need to configure them according to the specific component instructions after creation.

Removing components

to remove components from the session, you can select the corresponding component in the hierarchy view and press the delete key, or destroy (destroy) the corresponding object in the script.

Note

disabling (setactive(false)) the <xref:unityengine.gameobject> of the component has the same effect as removing the component.

for example, to remove an image tracker from the session, select image tracker and press the delete key.

alt text

Caution

removing components must be completed before assemble. after the session starts executing assemble or after assemble is completed, any addition or removal of components will cause the session to enter the <xref:u:easyar.arsession.sessionstate.broken> state and stop working.

Impact of component ordering

the order of the frame filter child nodes of the session has no effect on the session execution.

the order of the frame source child nodes of the session will affect the selection order of frame sources during the assemble process. only the first available frame source in transform order will be selected as the actual frame source of the session.

Note

the order of frame source nodes is only effective if modified before assemble. after assemble, adjusting the order will not affect the running result.

[optional] creating a session freely

if the default configured session does not meet the requirements, you can also create and configure the session freely as needed.

you can use the menu easyar sense > ar session (preset) > ar session (empty) to create an empty session without any frame source and frame filter components.

in scripts, you can use <xref:u:easyar.arsessionfactory.createsession?displayproperty=namewithtype> to achieve this.

ARSessionFactory.CreateSession();

then add appropriate frame source and frame filter components according to actual needs.

for example, if you need to create a session with sparse spatial mapping and dense spatial mapping functions, you can use the following code:

var session = ARSessionFactory.CreateSession();

var group = new GameObject("Frame Source Group");
group.transform.SetParent(session.transform, false);

ARSessionFactory.AddFrameSource<XREALFrameSource>(session);
ARSessionFactory.AddFrameSource<AREngineFrameSource>(session);
ARSessionFactory.AddFrameSource<ARCoreFrameSource>(session);
ARSessionFactory.AddFrameSource<ARCoreARFoundationFrameSource>(session);
ARSessionFactory.AddFrameSource<ARKitFrameSource>(session);
ARSessionFactory.AddFrameSource<ARKitARFoundationFrameSource>(session);
ARSessionFactory.AddFrameSource<VisionOSARKitFrameSource>(session);
ARSessionFactory.AddFrameSource<MotionTrackerFrameSource>(session);

List<GameObject> filters = new();
filters.Add(ARSessionFactory.AddFrameFilter<SparseSpatialMapBuilderFrameFilter>(session, resources));
filters.Add(ARSessionFactory.AddFrameFilter<DenseSpatialMapBuilderFrameFilter>(session, resources));

ARSessionFactory.SetupFrameFilters(filters, ARSessionFactory.ARSessionPreset.SparseSpatialMapBuilder);
ARSessionFactory.SetupFrameFilters(filters, ARSessionFactory.ARSessionPreset.DenseSpatialMapBuilder);

it will create a session structure like this:

alt text

Next steps

controlling operation

accessing components and results

component reference