Viro React

https://viro-community.readme.io/docs
Admin
Viro React is a platform that empowers developers to create immersive augmented and virtual reality...
Tokens:238,814
Snippets:2,683
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Starter Kit Dependencies

Source: https://viro-community.readme.io/docs/developing-viro

Navigate into the cloned starter kit directory and install its dependencies using npm.

```bash
cd starter-kit
npm install
```

--------------------------------

### Install Local Tarball into Starter Kit

Source: https://viro-community.readme.io/docs/developing-viro

Install the locally built Viro tarball into your starter kit project. Ensure you are in the starter-kit directory.

```bash
cd starter-kit
npm install ../viro/reactvision-react-viro-<package.json version>.tgz
```

--------------------------------

### Example Usage

Source: https://viro-community.readme.io/docs/virogameloop

A basic example demonstrating how to use ViroGameLoop within a ViroARScene.

```APIDOC
## Example

```tsx
import { ViroARScene, ViroBox, ViroGameLoop } from "@reactvision/react-viro";
import { useRef } from "react";

const boxRef = useRef(null);

<ViroARScene>
  <ViroBox ref={boxRef} position={[0, 0, -1]} scale={[0.1, 0.1, 0.1]} />
  <ViroGameLoop
    fixedHz={30}
    onFixedUpdate={({ nativeEvent: { dt } }) => {
      // deterministic physics step
    }}
    onUpdate={({ nativeEvent: { dt } }) => {
      // interpolate / render
    }}
  />
</ViroARScene>;
```
```

--------------------------------

### Install Viro Dependencies

Source: https://viro-community.readme.io/docs/developing-viro

Navigate into the cloned Viro directory and install its dependencies using npm.

```bash
cd viro
npm install
```

--------------------------------

### Basic ViroXRSceneNavigator Setup

Source: https://viro-community.readme.io/docs/viroxrscenenavigator

This snippet demonstrates the basic setup for ViroXRSceneNavigator, specifying separate initial scenes for AR and VR. It's suitable for apps that have distinct AR and VR experiences.

```typescript
import * as React from "react";
import { StyleSheet } from "react-native";
import { ViroXRSceneNavigator } from "@reactvision/react-viro";
import { MyARScene } from "./MyARScene";
import { MyVRScene } from "./MyVRScene";

export default function App() {
  return (
    <ViroXRSceneNavigator
      arInitialScene={{ scene: MyARScene }}
      vrInitialScene={{ scene: MyVRScene }}
      style={StyleSheet.absoluteFill}
    />
  );
}
```

--------------------------------

### ViroARScene Component Example

Source: https://viro-community.readme.io/docs/viroarscene

This example demonstrates the basic usage of the ViroARScene component, nesting ViroARPlane and ViroBox within it.

```APIDOC
## ViroARScene

### Description
The `ViroARScene` component allows developers to logically group their experiences and components and switch between them using the [ViroARSceneNavigator](https://viro-community.readme.io/docs/viroarscenenavigator). This component also hosts various properties that enable developers to control and interact with the AR subsystem.

### Example Use:
```javascript
<ViroARScene onTrackingUpdated={this._trackingUpdated}>
  <ViroARPlane>
    <ViroBox position={[0, .5, 0]} />
  </ViroARPlane>
</ViroARScene>
```
```

--------------------------------

### Host Cloud Anchor Example

Source: https://viro-community.readme.io/docs/cloud-anchors

This example demonstrates how to host a cloud anchor after a user selects a plane. It uses `ViroARPlaneSelector` and `hostCloudAnchor`. The anchor is hosted with a TTL of 1 day.

```tsx
import React, { useRef, useState } from "react";
import {
  ViroARSceneNavigator,
  ViroARScene,
  ViroARPlaneSelector,
  ViroNode,
  ViroBox,
} from "@reactvision/react-viro";

function HostScene({ sceneNavigator }) {
  const [cloudAnchorId, setCloudAnchorId] = useState<string | null>(null);
  const [isHosting, setIsHosting] = useState(false);

  const handlePlaneSelected = async (anchor) => {
    if (isHosting) return;
    setIsHosting(true);

    try {
      // Host the anchor with TTL of 1 day (API key auth limit)
      const result = await sceneNavigator.hostCloudAnchor(anchor.anchorId, 1);

      if (result.success && result.cloudAnchorId) {
        console.log("Cloud Anchor ID:", result.cloudAnchorId);
        setCloudAnchorId(result.cloudAnchorId);
        // Share this ID with other users via your backend
      }
      else {
        console.error("Failed to host:", result.error);
      }
    }
    catch (error) {
      console.error("Failed to host anchor:", error);
    }
    finally {
      setIsHosting(false);
    }
  };

  return (
    <ViroARScene>
      <ViroARPlaneSelector onPlaneSelected={handlePlaneSelected}>
        {/* This content appears at the anchor location */}
        <ViroBox
          position={[0, 0.05, 0]}
          scale={[0.1, 0.1, 0.1]}
          materials={["boxMaterial"]}
        />
      </ViroARPlaneSelector>
    </ViroARScene>
  );
}

export default function App() {
  return (
    <ViroARSceneNavigator
      // provider defaults to "reactvision" — set provider="arcore" to use Google Cloud Anchors instead
      initialScene={{ scene: HostScene }}
    />
  );
}

```

