Most visited

Recently visited

ARNode

public class ARNode
extends Node

java.lang.Object
   ↳ com.viro.core.Node
     ↳ com.viro.core.ARNode


ARNode is a specialized Node that corresponds to a detected or manually created ARAnchor. ARNodes are automatically created by Viro and added to the Scene as anchors are created, and by default hold no content and have no children. Each ARNode is continually updated to stay in sync with its corresponding ARAnchor: if the anchor's position, orientation, or other detected properties change, the ARNode will be changed as well.

ARNode is the mechanism through which you can attach virtual content to real-world objects. For example, if an ARPlaneAnchor is detected, you can add a 3D model to that plane by loading the Object3D and making it a child of the anchor's ARNode.

While normal Nodes can be used in AR, it is highly recommended to ensure that all nodes descend from an ARNode. This is 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.

There are three ways to acquire ARNodes:

  1. Real-world feature detection. Every real-world feature detected will trigger a callback giving you an ARNode corresponding to that feature. This can used to add content to real-world features like planes or images. To do this, attach a ARScene.Listener to the ARScene, and listen for onAnchorFound(ARAnchor, ARNode).
  2. Hit-test results. Perform a hit-test using performARHitTest(Point, ARHitTestListener), performARHitTestWithPosition(Vector, ARHitTestListener), or performARHitTestWithRay(Vector, ARHitTestListener). These functions will return an ARHitTestResult for each intersected real-world. You can retrieve an ARNode corresponding to any hit location via createAnchoredNode().
  3. Arbitrary real-world location. You can create an ARNode at any world coordinate position by invoking createAnchoredNode(Vector). Note that world coordinates are in meters.
  4. Finally, when finished with a manually constructed ARNode (methods 2 or 3 above), 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. Nodes that are automatically detected (method 1 above), do not need to be detached.

    Summary

    Public methods

    void detach()

    Detaches this ARNode, removing it and all of its children from the Scene, and stopping it from receiving further AR tracking updates.

    ARAnchor getAnchor()

    Get the ARAnchor associated with this ARNode.

    void removeFromParentNode()

    Remove this Node from its parent.

    void setPauseUpdates(boolean pauseUpdates)

    Set to true to pause automatic synchronization between this ARNode and its ARAnchor.

    void setPosition(Vector position)

    This operation is not valid for ARNodes.

    void setRotation(Vector rotation)

    This operation is not valid for ARNodes.

    Public methods

    detach

    void detach ()

    Detaches this ARNode, removing it and all of its children from the Scene, and stopping it from receiving further AR tracking updates. After this is called, the ARNode becomes unusable.

    This may only be called on ARNodes that are created manually by calls to createAnchoredNode(), createAnchoredNode(Vector, Quaternion), or createAnchoredNode(Vector). Other ARNodes are created automatically when Viro detects real-world features (e.g. planes and images), and are automatically detached when those features are no longer visible to the AR system.

    getAnchor

    ARAnchor getAnchor ()

    Get the ARAnchor associated with this ARNode. The anchor is used to fix the virtual content of this Node to tracked object represented by the anchor. This node is automatically updated with the anchor's transformations.

    This returns an immutable copy of the underlying anchor. The anchor returned will not be updated by the tracking system: it is snapshot of the anchor at this point in time. To get the latest transforms, you must invoke getAnchor() again.

    Returns
    ARAnchor The ARAnchor to which this ARNode is attached.

    removeFromParentNode

    void removeFromParentNode ()

    Remove this Node from its parent.

    setPauseUpdates

    void setPauseUpdates (boolean pauseUpdates)

    Set to true to pause automatic synchronization between this ARNode and its ARAnchor. ARAnchors are periodically updated by the AR tracking system as its estimates of the anchor's properties are refined. By default, updates to the ARAnchor are synchronized to the ARNode; for example, if the tracking system determines that an ARAnchor has moved, the ARNode will move as well.

    It may be useful to pause updates if you wish to ensure the stability of your Scene for a period of time. The ARNode will be immediately updated to its anchor's latest position when pause updates is turned off.

    Parameters
    pauseUpdates boolean: True to pause updates, false to resume updating. When set to false, the ARNode will immediately be updated to match its ARAnchor.

    setPosition

    void setPosition (Vector position)

    This operation is not valid for ARNodes. This is because their transforms are constantly updated by the underlying AR tracking system. Calling this function will throw an IllegalAccessError.

    Parameters
    position Vector: The position as a Vector.

    setRotation

    void setRotation (Vector rotation)

    This operation is not valid for ARNodes. This is because their transforms are constantly updated by the underlying AR tracking system. Calling this function will throw an IllegalAccessError.

    Parameters
    rotation Vector: Vector containing the rotation as three Euler angles in radians.

Hooray!