Most visited

Recently visited

ARScene

public class ARScene
extends Scene

java.lang.Object
   ↳ com.viro.core.Scene
     ↳ com.viro.core.ARScene


ARScene blends virtual 3D content with the device camera's view of the real world. Similar to a normal Scene, an ARScene contains a hierarchy of Node objects representing the virtual 3D world. Behind these objects the camera's live video feed is rendered. ARScene ensures the two worlds -- real and virtual -- stay in sync with a unified coordinate system.

There are two ways to add virtual content to the ARScene. The first is to simply place content manually. The origin of the coordinate system is the initial position of the user, and the scale is meters. To add content you only need to set the position of the Node within this coordinate system, and add it to the scene graph.

The second way to add virtual content is to use ARAnchor. ARAnchors represent features detected in the real-world. You can associate (or "anchor") your content to these features by adding your content to the ARNode that corresponds to each detected ARAnchor. To do this, implement the ARScene ARScene.Listener. The ARScene.Listener callbacks are invoked whenever ARAnchors are found (or updated, or removed) in the real-world.

For a higher level guide on building AR in Viro, refer to the Augmented Reality Guide.

Summary

Nested classes

class ARScene.ARSceneBuilder<R extends ARScene, B extends ARSceneBuilder<R, B>>

ARSceneBuilder for building ARScene

interface ARScene.CloudAnchorHostListener

Callback interface for responding to anchor hosting requests. 

interface ARScene.CloudAnchorResolveListener

Callback interface for responding to anchor resolution requests. 

interface ARScene.Listener

Callback interface for ARScene events. 

enum ARScene.TrackingState

Values representing position tracking quality. 

enum ARScene.TrackingStateReason

Diagnoses to explain cases where we have limited position tracking quality in AR. 

Public constructors

ARScene()

Construct a new ARScene.

Public methods

void addARImageTarget(ARImageTarget target)

Add an ARImageTarget to the Scene.

static ARSceneBuilder<? extends Scene, ? extends SceneBuilder> builder()

Creates a builder for building complex ARScene objects.

ARNode createAnchoredNode(Vector position, Quaternion quaternion)

Create an ARNode that will be anchored to the given real-world position and rotation.

ARNode createAnchoredNode(Vector position)

Create an ARNode that will be anchored to the given real-world position.

void displayPointCloud(boolean displayPointCloud)

Set to true to display a point cloud representing the rough feature points that the AR tracking system is detecting.

void dispose()

Release native resources associated with this ARScene.

Vector getEstimatedAmbientLightColor()

Get the estimated color of the lighting in the real-world, as an RGB vector with values ranging from 0 to 1.

float getEstimatedAmbientLightIntensity()

Get the estimated intensity of the lighting in the real-world, in lumens.

void hostCloudAnchor(ARAnchor anchor, ARScene.CloudAnchorHostListener callback)

Host the given ARAnchor to the cloud so it can be shared with other users.

void removeARImageTarget(ARImageTarget target)

Remove an ARImageTarget from the Scene.

void resetPointCloudSurface()

Reset the point cloud surface to the default values.

void resolveCloudAnchor(String cloudAnchorId, ARScene.CloudAnchorResolveListener callback)

Resolve the ARAnchor with the given cloud identifier.

void setListener(ARScene.Listener listener)

Set the ARScene.Listener to use for responding to AR events.

void setPointCloudMaxPoints(int maxPoints)

Set the maximum number of points to render when drawing the AR point cloud.

void setPointCloudSurface(Surface surface)

Set the Surface that should be used to render each point in the rendered AR point cloud.

void setPointCloudSurfaceScale(Vector scale)

Set the scale factor to use when rendering each point in the AR point cloud.

void setPointCloudUpdateListener(PointCloudUpdateListener listener)

Set the PointCloudUpdateListener to use for receiving point cloud updates.

Public constructors

ARScene

ARScene ()

Construct a new ARScene.

Public methods

addARImageTarget

void addARImageTarget (ARImageTarget target)

Add an ARImageTarget to the Scene. Once added, Viro will search for this reference image in the real-world, and alert you when an instance is found by invoking onAnchorFound(ARAnchor, ARNode) with an ARImageAnchor anchor.

Parameters
target ARImageTarget: The reference ARImageTarget you want to find in the real-world.

See also:

builder

ARSceneBuilder<? extends Scene, ? extends SceneBuilder> builder ()

Creates a builder for building complex ARScene objects.

Returns
ARSceneBuilder<? extends Scene, ? extends SceneBuilder> ARScene.ARSceneBuilder object.

createAnchoredNode

ARNode createAnchoredNode (Vector position, 
                Quaternion quaternion)

Create an ARNode that will be anchored to the given real-world position and rotation. Attaching objects to an anchored node is recommended in AR, because the world coordinate system used by the underlying tracking technology may not be stable. By using an ARNode, you ensure that said node is continually tracked, maintaining its position in the real world. Normal Node objects can be added as children to the ARNode, and they too will maintain their position relative to the real-world.

If AR tracking is limited, this method will return null.

Note that the returned ARNode is automatically added to the Scene, and will be continually updated to stay in the sync with its underlying anchor as the anchor's properties, orientation, or position change.

When finished with this ARNode, you must call detach() to remove it from the system. If you do not detach the ARNode, it will continue to receive tracking updates from the AR subsystem, adversely impacting performance.

Parameters
position Vector

quaternion Quaternion

Returns
ARNode New ARNode anchored to the given position, with the given rotation. Returns null if AR tracking is currently limited.

createAnchoredNode

ARNode createAnchoredNode (Vector position)