--------------------------------

### npm Install Fails on Windows

Source: https://viro-community.readme.io/docs/frequently-asked-questions

This error occurs when installing the starter kit on Windows due to platform incompatibility with fsevents. It can be resolved by removing fsevents from package.json or using `npm install -f`.

```text
npm ERR! code EBADPLATFORM
npm ERR! notsup Unsupported platform for fsevents@2.3.2: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})
npm ERR! notsup Valid OS:    darwin
npm ERR! notsup Valid Arch:  any
npm ERR! notsup Actual OS:   win32
npm ERR! notsup Actual Arch: x64
```

--------------------------------

### Full Scene with Registered Animation

Source: https://viro-community.readme.io/docs/animation

This example provides the complete code for a Viro scene that includes a registered animation and applies it to a ViroImage. It demonstrates the setup for using ViroAnimations.registerAnimations and rendering a component with animation properties.

```javascript
'use strict';

import React, { Component } from 'react';
import {
  ViroScene,
  ViroImage,
  ViroAnimations,
} from 'react-viro';

const AnimationTest = () => {
  return (
    <ViroScene>
    	<ViroImage
        source={require('./res/myimage.jpg')}
        position={[0, -1, -2]} 		
        scale={[.1, .1, .1]} 
        animation={{name:'animateImage', run:true}} />
    </ViroScene>
  );
}

ViroAnimations.registerAnimations({
  animateImage:{
    properties:{
      scaleX:1,
      scaleY:.6,
      scaleZ:1,
      opacity: 1
    },  
    easing:"Bounce", 
    duration: 5000
  },
});

```

--------------------------------

### ViroARObjectMarker Usage Example

Source: https://viro-community.readme.io/docs/viroarobjectmarker

This example demonstrates how to register an object target and use the ViroARObjectMarker component to place a ViroBox relative to the detected target.

```APIDOC
## ViroARObjectMarker Usage Example

### Description
This example shows how to register an object target using `ViroARTrackingTargets.createTargets` and then utilize the `ViroARObjectMarker` component to render a `ViroBox` in AR, positioned relative to the detected target.

### Code
```javascript
// Register the target
ViroARTrackingTargets.createTargets({
  "targetOne": {
    source: require('./res/targetOne.arobject'),
    type: 'Object'
  },
});

<ViroARObjectMarker target={"targetOne"}>
  <ViroBox position={[0, .25, 0]} scale={[.5, .5, .5]} />
</ViroARObjectMarker>
```
```

--------------------------------

### Install iOS Pods

Source: https://viro-community.readme.io/docs/provider-setup

Navigate to the ios directory of your Bare React Native project and run 'pod install' to install the necessary native dependencies.

```bash
cd ios && pod install && cd ..
```

--------------------------------

### Basic ViroCameraTexture Example

Source: https://viro-community.readme.io/docs/virocameratexture

This example demonstrates how to use ViroCameraTexture to create a mirror effect. It binds the front camera feed to a material named 'mirrorMat' and applies it to a ViroQuad. Ensure the material uses the 'Constant' lighting model.

```tsx
import {
  ViroMaterials,
  ViroQuad,
  ViroCameraTexture,
} from "@reactvision/react-viro";

ViroMaterials.createMaterials({
  mirrorMat: { lightingModel: "Constant" },
});

function MirrorScene() {
  const cameraRef = useRef(null);

  return (
    <ViroARScene>
      <ViroCameraTexture
        ref={cameraRef}
        material="mirrorMat"
        cameraPosition="front"
        paused={false}
        onCameraReady={() => console.log("Camera ready")}
      />
      <ViroQuad
        width={0.54}
        height={0.96}
        position={[0, 0, -1]}
        materials={["mirrorMat"]}
      />
    </ViroARScene>
  );
}
```

--------------------------------

### onLoadStart

Source: https://viro-community.readme.io/docs/viroimage

Callback triggered when the system starts processing the image specified by the `source` prop.

```APIDOC
## onLoadStart

### Description
Callback triggered when we are processing the image to be displayed as specified by the `source` prop.

### Type
```
React.PropTypes.func
```

### Example
```javascript
_onLoadStart() {
  console.log('Image loading started...');
}
```
```

--------------------------------

### ViroVirtualJoystick Example

Source: https://viro-community.readme.io/docs/virovirtualjoystick

Example usage of ViroVirtualJoystick, demonstrating its props and how to handle stick changes. Ensure explicit width and height are set in the style prop.

```tsx
import { ViroVirtualJoystick } from "@reactvision/react-viro";

const ctrl = { x: 0, y: 0 }; // module-level, shared with game loop

<ViroVirtualJoystick
  controllerId="p1"
  stickSide="left"
  radius={60}
  tintColor="rgba(255,255,255,0.7)"
  onStickChange={(e) => {
    ctrl.x = e.nativeEvent.x;
    ctrl.y = e.nativeEvent.y;
  }}
  style={{ width: 120, height: 120 }}
/>;
```

--------------------------------

### startVideoRecording

Source: https://viro-community.readme.io/docs/viroarscenenavigator

Starts recording the ViroARSceneNavigator's output, capturing Viro components and external audio. Permissions for microphone and camera are required.

