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.
Nested classes | |
|---|---|
class |
ARScene.ARSceneBuilder<R extends ARScene, B extends ARSceneBuilder<R, B>>
ARSceneBuilder for building |
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 |
static
ARSceneBuilder<? extends Scene, ? extends SceneBuilder>
|
builder()
Creates a builder for building complex |
ARNode
|
createAnchoredNode(Vector position, Quaternion quaternion)
Create an |
ARNode
|
createAnchoredNode(Vector position)
Create an |
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 |
void
|
removeARImageTarget(ARImageTarget target)
Remove an |
void
|
resetPointCloudSurface()
Reset the point cloud surface to the default values. |
void
|
resolveCloudAnchor(String cloudAnchorId, ARScene.CloudAnchorResolveListener callback)
Resolve the |
void
|
setListener(ARScene.Listener listener)
Set the |
void
|
setPointCloudMaxPoints(int maxPoints)
Set the maximum number of points to render when drawing the AR point cloud. |
void
|
setPointCloudSurface(Surface surface)
Set the |
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 |
ARScene ()
Construct a new ARScene.
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:
ARSceneBuilder<? extends Scene, ? extends SceneBuilder> builder ()
Creates a builder for building complex ARScene objects.
| Returns | |
|---|---|
ARSceneBuilder<? extends Scene, ? extends SceneBuilder> |
ARScene.ARSceneBuilder object.
|
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.
|
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.
|
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.
|
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. 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.
|
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. |
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.
|
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.
|
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.
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|