Create an ARNode that will be anchored to the given real-world position. Attaching objects to an anchored node is recommended in AR, because the world coordinate system used by the underlying tracking technology may not be stable. By using an ARNode, you ensure that said node is continually tracked, maintaining its position in the real world. Normal Node objects can be added as children to the ARNode, and they too will maintain their position relative to the real-world.

If AR tracking is limited, this method will return null.

The returned ARNode is automatically added to the Scene, and will be continually updated to stay in the sync with its underlying anchor as the anchor's properties, orientation, or position change.

When finished with this ARNode, you must call detach() to remove it from the system. If you do not detach the ARNode, it will continue to receive tracking updates from the AR subsystem, adversely impacting performance.

Parameters
position Vector

Returns
ARNode New ARNode anchored to the given position. Returns null if AR tracking is currently limited.

displayPointCloud

void displayPointCloud (boolean displayPointCloud)

Set to true to display a point cloud representing the rough feature points that the AR tracking system is detecting. This is useful for debugging and analysis, but can also be used for rendering effects.

Parameters
displayPointCloud boolean: True to display the point cloud, false to remove.

dispose

void dispose ()

Release native resources associated with this ARScene.

getEstimatedAmbientLightColor

Vector getEstimatedAmbientLightColor ()

Get the estimated color of the lighting in the real-world, as an RGB vector with values ranging from 0 to 1. The returned color can be applied to an AmbientLight to make the ambient lighting of your virtual objects closely resemble the ambient lighting detected in the real-world.

Returns
Vector The estimated color of the ambient light, in an RGB [0,1] Vector.

getEstimatedAmbientLightIntensity

float getEstimatedAmbientLightIntensity ()

Get the estimated intensity of the lighting in the real-world, in lumens. This value can be applied to an AmbientLight to make the ambient lighting of your virtual objects closely resemble the ambient lighting detected in the real-world.

Returns
float The estimated intensity of the ambient light, in lumens.

hostCloudAnchor

void hostCloudAnchor (ARAnchor anchor, 
                ARScene.CloudAnchorHostListener callback)

Host the given ARAnchor to the cloud so it can be shared with other users. The given callback will be invoked if the operation succeeds or fails.

The ARAnchor received in the callback upon a successful hosting will contain a cloud anchor ID, accessible via getCloudAnchorId(). Other clients can use this ID with resolveCloudAnchor(String, CloudAnchorResolveListener) to pull down the hosted anchor, creating a shared AR experience.

If the operation fails, an error message will be sent to the callback.

Note that to use cloud anchors, you must have a Google AR API key in the application section of your AndroidManifest. This is of the form:

 <meta-data android:name="com.google.android.ar.API_KEY"
            android:value="Your-API-Key" />
 

Parameters
anchor ARAnchor: The ARAnchor to host. You can retrieve an ARAnchor to host either from the ARScene ARScene.Listener, in response to detected planes, images, or other real-world features, or from any ARNode through getAnchor().

callback ARScene.CloudAnchorHostListener: The callback to invoke on success or failure.

removeARImageTarget

void removeARImageTarget (ARImageTarget target)

Remove an ARImageTarget from the Scene. Viro will stop searching for this image.

Parameters
target ARImageTarget: The target to stop searching for in the real-world.

resetPointCloudSurface

void resetPointCloudSurface ()

Reset the point cloud surface to the default values. The point cloud surface is the Surface that will be used to render each point in the point cloud.

resolveCloudAnchor

void resolveCloudAnchor (String cloudAnchorId, 
                ARScene.CloudAnchorResolveListener callback)

Resolve the ARAnchor with the given cloud identifier. If the given anchor is successfully found in the cloud and synchronized with this client, it will be returned in the provided callback. The ARAnchor received will be associated with a new ARNode, to which you can add virtual content. That content will remain synchronized with the location and pose of the cloud anchor.

If the operation fails, an error message will be sent to the callback.

Note that to use cloud anchors, you must have a Google AR API key in the application section of your AndroidManifest. This is of the form:

 <meta-data android:name="com.google.android.ar.API_KEY"
            android:value="Your-API-Key" />
 

Parameters
cloudAnchorId String: The unique cloud identifier of the anchor to resolve. This ID can be retrieved from getCloudAnchorId(), but some form of remote data transmission is typically required to move that ID from client to client.

callback ARScene.CloudAnchorResolveListener: The callback to invoke on success or failure.

setListener

void setListener (ARScene.Listener listener)

Set the ARScene.Listener to use for responding to AR events. This enables your application to receive ARAnchor and ARNode objects as they are detected by the AR tracking system.

Parameters
listener ARScene.Listener: The ARScene.Listener to use for this ARScene.

setPointCloudMaxPoints

void setPointCloudMaxPoints (int maxPoints)

Set the maximum number of points to render when drawing the AR point cloud.

Parameters
maxPoints int: The maximum number of points to render.

setPointCloudSurface

void setPointCloudSurface (Surface surface)

Set the Surface that should be used to render each point in the rendered AR point cloud. This allows you to customize the appearance of the cloud with a textured (or otherwise colored) Surface.

Parameters
surface Surface: The Surface to use for representing each point in the cloud.

setPointCloudSurfaceScale

void setPointCloudSurfaceScale (Vector scale)

Set the scale factor to use when rendering each point in the AR point cloud.

Parameters
scale Vector: The scale as a Vector in X, Y, and Z dimensions.

setPointCloudUpdateListener

void setPointCloudUpdateListener (PointCloudUpdateListener listener)

Set the PointCloudUpdateListener to use for receiving point cloud updates. The provided listener will receive an updated ARPointCloud as the point cloud updates.

Parameters
listener PointCloudUpdateListener: The PointCloudUpdateListener to use to receive point cloud updates.

Hooray!