```APIDOC
## startVideoRecording

### Description
Starts a recording of the ViroARSceneNavigator capturing only Viro-rendered components and external audio (microphone and camera permissions required).

### Parameters
* `fileName` (string) - Name of the file saved to the app's temporary files. If the name matches an existing file, it will be overridden. A file extension is added automatically.
* `saveToCameraRoll` (boolean) - Whether the file should also be saved to the user's Photos at the end of recording (requires photo/video saving permissions).
* `onError` (func) - A function invoked with an errorCode if recording encounters an issue.
```

--------------------------------

### Basic ViroSceneNavigator Usage

Source: https://viro-community.readme.io/docs/viroscenenavigator

This example demonstrates the basic usage of ViroSceneNavigator to render an initial scene. Ensure MyStartScene is correctly imported.

```javascript
var MyStartScene = require('./MyStartScene');
import { AppRegistry, ViroScene, ViroSceneNavigator, } from 'react-viro';
var ViroSceneNav = React.createClass({
    render: function () {
        return (
            <ViroSceneNavigator
                initialScene={{ scene: MyStartScene }}
            />
        );
    }
})
```

--------------------------------

### Camera UI Constraint Example

Source: https://viro-community.readme.io/docs/camera

Demonstrates how to attach UI elements to a camera, ensuring they maintain a fixed position relative to the camera's view. This example places a ViroBox 5 meters in front of the camera.

```javascript
<ViroCamera position={[0,0,0]} active={true} >
  <ViroBox position={[0, 0, -5]} />
</ViroCamera>
```

--------------------------------

### Install iOS Native Pods

Source: https://viro-community.readme.io/docs/integrating-viroreact-with-react-native-no-expo

Run this command to install the necessary native pods for ViroReact after updating the Podfile.

```bash
npx pod-install
```

```bash
pod install
```

--------------------------------

### Resolve Cloud Anchor Example

Source: https://viro-community.readme.io/docs/cloud-anchors

This example shows how to resolve a previously hosted cloud anchor and place content at its location. It uses `resolveCloudAnchor` and displays a `ViroBox` once the anchor is successfully resolved.

```tsx
function ResolveScene({ sceneNavigator, cloudAnchorIdToResolve }) {
  const [resolvedPosition, setResolvedPosition] = useState(null);

  useEffect(() => {
    const resolve = async () => {
      try {
        const result = await sceneNavigator.resolveCloudAnchor(
          cloudAnchorIdToResolve
        );

        if (result.success && result.anchor) {
          console.log("Resolved at:", result.anchor.position);
          setResolvedPosition(result.anchor.position);
        }
        else {
          console.error("Failed to resolve:", result.error);
        }
      }
      catch (error) {
        console.error("Failed to resolve anchor:", error);
      }
    };

    if (cloudAnchorIdToResolve) {
      resolve();
    }
  }, [cloudAnchorIdToResolve]);

  return (
    <ViroARScene>
      {resolvedPosition && (
        <ViroNode position={resolvedPosition}>
          <ViroBox
            position={[0, 0.05, 0]}
            scale={[0.1, 0.1, 0.1]}
            materials={["boxMaterial"]}
          />
        </ViroNode>
      )}
    </ViroARScene>
  );
}

```

--------------------------------

### ViroGameLoop Example with Fixed and Update Callbacks

Source: https://viro-community.readme.io/docs/virogameloop

Example demonstrating the usage of ViroGameLoop within a ViroARScene, configuring fixedHz for deterministic physics and onUpdate for rendering.

```tsx
import { ViroARScene, ViroBox, ViroGameLoop } from "@reactvision/react-viro";
import { useRef } from "react";

const boxRef = useRef(null);

<ViroARScene>
  <ViroBox ref={boxRef} position={[0, 0, -1]} scale={[0.1, 0.1, 0.1]} />
  <ViroGameLoop
    fixedHz={30}
    onFixedUpdate={({ nativeEvent: { dt } }) => {
      // deterministic physics step
    }}
    onUpdate={({ nativeEvent: { dt } }) => {
      // interpolate / render
    }}
  />
</ViroARScene>;
```

--------------------------------

### Image Source Loading

Source: https://viro-community.readme.io/docs/viro360image

Examples showing how to load image sources using `require` or a URI.

```APIDOC
## source (*required*)

### Parameters

- **source** (ImageSourcePropType) - Required - An asset can be loaded by using `require()` or `{ uri: 'https://example.com/your-image.png' }`

### Request Example

```javascript
<Viro360Image
  source={require("./res/myimage.png")}
/>

<Viro360Image
  source={{ uri: 'https://example.com/your-image.png' }}
/>
```
```

--------------------------------

### Basic ViroSpotLight Example

Source: https://viro-community.readme.io/docs/virospotlight

This snippet demonstrates the basic usage of a ViroSpotLight. It sets the color, attenuation distances, position, direction, and angles for the spotlight.

```javascript
<ViroSpotLight
    color="#ffffff"
    attenuationStartDistance={2}
    attenuationEndDistance={6}
    position={[0, -5, 5]}
    direction={[0 - 1, 0]}
    innerAngle={0}
    outerAngle={45}
/>
```

--------------------------------

### ViroVideo Component Usage

