ViroARPlane

A ViroARPlane is a component that allows developers to place components relative to a plane discovered by the AR system. The process of attaching a ViroARPlane to a plane discovered by the AR system is discussed in the next section.

Anchoring

Anchoring is our term for attaching virtual content to detected real-world points/features (anchors). For ViroARPlanes, we support two types: manual and automatic anchoring.

Automatic Anchoring

To enable automatic anchoring, the developer provides a minHeight and minWidth to the ViroARPlane and adds the content they desire within the ViroARPlane component. When the AR system finds a plane that matches the given dimensions, the ViroARPlane will be anchored to the real world plane and the child components will be made visible. Any updates to the real-world plane will be given to the developer through the onAnchorFound, onAnchorUpdated, and onAnchorRemoved callback functions.

Example use:

JavaScript

<ViroARScene
  onAnchorFound={() => console.log('onAnchorFound')}
  onAnchorUpdated={() => console.log('onAnchorUpdated')}
  onAnchorRemoved={() => console.log('onAnchorRemoved')}>
  <ViroARPlane minHeight={0.1} minWidth={0.1} alignment={'Horizontal'}>
    <ViroBox position={[0, 0, 0]} scale={[0.1, 0.1, 0.1]} />
  </ViroARPlane>
</ViroARScene>

Manual Anchoring

In manual anchoring, rather than having the platform determine which real-world feature/anchor the ViroARPlane is attached to, the developer is required to listen for all the anchors and "choose" the anchor they want the ViroARPlane to attach to via the anchorId property. To listen for all the anchors, the user should add onAnchorFound, onAnchorUpdated and onAnchorRemoved listeners to their ViroARScene component which will receive all anchors that the AR platform discovers.

Example use:

JavaScript

<ViroARScene
  onAnchorFound={(foundAnchor) => console.log('onAnchorFound', foundAnchor)}
  onAnchorUpdated={() => console.log('onAnchorUpdated')}
  onAnchorRemoved={() => console.log('onAnchorRemoved')}>
  <ViroARPlane anchorId={foundAnchor.anchorId}>
    <ViroBox position={[0, 0, 0]} scale={[0.1, 0.1, 0.1]} />
  </ViroARPlane>
</ViroARScene>

Props

alignment

Type	Description
"Horizontal" | "HorizontalUpward" | "HorizontalDownward" | "Vertical"	Specifies the desired alignment of a plane that this component will "anchor" to.The default value is "Horizontal". Don't forget to set the anchorDetectionTypes prop of ViroARScene to tell the AR Session what type of planes to discover. Note: "HorizontalUpward" and "HorizontalDownward" are only supported in Android. For Automatic Anchoring, see Anchoring

anchorId

Type	Description
string	For Manual Anchoring, see Anchoring The ID of the anchor that the platform should anchor this ViroARPlane to. If no Anchor has the specified anchorId, then plane will not be visible until an Anchor appears with the same ID.

dragPlane

Type	Description
ViroDragPlane	When a drag type of "FixedToPlane" is given, dragging is limited to a user defined plane. The dragging behavior is then configured by this property (specified by a point on the plane and its normal vector). You can also limit the maximum distance the dragged object is allowed to travel away from the camera/controller (useful for situations where the user can drag an object towards infinity).

dragType

Type

Description

"FixedDistance" | "FixedToWorld" | "FixedDistanceOrigin" | "FixedToPlane"

Determines the behavior of drag if onDrag is specified. "FixedDistance": Dragging is limited to a fixed radius around the user, dragged from the point at which the user has grabbed the geometry containing this draggable node "FixedDistanceOrigin": Dragging is limited to a fixed radius around the user, dragged from the point of this node's position in world space. "FixedToWorld": Dragging is based on intersection with real world objects. Available only in AR "FixedToPlane": Dragging is limited to a fixed plane around the user. The configuration of this plane is defined by the dragPlane property. The default value is "FixedDistance".

ignoreEventHandling

Type	Description
boolean	When set to true, this control will ignore events and not prevent controls behind it from receiving event callbacks.The default value is false.

minHeight

Type	Description
number	For Automatic Anchoring, see Anchoring Specifies the minimum height, in meters, of a plane that this component will "anchor" to. The default value is 0.

minWidth

Type	Description
number	For Automatic Anchoring, see Anchoring Specifies the minimum width, in meters, of a plane that this component will "anchor" to. The default value is 0.

onAnchorFound

Type	Description
(anchor) => void	Called when this component is anchored to a plane that is at least minHeight by minWidth large. This is when the component is made visible. anchor: see Anchor

onAnchorRemoved

Type	Description
Function	Called when this component is detached from a plane and is no longer visible.

onAnchorUpdated

Type	Description
(anchor) => void	Called when the plane to which this component is anchored is updated. anchor: see Anchor

onClick

See ViroNode onClick.

onClickState

See ViroNode onClickState.

onCollision

See ViroNode onCollision.

onDrag

See ViroNode onDrag.

onFuse

See ViroNode onFuse.

onHover

See ViroNode onHover.

onPinch

See ViroNode onPinch.

onRotate

See ViroNode onRotate.

onScroll

See ViroNode onScroll.

onSwipe

See ViroNode onSwipe.

onTouch

See ViroNode onTouch.

onTransformUpdate

See ViroNode onTransformUpdate.

opacity

Type	Description
number	A number from 0 to 1 that specifies the opacity of the container. A value of 1 translates into a fully opaque node while 0 represents full transparency.

pauseUpdates

Type	Description
boolean	True/False to stop the automatic positioning/rotation of children components of a ViroARPlane. This does not stop onAnchorUpdated from being called.

viroTag

Type	Description
string	A tag given to other components when their physics body collides with this component's physics body. Refer to physics for more information.

visible

Type	Description
boolean	False if the container should be hidden. By default the container is visible and this value is true.

renderingOrder

Type	Description
number	This determines the order in which this Node is rendered relative to other Nodes. Nodes with greater rendering orders are rendered last. The default rendering order is zero. For example, setting a Node's rendering order to -1 will cause the Node to be rendered before all Nodes with rendering orders greater than or equal to 0.

rotation

Type	Description
[number, number, number]	The rotation of the component around it's local axis specified as Euler angles [x, y, z]. Units for each angle are specified in degrees.

scale

Type	Description
	PropTypes.arrayOf(PropTypes.number)Put the PropType Description here.

transformBehaviors

Type

Description

string[]

An array of transform constraints that affect the transform of the object. For example, putting the value "billboard" will ensure the box is facing the user as the user rotates their head on any axis. This is useful for icons or text where you'd like the box to always face the user at a particular rotation. Allowed values(values are case sensitive): "billboard": Billboard object on x,y,z axis "billboardX": Billboard object on the x axis "billboardY": Billboard object on the y axis "billboardZ": Billboard object on the z axis

Methods

setNativeProps(nativeProps)

A wrapper function around the native component's setNativeProps which allow users to set values on the native component without changing state/setting props and re-rendering. Refer to the React Native documentation on Direct Manipulation for more information.

Parameter	Type	Description
nativeProps	object	an object where the keys are the properties to set and the values are the values to set

JavaScript

componentRef.setNativeProps({ position: [0, 0, -1] });