Source: https://viro-community.readme.io/docs/virovideo

This example demonstrates the basic usage of the ViroVideo component, including setting the video source and loop behavior.

```APIDOC
## ViroVideo Component

A component that provides a 2D surface for playing video. This can be used to display virtual video screens.

### Example Use:

```javascript
<ViroVideo
    source={require('./video/myvid.mp4')}
    loop={true}
    position={[0,2,-5]}
    scale={[2, 2, 0]}
 />
```

## Props

### source (* required)

- **Type**: PropTypes.oneOfType([PropTypes.shape({uri: PropTypes.string}), PropTypes.number])
- **Description**: The video source, a remote URL or a local file resource. MPEG videos accepted.
  - To invoke with remote url: `{uri:"http://example.org/myvideo.mp4"}`
  - To invoke with local source: `require('./myvideo.mp4');`

### animation

- **Type**: PropTypes.shape({
      name: PropTypes.string,
      delay: PropTypes.number,
      loop: PropTypes.bool,
      onStart: PropTypes.func,
      onFinish: PropTypes.func,
      run: PropTypes.bool,
    })
- **Description**: A collection of parameters that determine if this component should animate. For more information on animated components please see our [Animation](https://viro-community.readme.io/docs/animation) Guide.

### dragPlane

- **Type**: PropTypes.shape({
      planePoint: PropTypes.arrayOf(PropTypes.number),
      planeNormal: PropTypes.arrayOf(PropTypes.number),
      maxDistance: PropTypes.number
    })
- **Description**: 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**: PropTypes.oneOf(["FixedDistance", "FixedToWorld"])
- **Description**: 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.
- **Default Value**: "FixedDistance"

### height

- **Type**: PropTypes.number
- **Description**: The height of the video in 3D space. Default value is 1.

### highAccuracyEvents

- **Type**: PropTypes.bool
- **Description**: True if events should use the geometry of the object to determine if the user is interacting with this object. If false, the object's axis-aligned bounding box will be used instead. Enabling this is more accurate but takes more processing power, so it is set to false by default.

### ignoreEventHandling

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

### lightReceivingBitMask

- **Type**: PropTypes.number
- **Description**: A bit mask that is bitwise and-ed (&) with each light's influenceBitMask. If the result is > 0, then the light will illuminate this object. For more information please see the [Lighting and Materials](https://viro-community.readme.io/docs/3d-scene-lighting) Guide.
```

--------------------------------

### Directional Vector Example

Source: https://viro-community.readme.io/docs/virospotlight

Illustrates how to specify the direction for a spotlight using a 3D unit vector. This example sets the light to face towards the positive x-axis.

```javascript
direction={[1, 0, 0]}
```

--------------------------------

### Basic ViroSphere Component

Source: https://viro-community.readme.io/docs/virosphere

Example of how to render a ViroSphere with specified dimensions, radius, position, and materials.

```javascript
<ViroSphere
    heightSegmentCount={20}
    widthSegmentCount={20}
    radius={2}
    position={[0, 0, -2]}
    materials={"spherematerial"}
/>
```

--------------------------------

### Basic ViroButton Usage

Source: https://viro-community.readme.io/docs/virobutton

Example of how to use the ViroButton component with different image sources for its states and basic positioning.

```javascript
<ViroButton
    source={require("./res/button_base.jpg")}
    gazeSource={require("./res/button_on_gazing.jpg")}
    tapSource={require("./res/button_on_tap_pressed.jpg")}
    position={[1, 3, -5]}
    height={2}
    width={3}
    onTap={this._onButtonTap}
/>    

```

--------------------------------

### Viro360Image Component Usage

Source: https://viro-community.readme.io/docs/viro360image

This example demonstrates the basic usage of the Viro360Image component with its source property.

```APIDOC
## Viro360Image

A component that displays a 360 photo sphere that surrounds the user.

### Props

#### source (*required*)

- **Type**: [ImageSourcePropType](https://reactnative.dev/docs/image#source)
- **Description**: An asset can be loaded by using `require()` or `{ uri: 'https://example.com/your-image.png' }`

#### isHDR

- **Type**: boolean
- **Description**: Set to true if we are providing a radiance HDR image (.hdr) as the source of this 360 image.

#### format

- **Type**: 'RGBA8' | 'RGBA4' | 'RGB565'
- **Description**: The *internal* format to use for the image. This is the format we will use to store the image on the GPU. It is not the format of the source image data. This property does not apply to HDR images.
  - **RGBA8**: Each pixel is described with 32-bits, using eight bits per channel
  - **RGBA4**: Each pixel is described with 16 bits, using four bits per channel
  - **RGB565**: Formats the picture into 16 bit color values without alpha

#### onLoadEnd

- **Type**: Function
- **Description**: Callback triggered when we have finished loading the 360 image to be displayed. If the image was loaded and displayed correctly, the 'success' parameter will be true.

#### onError

- **Type**: Function
- **Description**: Callback invoked when the 360 Image fails to load. The error message is contained in event.nativeEvent.error

#### onLoadStart

- **Type**: Function
- **Description**: Callback triggered when the image is processing to be displayed in this 360 Photo (either downloading / reading from file).

#### rotation

- **Type**: [number, number, number]
- **Description**: The rotation of the box around its local axis specified as Euler angles [x, y, z]. Units for each angle are specified in degrees.

### Example Usage

```javascript
<Viro360Image
  source={require("./res/myimage.png")}
  rotation={[0, 45, 0]}
  format="RGBA8"
  onLoadStart={handleLoadStart}
  onLoadEnd={handleLoadEnd}
  onError={handleError}
/>
```
```

--------------------------------

### Basic ViroPolyline Usage

Source: https://viro-community.readme.io/docs/viropolyline

This example demonstrates how to create a basic ViroPolyline with specified position, points, thickness, and material.

```javascript
<ViroPolyline
    position={[0, 0, -2]}
    points={[
        [0, 0, 0],
        [.5, .5, .5],
        [1, 0, 0]
    ]}
    thickness={0.2}
    materials={"red"}
/>
```

--------------------------------

### ViroButton Component Usage

Source: https://viro-community.readme.io/docs/virobutton

Example of how to use the ViroButton component with different source images for various states and basic positioning.

```APIDOC
## ViroButton Component

A component that displays a 2D Button that is positioned in 3D world space. The button will animate onTap and switch the button look based on its state.

### Example Use:

```javascript
<ViroButton
    source={require("./res/button_base.jpg")}
    gazeSource={require("./res/button_on_gazing.jpg")}
    tapSource={require("./res/button_on_tap_pressed.jpg")}
    position={[1, 3, -5]}
    height={2}
    width={3}
    onTap={this._onButtonTap}
/>    
```
```

--------------------------------

### Handle OBJ Loading Callbacks

Source: https://viro-community.readme.io/docs/3d-objects

Register functions to respond to OBJ loading start, end, and error events. This example logs messages to the console for each event.

```javascript
const OBJTest = () => {
  const handleLoadStart = () => {
    console.log("OBJ loading has started");   
  }
  const handleLoadEnd = () => {
    console.log("OBJ loading has finished");
  }
  const handleError(event) {
    console.log("OBJ loading failed with error: " + event.nativeEvent.error);
  }
  
  return (
    <ViroScene> 
      <Viro3DObject
        source={require('./res/model.obj')}
        resources={[
          require('./res/model.mtl'),
          require('res/texture1.html'),
          require('res/texture2.html'),
          require('res/texture3.html')
        ]}
        type="OBJ"
        position={[0.0, 0.0, -10]}
        scale={[0.1, 0.1, 0.1]}
        onLoadStart={this._onLoadStart}
        onLoadEnd={this._onLoadEnd}
        onError={this._onError}
      />
    </ViroScene>
  )
}
```

--------------------------------

### Animate Material Color

Source: https://viro-community.readme.io/docs/animation

Animate the material of a Viro object from one defined material to another. This example animates a ViroQuad from red to blue over 3 seconds, with a 3-second delay before starting.

```javascript
const AnimationTest = () => {

  const handleAninimationFinished = () => {
    console.log("Animation has finished!");
  }
  
  return (
    <ViroScene>
      <ViroQuad 
        materials={["redColor"]}
        position={[0, -.5, -1]}
        animation={{
          name:'animateColor', 
          run: true, 
          loop: false, 
          delay:3000
        }} />
      </ViroScene>
  )
}

ViroMaterials.createMaterials({
  redColor: {
    diffuseColor: "#FF0000"
  },
  blueColor: {
    diffuseColor: "#0000FF"
  },
});

ViroAnimations.registerAnimations({
  animateColor: {
    properties: {
      material: "blueColor"
    }, 
    duration:3000
  },
});
```

--------------------------------

### Run Android Starter Kit

Source: https://viro-community.readme.io/docs/developing-viro

If developing for Android, run the starter kit application with a device connected.

```bash
npm run android
```

--------------------------------

### ViroAnimatedComponent Usage Example

Source: https://viro-community.readme.io/docs/viroanimatedcomponent

This snippet demonstrates how to use ViroAnimatedComponent to animate a Viro3DObject. It includes properties for animation type, delay, looping, and callbacks for start and finish events. Ensure the animation property matches a defined animation.

```javascript
<ViroAnimatedComponent
  animation="rotateAroundYAxis"
  delay={1000}
  loop={true}
  onStart={this._onStart}
  onFinish={this._onFinish}
  run={true}
>
  <Viro3DObject
    source={require("./res/skeleton.obj")}
    position={[-0.0, -5.5, -1.15]}
    materials={["skeleton"]}
  />
</ViroAnimatedComponent>;
```

--------------------------------

### Multiplayer AR Game with Cloud Anchors

Source: https://viro-community.readme.io/docs/cloud-anchors

This example demonstrates how to use Cloud Anchors to synchronize AR experiences across multiple devices in real-time. It involves resolving existing anchors shared by other players and hosting new anchors to share with them. Requires Firebase for real-time data synchronization and a ViroReact setup.

```tsx
import { useEffect, useState } from "react";
import { database } from "./firebase"; // Your Firebase setup

function MultiplayerARScene({ sceneNavigator, roomId }) {
  const [sharedObjects, setSharedObjects] = useState([]);

  // Listen for cloud anchors shared by other players
  useEffect(() => {
    const unsubscribe = database
      .ref(`rooms/${roomId}/anchors`)
      .on("child_added", async (snapshot) => {
        const { cloudAnchorId, objectType } = snapshot.val();

        const result = await sceneNavigator.resolveCloudAnchor(cloudAnchorId);
        if (result.success && result.anchor) {
          setSharedObjects((prev) => [
            ...prev,
            {
              id: snapshot.key,
              position: result.anchor.position,
              objectType,
            },
          ]);
        }
      });

    return () => unsubscribe();
  }, [roomId]);

  // Host a new object and share with other players
  const placeObject = async (anchor, objectType) => {
    const result = await sceneNavigator.hostCloudAnchor(anchor.anchorId, 1);

    if (result.success) {
      // Share with other players via Firebase
      await database.ref(`rooms/${roomId}/anchors`).push({
        cloudAnchorId: result.cloudAnchorId,
        objectType,
        timestamp: Date.now(),
      });
    }
  };

  return (
    <ViroARScene onAnchorFound={(anchor) => placeObject(anchor, "cube")}>
      {sharedObjects.map((obj) => (
        <ViroNode key={obj.id} position={obj.position}>
          <ViroBox scale={[0.1, 0.1, 0.1]} />
        </ViroNode>
      ))}
    </ViroARScene>
  );
}

```

--------------------------------

### Prebuild and Run Native Projects

Source: https://viro-community.readme.io/docs/viroobjectdetector

After installation and configuration, prebuild your native projects and then run them on Android or iOS. Use '--clean' with prebuild to regenerate from scratch if needed.

```bash
npx expo prebuild        # add --clean to regenerate from scratch (see Model bundling caveat)
npx expo run:android     # / run:ios
```

--------------------------------

### Basic ViroCamera Usage

Source: https://viro-community.readme.io/docs/virocamera

Example of how to set up a ViroCamera with initial position and rotation. Ensure only one camera is active to avoid undefined behavior.

```javascript
<ViroCamera
  position={[0, 0, 0]}
  rotation={[45, 0, 0]}
  active={true} 
/>
```

--------------------------------

### Initialize ViroVRSceneNavigator

Source: https://viro-community.readme.io/docs/scene-navigation

Set up the initial scene for your VR application using ViroVRSceneNavigator. Ensure the initial scene is correctly imported.

```javascript
import { FirstScene } from './FirstScene';
import { ViroVRSceneNavigator } from '@reactvision/viro-react'

const ViroSceneNav = () => {
  return (
    <ViroVRSceneNavigator initialScene={{ scene: FirstScene }} />
  )
}
```

--------------------------------

### onClick Callback Example

Source: https://viro-community.readme.io/docs/viroportalscene

This example demonstrates how to implement the onClick callback for a draggable object. The callback receives the click position and source.

```javascript
  _onClick(position, source)  {
    // user has clicked the object
  }
```

--------------------------------

### Example Response for getSemanticLabelFractions

Source: https://viro-community.readme.io/docs/scene-semantics

This is an example of the data structure returned by the getSemanticLabelFractions method, showing pixel fractions for various semantic labels.

```typescript
{
  success: true,
  fractions: {
    unlabeled: 0.02,
    sky: 0.35,
    building: 0.28,
    tree: 0.15,
    road: 0.12,
    sidewalk: 0.03,
    terrain: 0.02,
    structure: 0.01,
    object: 0.01,
    vehicle: 0.00,
    person: 0.01,
    water: 0.00
  }
}
```

--------------------------------

### onLoadStart

Source: https://viro-community.readme.io/docs/viro3dobject

Callback invoked when the OBJ file begins loading.

```APIDOC
## onLoadStart

### Description
Callback invoked when the OBJ file starts loading.

### Type
`Function`
```

--------------------------------

### Install ViroObjectDetector and ONNX Provider

Source: https://viro-community.readme.io/docs/viroobjectdetector

Install the necessary packages for ViroObjectDetector and its ONNX inference provider. Ensure both are added to your Expo project's plugins.

```bash
npm install @reactvision/react-viro @reactvision/react-viro-onnx
```

--------------------------------

### Example Usage of ViroVirtualButton

Source: https://viro-community.readme.io/docs/virovirtualbutton

Demonstrates how to use the ViroVirtualButton component with its required and optional props. Ensure explicit width and height are set in the style prop for touch event handling.

```tsx
<ViroVirtualButton
  controllerId="p1"
  button="A"
  size={48}
  tintColor="#FF6B9D"
  onPressIn={() => console.log("A pressed")}
  onPressOut={() => console.log("A released")}
  style={{ width: 48, height: 48 }}
/>
```

--------------------------------

### Clone Starter Kit Repository

Source: https://viro-community.readme.io/docs/developing-viro

Clone the starter kit repository, which serves as a base for your Viro application.

```bash
gh repo clone ReactVision/starter-kit
```

--------------------------------

### Select Geospatial Provider

Source: https://viro-community.readme.io/docs/geospatial

Choose the provider for geospatial anchors. 'reactvision' is the default and requires no additional setup. 'arcore' requires Google Cloud setup.

```tsx
<ViroARSceneNavigator
  // provider="reactvision" // this is the default
  // ... other props
/>

<ViroARSceneNavigator
  provider="arcore"
  // ... other props
/>
```

--------------------------------

### Begin Streaming Configuration

Source: https://viro-community.readme.io/docs/streamingaudiomanager

Configure the stream format, including sample rate and channels, before pushing samples. This must be called after create and before pushSamples.

```typescript
// Begin streaming — must be called before pushSamples
StreamingAudioManager.beginStreaming(
  playerId: string,
  sampleRate: number,   // e.g. 22050, 44100, 48000
  channels: number      // 1 = mono, 2 = stereo
): void;
```

--------------------------------

### Basic ViroScene Usage

Source: https://viro-community.readme.io/docs/viroscene

This snippet shows how to set up a basic ViroScene with a ViroSphere. It demonstrates the fundamental structure of a ViroScene component.

```javascript
<ViroScene
    onClick={this._onClick}
>
    <ViroSphere
        position={[0, 0, -1]}
    />
</ViroScene>
```

--------------------------------

### Skybox onLoadEnd Callback Example

Source: https://viro-community.readme.io/docs/viroskybox

This example shows how to implement the onLoadEnd callback to handle events after the skybox cube map has finished loading. It checks for a successful load.

```typescript
const handleLoadEnd = (event:Event) => {
  if(event.nativeEvent.success) {
    //skybox has loaded successfully!
  }
}
```

--------------------------------

### Basic Viro360Video Usage

Source: https://viro-community.readme.io/docs/viro360video

This example demonstrates the basic usage of the Viro360Video component. It requires a video source and can be configured with various playback options like looping and volume.

```javascript
<Viro360Video
    source={require("./video/myvideo.mp4")}
    onFinish={this._onFinish}
    onUpdateTime={this._onUpdateTime}
    onError={this._videoError}
    loop={true}
    paused={false}
    volume={1.0}/>
```

--------------------------------

### Skybox Texture Map Example

Source: https://viro-community.readme.io/docs/viroskybox

This example demonstrates the structure for providing a cube map with six textures to the ViroSkyBox component. Each key (nx, px, ny, py, nz, pz) corresponds to a specific side of the skybox.

```typescript
{
  nx: require("res/nx.png"),
  px: require("res/px.png"),
  ny: require("res/ny.png"),
  py: require("res/py.png"),
  nz: require("res/nz.png"),
  pz: require("res/pz.png"),
}
```

--------------------------------

### Implement ViroImage Event Callbacks

Source: https://viro-community.readme.io/docs/input-events

This example shows how to attach and implement multiple event handlers for a ViroImage component. Ensure all necessary ViroReact modules are imported.

```javascript
"use strict";
import React, { Component } from "react";
import { StyleSheet, ViroScene, ViroImage } from "react-viro";

var OnHoverExample = React.createClass({
  render: function () {
    return (
      <ViroScene>
        <ViroImage
          source={require("res/myimg.html")}
          position={[0, -0.5, -2]}
          scale={[0.1, 0.1, 0.1]}
          onClick={this._onClick}
          onClickState={this._onClickState}
          onDrag={this._onDrag}
          onHover={this._onHoverDoSomething}
          onScroll={this._onScroll}
          onSwipe={this._onSwipe}
          onTouch={this._onTouch}
          onFuse={{ callback: this._onFuse, timeToFuse: 3000 }}
        />
      </ViroScene>
    );
  },

  _onClick(source) {
    console.log("We just Clicked the image!");
  },

  _onClickState(state, source) {
    if (stateValue == 1) {
      console.log("User has click-down on the image!");
    } else if (stateValue == 2) {
      console.log("User has click-up on the image!");
    } else if (stateValue == 3) {
      console.log("User has finally clicked on the image!");
    }
  },

  _onDrag(draggedToPosition, source) {
    console.log(
      "Dragged to: x" +
        draggedToPosition[0] +
        " y:" +
        draggedToPosition[1] +
        " z: " +
        draggedToPosition[2]
    );
  },

  _onHoverDoSomething(isHovering, source) {
    if (isHovering) {
      console.log("We are hovering onto the image!");
    } else {
      console.log("We are not longer hovering on the image!");
    }
  },
  _onScroll(scrollPosition, source) {
    console.log(
      "Scrolled to: x" + scrollPosition[0] + " y:" + scrollPosition[1]
    );
  },

  _onSwipe(swipeState, source) {
    if (swipeState == 1) {
      console.log("Swiped up");
    } else if (swipeState == 2) {
      console.log("Swiped down");
    } else if (swipeState == 3) {
      console.log("Swiped left");
    } else if (swipeState == 4) {
      console.log("Swiped right");
    }
  },

  _onTouch(state, touchPos, source) {
    var touchX = touchPos[0];
    var touchY = touchPos[1];
    if (state == 1) {
      // Touch Down
    } else if (state == 2) {
      // Touch Down Move
    } else if (state == 3) {
      // Touch Up
    }
  },

  _onFuse(source) {
    // User has hovered over object for timeToFuse milliseconds
  },
});

```

--------------------------------

### Configure Point Cloud Display with Options

Source: https://viro-community.readme.io/docs/viroarscene

Demonstrates how to enable and configure the point cloud visualization in ViroARScene using custom options. This allows for detailed control over the appearance and performance of the point cloud rendering.

```typescript
<ViroARScene 
  displayPointCloud={{
    imageSource: require("./res/pointCloudPoint.png"),
    imageScale: [.02,.02,.02],
    maxPoints: 100 
  }} />
```

--------------------------------

### ViroOrbitCamera Component

Source: https://viro-community.readme.io/docs/viroorbitcamera

Example usage of the ViroOrbitCamera component with basic props.

```APIDOC
## ViroOrbitCamera Component

### Description
A camera component that allows the user to orbit around a specified focal point.

### Props

#### active (* required)
- **Type**: PropTypes.bool.isRequired
- **Description**: If true, sets the corresponding camera as the active one from which we render the world. Setting more than one active camera within a scene will result in undefined behavior.

#### fieldOfView
- **Type**: PropTypes.number
- **Description**: Set the field of view for this camera, along the major (larger) axis. Field of view is an angle that determines how wide or narrow the camera lens is when rendering the scene. This value sets the field of view, in degrees, for the major axis. The major axis is the axis with the larger dimension: the X axis in landscape mode, or the Y axis in portrait mode. By specifying the field of view in terms of the major axis, Viro can keep the field of view consistent upon orientation changes, when the major/minor axes swap. The minor axis field of view is automatically computed from the major axis field of view and the viewport. This value is ignored on VR and AR platforms, where the FOV is fixed by the VR headset or the AR camera. Else, in non-VR (360 mode) the FOV defaults to 90.

#### focalPoint
- **Type**: PropTypes.arrayOf(PropTypes.number)
- **Description**: Cartesian position in 3D world space where the camera focuses on and orbits around. Default position is [0,0,0].

#### position
- **Type**: PropTypes.number
- **Description**: The desired fov for this camera. Default fov is 90.

#### text
- **Type**: PropTypes.string
- **Description**: Put the PropType Description here.

#### transformBehaviors
- **Type**: PropTypes.arrayOf(PropTypes.string)
- **Description**: Put the PropType Description here.

#### width
- **Type**: PropTypes.number
- **Description**: Put the PropType Description here.

#### visible
- **Type**: PropTypes.bool
- **Description**: Put the PropType Description here.

### Example Use:
```javascript
<ViroOrbitCamera
    position={[0, 0, 0]}
    focalPoint={[0, 0, -1]}
    active={true}
/>
```
```

--------------------------------

### Image Rotation

Source: https://viro-community.readme.io/docs/viro360image

Example demonstrating how to set the rotation for the Viro360Image component.

```APIDOC
## rotation

### Parameters

- **rotation** (Array<number>) - Optional - The rotation of the box around its local axis specified as Euler angles [x, y, z]. Units for each angle are specified in degrees.

### Request Example

```javascript
<Viro360Image
  source={{ uri: 'https://example.com/your-image.png' }}
  rotation={[0,45,0]}
/>
```
```

--------------------------------

### Run Prebuild with Clean

Source: https://viro-community.readme.io/docs/integrating-with-expo

Use this command to create your native directories for an Expo project. The --clean flag ensures a fresh build.

```text
npx expo prebuild --clean
```

--------------------------------

### ViroSpatialSound Component

Source: https://viro-community.readme.io/docs/virospatialsound

Example usage of the ViroSpatialSound component to play a spatial sound.

```APIDOC
## ViroSpatialSound Component

### Description
Represents a sound in 3D space. Must be a single-channel sound (mono) and can be placed within a ViroNode or ViroAnimatedComponent which changes its position relative to the user.

### Props

#### source (* required)
- **Type**: [ImageSourcePropType](https://reactnative.dev/docs/image#source)
- **Description**: The source of a spatial sound. Must be a single-channel audio file.

#### loop
- **Type**: boolean
- **Description**: Set to true to loop the spatial sound. This is set to false by default.

#### maxDistance
- **Type**: number
- **Description**: A distance after which the audio can not be heard.

#### minDistance
- **Type**: number
- **Description**: A distance after which the audio will begin to attenuate until maxDistance where the sound is completely gone.

#### muted
- **Type**: boolean
- **Description**: Set to true to mute the spatial sound. This is set to false by default.

#### onError
- **Type**: Function
- **Description**: Callback invoked when the 360 Image fails to load. The error message is contained in event.nativeEvent.error

#### onFinish
- **Type**: Function
- **Description**: Callback that is called when the spatial sound is finished playing. This function isn't called at the end of a spatial sound if looping is enabled.

#### paused
- **Type**: boolean
- **Description**: Set to true to pause the spatial sound. This is set to false by default.

#### rolloffModel
- **Type**: "None" | "Linear" | "Logarithmic"
- **Description**: The rolloff model which determines how the sound volume will fall off between minDistance and maxDistance. Accepts the following values:

* None
* Linear
* Logarithmic

#### volume
- **Type**: number
- **Description**: A number represented volume from 0 to 1. Max volume is equal to 1. Min volume is equal to 0. This is set to 1 by default.

#### position
- **Type**: [number, number, number]
- **Description**: Cartesian position of the sound in 3D world space, specified as [x, y, z].

### Example Usage

```javascript
<ViroSpatialSound
    source={require("./sound/mysound.wav")}
    position={[0, 0, -3]}
    onFinish={this.onFinishSound}
/>
```
```
Tokens:
Raw