{"_id":"59bc27227c3f420010f965e3","project":"578c4badbd223d2000cc1441","version":{"_id":"59bc03d31d2d8d001a34457d","project":"578c4badbd223d2000cc1441","__v":2,"createdAt":"2017-09-15T16:46:11.721Z","releaseDate":"2017-09-15T16:46:11.721Z","categories":["59bc03d31d2d8d001a34457e","59bc03d31d2d8d001a34457f","59bc03d31d2d8d001a344580","59bc03d31d2d8d001a344581","59bc03d31d2d8d001a344582","59bc03d31d2d8d001a344583","59bc284b7c3f420010f965e6"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0.0"},"category":{"_id":"59bc03d31d2d8d001a34457e","version":"59bc03d31d2d8d001a34457d","project":"578c4badbd223d2000cc1441","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-10-25T23:36:45.975Z","from_sync":false,"order":0,"slug":"basics","title":"Getting Started"},"user":"576c22a3808cf02b00d37419","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-15T19:16:50.790Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"AR only supported on iPhone 6s+ devices on iOS 11+\"\n}\n[/block]\nThis tutorial requires the completion of the [Quick Start](doc:quick-start).\n\nThis tutorial is a step by step guide for developing a simple AR app. Our goal by the end of this tutorial is to:\n\n1. Understand HelloWorldSceneAR.js\n2. Place a textured Box into the world\n3. Add a Smiley Emoji to the scene\n4. Select an ARPlane\n5. Add the emoji to the plane\n6. Add a shadow to the emoji\n7. Make the emoji draggable\n8. Animate the box\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Understanding HelloWorldSceneAR.js\"\n}\n[/block]\nOpen your test project in the Viro Media App (like you did in the [Quick Start (Mac/Linux)](doc:quick-start)) and select the **AR** option. You should see the following, \"Hello World\" in white overlay in your camera view:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/9a353c5-IMG_BAFBC32D0716-1.jpeg\",\n        \"IMG_BAFBC32D0716-1.jpeg\",\n        1104,\n        621,\n        \"#73899b\"\n      ],\n      \"sizing\": \"80\",\n      \"caption\": \"HelloWorldAR scene\"\n    }\n  ]\n}\n[/block]\nThe scene you are presented with is `HelloWorldSceneAR.js` which is set as the `initialScene` on the [ViroARSceneNavigator](doc:viroarscenenavigator) component in the `index.ios.js`, which serves as the entry point into your app on iOS (on Android, `index.android.js` would be your entry point).\n\nViro is built on top of React Native and uses React Native constructs to make it easy to create native AR applications. In addition to understanding Javascript, you will also need to understand some basic React concepts, like [JSX](https://facebook.github.io/react/docs/jsx-in-depth.html), [components](https://facebook.github.io/react/docs/react-component.html), [state](https://facebook.github.io/react-native/docs/state.html), and [props](https://facebook.github.io/react-native/docs/props.html). \n\nBelow is the code for **HelloWorldSceneAR**:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"'use strict';\\n\\nimport React, { Component } from 'react';\\n\\nimport {StyleSheet} from 'react-native';\\n\\nimport {\\n  ViroARScene,\\n  ViroText,\\n} from 'react-viro';\\n\\nvar HelloWorldSceneAR = React.createClass({\\n  getInitialState() {\\n    return {\\n      text : \\\"Initializing AR...\\\"\\n    };\\n  },\\n  render: function() {\\n    return (\\n      <ViroARScene onTrackingInitialized={()=>{this.setState({text : \\\"Hello World!\\\"})}}>\\n        <ViroText text={this.state.text} scale={[.5, .5, .5]} position={[0, 0, -1]} style={styles.helloWorldTextStyle} />\\n      </ViroARScene>\\n    );\\n  },\\n});\\n\\nvar styles = StyleSheet.create({\\n  helloWorldTextStyle: {\\n    fontFamily: 'Arial',\\n    fontSize: 30,\\n    color: '#ffffff',\\n    textAlignVertical: 'center',\\n    textAlign: 'center',\\n  },\\n});\\n\\nmodule.exports = HelloWorldSceneAR;\",\n      \"language\": \"javascript\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nLet's see what's happening in the code above...\n\n## Importing Components\nThe code begins by importing React, ```StyleSheet``` from React Native and react-viro components that the app will use. In this app we use ```ViroARScene``` and ```ViroText```.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"'use strict';\\n\\nimport React, { Component } from 'react';\\n\\nimport {StyleSheet} from 'react-native';\\n\\nimport {\\n  ViroARScene,\\n  ViroText,\\n} from 'react-viro';\\n  \\n...\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## render() method\nBelow the import code, we declare the HelloWorldSceneAR using React.createClass. This creates a react component that adheres to the [react component lifecycle](https://facebook.github.io/react/docs/react-component.html#the-component-lifecycle).\n\n```getInitialState()``` is the first method defined. It defines the initial state for variables in our class. It can take a few seconds before ARKit is initialized. With getInitialState(), we are displaying \"Initializing AR...\" until onTrackingInitialized is called.\n\n```render()``` is an important member of each react class, and in our case, determines how each scene is displayed. It's defined using [JSX](https://facebook.github.io/react/docs/jsx-in-depth.html) which is syntactically similar to HTML. In the section below we go through this method in detail.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"...\\n\\nvar HelloWorldSceneAR = React.createClass({\\n  getInitialState() {\\n    return {\\n      text : \\\"Initializing AR...\\\"\\n    };\\n  },\\n  render: function() {\\n    return (\\n      <ViroARScene onTrackingInitialized={()=>{this.setState({text : \\\"Hello World!\\\"})}}>\\n        <ViroText text={this.state.text} scale={[.5, .5, .5]} position={[0, 0, -1]} style={styles.helloWorldTextStyle} />\\n      </ViroARScene>\\n    );\\n  },\\n});\\n\\n...\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n* In the return statement, we declare the top level component: `ViroARScene`. Every AR scene must have a `ViroARScene` as its top-most element. All other components are children of `ViroARScene`. We use the callback prop, `onTrackingInitialized`, to set our text to \"Hello World\" once ARKit has initialized and invoked the function.\n    \n* `ViroText` is declared next. It displays the text \"Initializing AR...\" then \"Hello World\" at x,y,z position of [0,0,-1] with the font, font size and color specified by the `style` property. In our coordinate system, the viewer faces in the negative-Z direction, so providing a Z coordinate of -1 places the object in front of the viewer.\n    \n## Declaring Styles\nAfter the render method, we declare styles that can be used in our application. Styles generally represent layout properties for components. In our app, we declare a style named `helloWorldTextStyle` that describes the font type, color, size and alignment for our `ViroText` component.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var styles = StyleSheet.create({\\n  helloWorldTextStyle: {\\n    fontFamily: 'Arial',\\n    fontSize: 30,\\n    color: '#ffffff',\\n    textAlignVertical: 'center',\\n    textAlign: 'center',\\n  },\\n});\\n\\nmodule.exports = HelloWorldSceneAR;\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNow that we described how our scene works, let's see how we can expand upon it. \n[block:api-header]\n{\n  \"title\": \"Downloading Assets\"\n}\n[/block]\nThe first thing we need to do is to download assets that we'll be using for the tutorial, follow the steps below:\n- Download the bundle of [assets](https://s3-us-west-2.amazonaws.com/viro/Assets/res.zip)\n- Unzip the file and replace the `res` folder at `<path_to>/ViroSample/js/`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding Components to a Scene\"\n}\n[/block]\nLet's take our current HelloWorld scene and add a 3D Box above the \"Hello World\" text. We can do this by using the `ViroBox` component. To add a box to our scene we do the following:\n\nFirst we import `ViroBox` and `ViroMaterials` from `react-viro` so our import statements now look like: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import {\\n  ...\\n\\tViroBox,\\n  ViroMaterials,\\n} from 'react-viro';\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNext we need to add the box to our scene. The [`ViroBox` API Reference](doc:virobox) lets us know what properties we can set to customize our box.\n\nCopy the following code and add it below the `ViroText` component:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ViroBox position={[0, -.5, -1]} scale={[.3, .3, .1]} materials={[\\\"grid\\\"]} />\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n**Customizing the ViroBox**\n\nIn the above code, we set the `position` of the `ViroBox` to [0, -.5, -1] so that it sets beneath the \"Hello World\" text.\n\nWe then scale the `ViroBox` by [.3, .3, .1] to make it smaller as its default `width`, `height`, and `length` is 1 (meters).\n\nFinally, the `materials` property define the visual appearance of the object, such as its color, lighting model, etc. In this example, we set a material named `grid` on the `ViroBox`.\n\n**Defining a Material**\nBefore we can use a material like the aforementioned `grid`, we need to define it. Since we have already import `ViroMaterials`, we can simply add the following code beneath the styles declaration.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ViroMaterials.createMaterials({\\n  grid: {\\n    diffuseTexture: require('./res/grid_bg.jpg'),\\n  },\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nAs you can see, we defined a `grid` material containing `diffuseTexture` which points to the file `grid_bg.jpg` in the `res` directory.\n\nTwo things to note here:\n- The `require()` function is a special function provided in React that converts a filepath into a value that the platform can use to fetch the resource.\n- The argument to `require()` is a filepath and is relative to the location of the file (in this case both the `res/` directory and the `HelloWorldSceneAR.js` are in the same `ViroSample/js/` directory.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Not finding `grid_bg.jpg`?\",\n  \"body\": \"Make sure you followed the instructions under [Downloading Assets](docs:tutorial-ar#downloading-assets) to download and copy the assets we'll be using in this tutorial.\"\n}\n[/block]\nYour `HelloWorldSceneAR.js` should look similar to the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"'use strict';\\n\\nimport React, { Component } from 'react';\\n\\nimport {StyleSheet} from 'react-native';\\n\\nimport {\\n  ViroARScene,\\n  ViroText,\\n  ViroMaterials,\\n  ViroBox,\\n} from 'react-viro';\\n\\nvar HelloWorldSceneAR = React.createClass({\\n  getInitialState() {\\n    return {\\n      text : \\\"Initializing AR...\\\"\\n    };\\n  },\\n  render: function() {\\n    return (\\n      <ViroARScene onTrackingInitialized={()=>{this.setState({text : \\\"Hello World!\\\"})}}>\\n        <ViroText text={this.state.text} scale={[.5, .5, .5]} position={[0, 0, -1]} style={styles.helloWorldTextStyle} />\\n        <ViroBox position={[0, -.5, -1]}\\n          animation={{name: \\\"rotate\\\", run: true, loop: true}}\\n          scale={[.3, .3, .1]} materials={[\\\"grid\\\"]} />\\n      </ViroARScene>\\n    );\\n  },\\n});\\n\\nvar styles = StyleSheet.create({\\n  helloWorldTextStyle: {\\n    fontFamily: 'Arial',\\n    fontSize: 30,\\n    color: '#ffffff',\\n    textAlignVertical: 'center',\\n    textAlign: 'center',\\n  },\\n});\\n\\nViroMaterials.createMaterials({\\n  grid: {\\n    diffuseTexture: require('./res/grid_bg.jpg'),\\n  },\\n});\\n\\nmodule.exports = HelloWorldSceneAR;\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSave your `HelloWorldSceneAR.js` file and reload the app. You should now see a pink and grey cube under the Hello World text\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0019cfa-IMG_BEC77E650A4B-1.jpeg\",\n        \"IMG_BEC77E650A4B-1.jpeg\",\n        1242,\n        2208,\n        \"#46535e\"\n      ]\n    }\n  ]\n}\n[/block]\nTo reload your file, simply shake your device and a debug menu will appear, as shown below. Tap on \"Reload\" and a screen to choose AR or VR will appear. Tap on AR and your changes will appear.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/51ccf4d-viro_debug_hud.jpg\",\n        \"viro_debug_hud.jpg\",\n        800,\n        450,\n        \"#c4c4c5\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding a 3D Object to the scene\"\n}\n[/block]\nNow let's add a 3D Object to the scene. There should be a folder in your `res` folder called \"emoji_smile\". We will be using these files to add a 3D emoji to the scene.\n\n**Add new components**\nWe first need to import the components we'll be using:  `Viro3DObject`, `ViroAmbientLight` and `ViroSpotLight`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import {\\n  ViroARScene,\\n  ViroText,\\n  ViroMaterials,\\n\\tViroBox,\\n  Viro3DObject,\\n  ViroAmbientLight,\\n  ViroSpotLight,\\n} from 'react-viro';\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNext we need to add the `Viro3DObject` and lights to our scene. Copy the code below and paste it below the `ViroBox` component within the `ViroARScene`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\t\\t\\t\\t<ViroAmbientLight color={\\\"#aaaaaa\\\"} />\\n        <ViroSpotLight\\n          innerAngle={5}\\n          outerAngle={90}\\n          direction={[0,-1,-.2]}\\n          position={[0, 3, 1]}\\n          color=\\\"#ffffff\\\"\\n          castsShadow={true} />\\n        <Viro3DObject\\n          source={require('./res/emoji_smile/emoji_smile.vrx')}\\n          position={[-.5, -.5, -.5]}\\n          scale={[.2, .2, .2]}\\n          type=\\\"VRX\\\" />\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSave your file and reload the Testbed app. You should see the scene below. Move around if you are unable to see all the components at first as they might be to your left.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/74a0078-IMG_2934.PNG\",\n        \"IMG_2934.PNG\",\n        1242,\n        2208,\n        \"#323132\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Using ViroARPlane\"\n}\n[/block]\nIn an AR app, the device's camera is used to present a live, onscreen view of the physical world. Three-dimensional virtual objects are superimposed over this view, creating the illusion that they actually exist. \n\nOne method for placing objects in the real world is by using the `ViroARPlane` or `ViroARPlaneSelector` component. When the AR system detects a plane, the Viro platform attempts to attach it to any declared `ViroARPlane` components and continually keeps the virtual plane anchored to the detected real-world plane. On the other hand, the `ViroARPlaneSelector` component enables developers to allow their users to select the plane that they want the developer to use.\n\nTo see how it works, let's add a `ViroARPlaneSelector` into our scene. First, add `ViroARPlaneSelector` as a new component as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import {\\n  ...\\n  ViroARPlaneSelector,\\n} from 'react-viro';\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNext add a `ViroARPlaneSelector` by pasting the following code into your `ViroARScene` component.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ViroARPlaneSelector />\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSave your file and reload the testbed app. In addition to the previous scene, you should now see planes appear as you move around your room. In our real world, both the table and floor plane were detected as shown below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0c2779b-IMG_805765C25B14-1.jpeg\",\n        \"IMG_805765C25B14-1.jpeg\",\n        1242,\n        2208,\n        \"#989390\"\n      ]\n    }\n  ]\n}\n[/block]\nIf you try \"selecting\" a plane by tapping on it, they will simply all disappear as nothing was added within the `ViroARPlaneSelector`, in the next section, we'll show you how to add a component to it.\n[block:api-header]\n{\n  \"title\": \"Add a 3D Object to the Plane\"\n}\n[/block]\nPreviously, when we added our emoji to the scene, it was at a fixed position as shown {[-.5, -.5, -.5]} as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Viro3DObject\\n  source={require('./res/emoji_smile/emoji_smile.vrx')}\\n  position={[-.5, -.5, -.5]}\\n  scale={[.2, .2, .2]}\\n  type=\\\"VRX\\\" />\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nWith AR, we often times want objects to be placed in relation to the real world. Using the planes we identified earlier, let's place our emoji on a plane. Replace the `Viro3DObject` code above in your `HelloWorldSceneAR.js` file with the code below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ViroARPlaneSelector>\\n  <Viro3DObject\\n    source={require('./res/emoji_smile/emoji_smile.vrx')}\\n    position={[0, .5, 0]}\\n    scale={[.2, .2, .2]}\\n    type=\\\"VRX\\\" />\\n</ViroARPlaneSelector>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNotice that we also changed the `position` of the emoji to [0, .5, 0]. This is because the emoji's center is within the emoji itself, so to make it sit \"on\" the plane, we need to shift it slightly above where the plane is\n\nSave the file and reload the testbed app.\n\nNow that we have placed the 3D Object inside the `ViroARPlaneSelector`, when a plane is tapped, the emoji will be placed on the selected plane and the other ones will disappear.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2909904-IMG_2936.PNG\",\n        \"IMG_2936.PNG\",\n        1242,\n        2208,\n        \"#9c9285\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Interactions and Animations\"\n}\n[/block]\nOne of the great things about AR that users can move about their world to view and interact with objects from different angles. Let's add interaction to the emoji and some movement to the box.\n\nFirst let's make the emoji draggable so that it can be moved with the drag gesture. First we need to import another component `ViroNode`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import {\\n  ...\\n  ViroNode,\\n} from 'react-viro';\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIn the previous step, we placed our emoji within a `ViroARPlaneSelector` component as shown below.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ViroARPlaneSelector>\\n  <Viro3DObject\\n    source={require('./res/emoji_smile/emoji_smile.vrx')}\\n    position={[0, .5, 0]}\\n    scale={[.2, .2, .2]}\\n    type=\\\"VRX\\\" />\\n</ViroARPlaneSelector>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nTo make our emoji drag along real-world surfaces, we need to replace `ViroARPlaneSelector` with a `ViroNode`, set the `dragType` to \"FixedToWorld\", and add an empty anonymous function to let the platform know that we want this object to drag.\n\nReplace the above code block with the one below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ViroNode position={[0,-1,0]} dragType=\\\"FixedToWorld\\\" onDrag={()=>{}} >\\n  <Viro3DObject\\n    source={require('./res/emoji_smile/emoji_smile.vrx')}\\n    position={[0, .5, 0]}\\n    scale={[.2, .2, .2]}\\n    type=\\\"VRX\\\" />\\n</ViroNode>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSave your file and reload the testbed app.\n\nThe emoji should now appear right under you. You should now be able to touch and drag the emoji around the scene, notice how it moves along real world surfaces.\n\n## Animation\n\nFinally, let's add some movement to the box. First, we need to import `ViroAnimations`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import {\\n  ...\\n  ViroAnimations,\\n} from 'react-viro'\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNext, replace the `ViroBox` component with the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ViroBox position={[0, -.5, -1]} scale={[.3, .3, .1]} materials={[\\\"grid\\\"]} animation={{name: \\\"rotate\\\", run: true, loop: true}}/>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nAs you can see, we added a new property `animation` with the value `{name: \"rotate\", run: true, loop: true}`. The name refers to an animation we will register in the next step like we did for [ViroMaterials](doc:materials) above.\n\nFind where we registered `ViroMaterials` (near the bottom of the file), copy and paste the following code below it:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ViroAnimations.registerAnimations({\\n  rotate: {\\n    properties: {\\n      rotateY: \\\"+=90\\\"\\n    },\\n    duration: 250, //.25 seconds\\n  },\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSave your file and reload the testbed app. You should now see \"Hello World\", a spinning box and be able to drag the emoji. An example of the complete final code is posted at the end of this tutorial.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e5c8290-IMG_E4A7470BB353-1.jpeg\",\n        \"IMG_E4A7470BB353-1.jpeg\",\n        1242,\n        2208,\n        \"#908a83\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Next Steps\"\n}\n[/block]\n## Continue Modifying the Scene\nYou should now have a basic overview for how the Viro platform works. Check out our [Code Samples](doc:code-samples) for other example apps, or continuing adding functionality on your own to the HelloWorldScene. For example:\n\n* Add an animation to other objects in the scene. Look at our [Animation Guide](doc:animation) for info on how to accomplish this.\n* Try adding shadows and illumination to the scene. Check out the [Lighting and Materials](doc:3d-scene-lighting) guide for details.\n[block:api-header]\n{\n  \"title\": \"HelloWorldSceneAR Tutorial - Final Code\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"'use strict';\\n\\nimport React, { Component } from 'react';\\n\\nimport {StyleSheet} from 'react-native';\\n\\nimport {\\n  ViroARScene,\\n  ViroText,\\n  ViroMaterials,\\n\\tViroBox,\\n  Viro3DObject,\\n  ViroAmbientLight,\\n  ViroSpotLight,\\n  ViroARPlaneSelector,\\n  ViroNode,\\n  ViroAnimations,\\n} from 'react-viro';\\n\\nvar HelloWorldSceneAR = React.createClass({\\n  getInitialState() {\\n    return {\\n      text : \\\"Initializing AR...\\\"\\n    };\\n  },\\n  render: function() {\\n    return (\\n      <ViroARScene onTrackingInitialized={()=>{this.setState({text : \\\"Hello World!\\\"})}}>\\n\\n        <ViroText text={this.state.text} scale={[.5, .5, .5]} position={[0, 0, -1]} style={styles.helloWorldTextStyle} />\\n\\n        <ViroBox position={[0, -.5, -1]} scale={[.3, .3, .1]} materials={[\\\"grid\\\"]} animation={{name: \\\"rotate\\\", run: true, loop: true}}/>\\n        \\n        <ViroAmbientLight color={\\\"#aaaaaa\\\"} />\\n\\n        <ViroSpotLight\\n          innerAngle={5}\\n          outerAngle={90}\\n          direction={[0,-1,-.2]}\\n          position={[0, 3, 1]}\\n          color=\\\"#ffffff\\\"\\n          castsShadow={true} />\\n\\n        <ViroNode position={[0,-1,0]} dragType=\\\"FixedToWorld\\\" onDrag={()=>{}} >\\n          <Viro3DObject\\n            source={require('./res/emoji_smile/emoji_smile.vrx')}\\n            position={[0, .5, 0]}\\n            scale={[.2, .2, .2]}\\n            type=\\\"VRX\\\" />\\n        </ViroNode>\\n\\n      </ViroARScene>\\n    );\\n  },\\n});\\n\\nvar styles = StyleSheet.create({\\n  helloWorldTextStyle: {\\n    fontFamily: 'Arial',\\n    fontSize: 30,\\n    color: '#ffffff',\\n    textAlignVertical: 'center',\\n    textAlign: 'center',\\n  },\\n});\\n\\nViroMaterials.createMaterials({\\n  grid: {\\n    diffuseTexture: require('./res/grid_bg.jpg'),\\n  },\\n});\\n\\nViroAnimations.registerAnimations({\\n  rotate: {\\n    properties: {\\n      rotateY: \\\"+=90\\\"\\n    },\\n    duration: 250, //.25 seconds\\n  },\\n});\\n\\nmodule.exports = HelloWorldSceneAR;\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"tutorial-ar","type":"basic","title":"Tutorial AR"}
[block:callout] { "type": "warning", "title": "AR only supported on iPhone 6s+ devices on iOS 11+" } [/block] This tutorial requires the completion of the [Quick Start](doc:quick-start). This tutorial is a step by step guide for developing a simple AR app. Our goal by the end of this tutorial is to: 1. Understand HelloWorldSceneAR.js 2. Place a textured Box into the world 3. Add a Smiley Emoji to the scene 4. Select an ARPlane 5. Add the emoji to the plane 6. Add a shadow to the emoji 7. Make the emoji draggable 8. Animate the box [block:api-header] { "type": "basic", "title": "Understanding HelloWorldSceneAR.js" } [/block] Open your test project in the Viro Media App (like you did in the [Quick Start (Mac/Linux)](doc:quick-start)) and select the **AR** option. You should see the following, "Hello World" in white overlay in your camera view: [block:image] { "images": [ { "image": [ "https://files.readme.io/9a353c5-IMG_BAFBC32D0716-1.jpeg", "IMG_BAFBC32D0716-1.jpeg", 1104, 621, "#73899b" ], "sizing": "80", "caption": "HelloWorldAR scene" } ] } [/block] The scene you are presented with is `HelloWorldSceneAR.js` which is set as the `initialScene` on the [ViroARSceneNavigator](doc:viroarscenenavigator) component in the `index.ios.js`, which serves as the entry point into your app on iOS (on Android, `index.android.js` would be your entry point). Viro is built on top of React Native and uses React Native constructs to make it easy to create native AR applications. In addition to understanding Javascript, you will also need to understand some basic React concepts, like [JSX](https://facebook.github.io/react/docs/jsx-in-depth.html), [components](https://facebook.github.io/react/docs/react-component.html), [state](https://facebook.github.io/react-native/docs/state.html), and [props](https://facebook.github.io/react-native/docs/props.html). Below is the code for **HelloWorldSceneAR**: [block:code] { "codes": [ { "code": "'use strict';\n\nimport React, { Component } from 'react';\n\nimport {StyleSheet} from 'react-native';\n\nimport {\n ViroARScene,\n ViroText,\n} from 'react-viro';\n\nvar HelloWorldSceneAR = React.createClass({\n getInitialState() {\n return {\n text : \"Initializing AR...\"\n };\n },\n render: function() {\n return (\n <ViroARScene onTrackingInitialized={()=>{this.setState({text : \"Hello World!\"})}}>\n <ViroText text={this.state.text} scale={[.5, .5, .5]} position={[0, 0, -1]} style={styles.helloWorldTextStyle} />\n </ViroARScene>\n );\n },\n});\n\nvar styles = StyleSheet.create({\n helloWorldTextStyle: {\n fontFamily: 'Arial',\n fontSize: 30,\n color: '#ffffff',\n textAlignVertical: 'center',\n textAlign: 'center',\n },\n});\n\nmodule.exports = HelloWorldSceneAR;", "language": "javascript", "name": null } ] } [/block] Let's see what's happening in the code above... ## Importing Components The code begins by importing React, ```StyleSheet``` from React Native and react-viro components that the app will use. In this app we use ```ViroARScene``` and ```ViroText```. [block:code] { "codes": [ { "code": "'use strict';\n\nimport React, { Component } from 'react';\n\nimport {StyleSheet} from 'react-native';\n\nimport {\n ViroARScene,\n ViroText,\n} from 'react-viro';\n \n...", "language": "javascript" } ] } [/block] ## render() method Below the import code, we declare the HelloWorldSceneAR using React.createClass. This creates a react component that adheres to the [react component lifecycle](https://facebook.github.io/react/docs/react-component.html#the-component-lifecycle). ```getInitialState()``` is the first method defined. It defines the initial state for variables in our class. It can take a few seconds before ARKit is initialized. With getInitialState(), we are displaying "Initializing AR..." until onTrackingInitialized is called. ```render()``` is an important member of each react class, and in our case, determines how each scene is displayed. It's defined using [JSX](https://facebook.github.io/react/docs/jsx-in-depth.html) which is syntactically similar to HTML. In the section below we go through this method in detail. [block:code] { "codes": [ { "code": "...\n\nvar HelloWorldSceneAR = React.createClass({\n getInitialState() {\n return {\n text : \"Initializing AR...\"\n };\n },\n render: function() {\n return (\n <ViroARScene onTrackingInitialized={()=>{this.setState({text : \"Hello World!\"})}}>\n <ViroText text={this.state.text} scale={[.5, .5, .5]} position={[0, 0, -1]} style={styles.helloWorldTextStyle} />\n </ViroARScene>\n );\n },\n});\n\n...", "language": "javascript" } ] } [/block] * In the return statement, we declare the top level component: `ViroARScene`. Every AR scene must have a `ViroARScene` as its top-most element. All other components are children of `ViroARScene`. We use the callback prop, `onTrackingInitialized`, to set our text to "Hello World" once ARKit has initialized and invoked the function. * `ViroText` is declared next. It displays the text "Initializing AR..." then "Hello World" at x,y,z position of [0,0,-1] with the font, font size and color specified by the `style` property. In our coordinate system, the viewer faces in the negative-Z direction, so providing a Z coordinate of -1 places the object in front of the viewer. ## Declaring Styles After the render method, we declare styles that can be used in our application. Styles generally represent layout properties for components. In our app, we declare a style named `helloWorldTextStyle` that describes the font type, color, size and alignment for our `ViroText` component. [block:code] { "codes": [ { "code": "var styles = StyleSheet.create({\n helloWorldTextStyle: {\n fontFamily: 'Arial',\n fontSize: 30,\n color: '#ffffff',\n textAlignVertical: 'center',\n textAlign: 'center',\n },\n});\n\nmodule.exports = HelloWorldSceneAR;", "language": "javascript" } ] } [/block] Now that we described how our scene works, let's see how we can expand upon it. [block:api-header] { "title": "Downloading Assets" } [/block] The first thing we need to do is to download assets that we'll be using for the tutorial, follow the steps below: - Download the bundle of [assets](https://s3-us-west-2.amazonaws.com/viro/Assets/res.zip) - Unzip the file and replace the `res` folder at `<path_to>/ViroSample/js/`. [block:api-header] { "type": "basic", "title": "Adding Components to a Scene" } [/block] Let's take our current HelloWorld scene and add a 3D Box above the "Hello World" text. We can do this by using the `ViroBox` component. To add a box to our scene we do the following: First we import `ViroBox` and `ViroMaterials` from `react-viro` so our import statements now look like: [block:code] { "codes": [ { "code": "import {\n ...\n\tViroBox,\n ViroMaterials,\n} from 'react-viro';", "language": "javascript" } ] } [/block] Next we need to add the box to our scene. The [`ViroBox` API Reference](doc:virobox) lets us know what properties we can set to customize our box. Copy the following code and add it below the `ViroText` component: [block:code] { "codes": [ { "code": "<ViroBox position={[0, -.5, -1]} scale={[.3, .3, .1]} materials={[\"grid\"]} />", "language": "javascript" } ] } [/block] **Customizing the ViroBox** In the above code, we set the `position` of the `ViroBox` to [0, -.5, -1] so that it sets beneath the "Hello World" text. We then scale the `ViroBox` by [.3, .3, .1] to make it smaller as its default `width`, `height`, and `length` is 1 (meters). Finally, the `materials` property define the visual appearance of the object, such as its color, lighting model, etc. In this example, we set a material named `grid` on the `ViroBox`. **Defining a Material** Before we can use a material like the aforementioned `grid`, we need to define it. Since we have already import `ViroMaterials`, we can simply add the following code beneath the styles declaration. [block:code] { "codes": [ { "code": "ViroMaterials.createMaterials({\n grid: {\n diffuseTexture: require('./res/grid_bg.jpg'),\n },\n});", "language": "javascript" } ] } [/block] As you can see, we defined a `grid` material containing `diffuseTexture` which points to the file `grid_bg.jpg` in the `res` directory. Two things to note here: - The `require()` function is a special function provided in React that converts a filepath into a value that the platform can use to fetch the resource. - The argument to `require()` is a filepath and is relative to the location of the file (in this case both the `res/` directory and the `HelloWorldSceneAR.js` are in the same `ViroSample/js/` directory. [block:callout] { "type": "warning", "title": "Not finding `grid_bg.jpg`?", "body": "Make sure you followed the instructions under [Downloading Assets](docs:tutorial-ar#downloading-assets) to download and copy the assets we'll be using in this tutorial." } [/block] Your `HelloWorldSceneAR.js` should look similar to the following: [block:code] { "codes": [ { "code": "'use strict';\n\nimport React, { Component } from 'react';\n\nimport {StyleSheet} from 'react-native';\n\nimport {\n ViroARScene,\n ViroText,\n ViroMaterials,\n ViroBox,\n} from 'react-viro';\n\nvar HelloWorldSceneAR = React.createClass({\n getInitialState() {\n return {\n text : \"Initializing AR...\"\n };\n },\n render: function() {\n return (\n <ViroARScene onTrackingInitialized={()=>{this.setState({text : \"Hello World!\"})}}>\n <ViroText text={this.state.text} scale={[.5, .5, .5]} position={[0, 0, -1]} style={styles.helloWorldTextStyle} />\n <ViroBox position={[0, -.5, -1]}\n animation={{name: \"rotate\", run: true, loop: true}}\n scale={[.3, .3, .1]} materials={[\"grid\"]} />\n </ViroARScene>\n );\n },\n});\n\nvar styles = StyleSheet.create({\n helloWorldTextStyle: {\n fontFamily: 'Arial',\n fontSize: 30,\n color: '#ffffff',\n textAlignVertical: 'center',\n textAlign: 'center',\n },\n});\n\nViroMaterials.createMaterials({\n grid: {\n diffuseTexture: require('./res/grid_bg.jpg'),\n },\n});\n\nmodule.exports = HelloWorldSceneAR;", "language": "javascript" } ] } [/block] Save your `HelloWorldSceneAR.js` file and reload the app. You should now see a pink and grey cube under the Hello World text [block:image] { "images": [ { "image": [ "https://files.readme.io/0019cfa-IMG_BEC77E650A4B-1.jpeg", "IMG_BEC77E650A4B-1.jpeg", 1242, 2208, "#46535e" ] } ] } [/block] To reload your file, simply shake your device and a debug menu will appear, as shown below. Tap on "Reload" and a screen to choose AR or VR will appear. Tap on AR and your changes will appear. [block:image] { "images": [ { "image": [ "https://files.readme.io/51ccf4d-viro_debug_hud.jpg", "viro_debug_hud.jpg", 800, 450, "#c4c4c5" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Adding a 3D Object to the scene" } [/block] Now let's add a 3D Object to the scene. There should be a folder in your `res` folder called "emoji_smile". We will be using these files to add a 3D emoji to the scene. **Add new components** We first need to import the components we'll be using: `Viro3DObject`, `ViroAmbientLight` and `ViroSpotLight`. [block:code] { "codes": [ { "code": "import {\n ViroARScene,\n ViroText,\n ViroMaterials,\n\tViroBox,\n Viro3DObject,\n ViroAmbientLight,\n ViroSpotLight,\n} from 'react-viro';", "language": "javascript" } ] } [/block] Next we need to add the `Viro3DObject` and lights to our scene. Copy the code below and paste it below the `ViroBox` component within the `ViroARScene`. [block:code] { "codes": [ { "code": "\t\t\t\t<ViroAmbientLight color={\"#aaaaaa\"} />\n <ViroSpotLight\n innerAngle={5}\n outerAngle={90}\n direction={[0,-1,-.2]}\n position={[0, 3, 1]}\n color=\"#ffffff\"\n castsShadow={true} />\n <Viro3DObject\n source={require('./res/emoji_smile/emoji_smile.vrx')}\n position={[-.5, -.5, -.5]}\n scale={[.2, .2, .2]}\n type=\"VRX\" />", "language": "javascript" } ] } [/block] Save your file and reload the Testbed app. You should see the scene below. Move around if you are unable to see all the components at first as they might be to your left. [block:image] { "images": [ { "image": [ "https://files.readme.io/74a0078-IMG_2934.PNG", "IMG_2934.PNG", 1242, 2208, "#323132" ] } ] } [/block] [block:api-header] { "title": "Using ViroARPlane" } [/block] In an AR app, the device's camera is used to present a live, onscreen view of the physical world. Three-dimensional virtual objects are superimposed over this view, creating the illusion that they actually exist. One method for placing objects in the real world is by using the `ViroARPlane` or `ViroARPlaneSelector` component. When the AR system detects a plane, the Viro platform attempts to attach it to any declared `ViroARPlane` components and continually keeps the virtual plane anchored to the detected real-world plane. On the other hand, the `ViroARPlaneSelector` component enables developers to allow their users to select the plane that they want the developer to use. To see how it works, let's add a `ViroARPlaneSelector` into our scene. First, add `ViroARPlaneSelector` as a new component as shown below: [block:code] { "codes": [ { "code": "import {\n ...\n ViroARPlaneSelector,\n} from 'react-viro';", "language": "javascript" } ] } [/block] Next add a `ViroARPlaneSelector` by pasting the following code into your `ViroARScene` component. [block:code] { "codes": [ { "code": "<ViroARPlaneSelector />", "language": "javascript" } ] } [/block] Save your file and reload the testbed app. In addition to the previous scene, you should now see planes appear as you move around your room. In our real world, both the table and floor plane were detected as shown below: [block:image] { "images": [ { "image": [ "https://files.readme.io/0c2779b-IMG_805765C25B14-1.jpeg", "IMG_805765C25B14-1.jpeg", 1242, 2208, "#989390" ] } ] } [/block] If you try "selecting" a plane by tapping on it, they will simply all disappear as nothing was added within the `ViroARPlaneSelector`, in the next section, we'll show you how to add a component to it. [block:api-header] { "title": "Add a 3D Object to the Plane" } [/block] Previously, when we added our emoji to the scene, it was at a fixed position as shown {[-.5, -.5, -.5]} as shown below: [block:code] { "codes": [ { "code": "<Viro3DObject\n source={require('./res/emoji_smile/emoji_smile.vrx')}\n position={[-.5, -.5, -.5]}\n scale={[.2, .2, .2]}\n type=\"VRX\" />", "language": "javascript" } ] } [/block] With AR, we often times want objects to be placed in relation to the real world. Using the planes we identified earlier, let's place our emoji on a plane. Replace the `Viro3DObject` code above in your `HelloWorldSceneAR.js` file with the code below: [block:code] { "codes": [ { "code": "<ViroARPlaneSelector>\n <Viro3DObject\n source={require('./res/emoji_smile/emoji_smile.vrx')}\n position={[0, .5, 0]}\n scale={[.2, .2, .2]}\n type=\"VRX\" />\n</ViroARPlaneSelector>", "language": "javascript" } ] } [/block] Notice that we also changed the `position` of the emoji to [0, .5, 0]. This is because the emoji's center is within the emoji itself, so to make it sit "on" the plane, we need to shift it slightly above where the plane is Save the file and reload the testbed app. Now that we have placed the 3D Object inside the `ViroARPlaneSelector`, when a plane is tapped, the emoji will be placed on the selected plane and the other ones will disappear. [block:image] { "images": [ { "image": [ "https://files.readme.io/2909904-IMG_2936.PNG", "IMG_2936.PNG", 1242, 2208, "#9c9285" ] } ] } [/block] [block:api-header] { "title": "Interactions and Animations" } [/block] One of the great things about AR that users can move about their world to view and interact with objects from different angles. Let's add interaction to the emoji and some movement to the box. First let's make the emoji draggable so that it can be moved with the drag gesture. First we need to import another component `ViroNode`: [block:code] { "codes": [ { "code": "import {\n ...\n ViroNode,\n} from 'react-viro';\n", "language": "javascript" } ] } [/block] In the previous step, we placed our emoji within a `ViroARPlaneSelector` component as shown below. [block:code] { "codes": [ { "code": "<ViroARPlaneSelector>\n <Viro3DObject\n source={require('./res/emoji_smile/emoji_smile.vrx')}\n position={[0, .5, 0]}\n scale={[.2, .2, .2]}\n type=\"VRX\" />\n</ViroARPlaneSelector>", "language": "javascript" } ] } [/block] To make our emoji drag along real-world surfaces, we need to replace `ViroARPlaneSelector` with a `ViroNode`, set the `dragType` to "FixedToWorld", and add an empty anonymous function to let the platform know that we want this object to drag. Replace the above code block with the one below: [block:code] { "codes": [ { "code": "<ViroNode position={[0,-1,0]} dragType=\"FixedToWorld\" onDrag={()=>{}} >\n <Viro3DObject\n source={require('./res/emoji_smile/emoji_smile.vrx')}\n position={[0, .5, 0]}\n scale={[.2, .2, .2]}\n type=\"VRX\" />\n</ViroNode>", "language": "javascript" } ] } [/block] Save your file and reload the testbed app. The emoji should now appear right under you. You should now be able to touch and drag the emoji around the scene, notice how it moves along real world surfaces. ## Animation Finally, let's add some movement to the box. First, we need to import `ViroAnimations` [block:code] { "codes": [ { "code": "import {\n ...\n ViroAnimations,\n} from 'react-viro'", "language": "javascript" } ] } [/block] Next, replace the `ViroBox` component with the following: [block:code] { "codes": [ { "code": "<ViroBox position={[0, -.5, -1]} scale={[.3, .3, .1]} materials={[\"grid\"]} animation={{name: \"rotate\", run: true, loop: true}}/>", "language": "javascript" } ] } [/block] As you can see, we added a new property `animation` with the value `{name: "rotate", run: true, loop: true}`. The name refers to an animation we will register in the next step like we did for [ViroMaterials](doc:materials) above. Find where we registered `ViroMaterials` (near the bottom of the file), copy and paste the following code below it: [block:code] { "codes": [ { "code": "ViroAnimations.registerAnimations({\n rotate: {\n properties: {\n rotateY: \"+=90\"\n },\n duration: 250, //.25 seconds\n },\n});", "language": "javascript" } ] } [/block] Save your file and reload the testbed app. You should now see "Hello World", a spinning box and be able to drag the emoji. An example of the complete final code is posted at the end of this tutorial. [block:image] { "images": [ { "image": [ "https://files.readme.io/e5c8290-IMG_E4A7470BB353-1.jpeg", "IMG_E4A7470BB353-1.jpeg", 1242, 2208, "#908a83" ] } ] } [/block] [block:api-header] { "title": "Next Steps" } [/block] ## Continue Modifying the Scene You should now have a basic overview for how the Viro platform works. Check out our [Code Samples](doc:code-samples) for other example apps, or continuing adding functionality on your own to the HelloWorldScene. For example: * Add an animation to other objects in the scene. Look at our [Animation Guide](doc:animation) for info on how to accomplish this. * Try adding shadows and illumination to the scene. Check out the [Lighting and Materials](doc:3d-scene-lighting) guide for details. [block:api-header] { "title": "HelloWorldSceneAR Tutorial - Final Code" } [/block] [block:code] { "codes": [ { "code": "'use strict';\n\nimport React, { Component } from 'react';\n\nimport {StyleSheet} from 'react-native';\n\nimport {\n ViroARScene,\n ViroText,\n ViroMaterials,\n\tViroBox,\n Viro3DObject,\n ViroAmbientLight,\n ViroSpotLight,\n ViroARPlaneSelector,\n ViroNode,\n ViroAnimations,\n} from 'react-viro';\n\nvar HelloWorldSceneAR = React.createClass({\n getInitialState() {\n return {\n text : \"Initializing AR...\"\n };\n },\n render: function() {\n return (\n <ViroARScene onTrackingInitialized={()=>{this.setState({text : \"Hello World!\"})}}>\n\n <ViroText text={this.state.text} scale={[.5, .5, .5]} position={[0, 0, -1]} style={styles.helloWorldTextStyle} />\n\n <ViroBox position={[0, -.5, -1]} scale={[.3, .3, .1]} materials={[\"grid\"]} animation={{name: \"rotate\", run: true, loop: true}}/>\n \n <ViroAmbientLight color={\"#aaaaaa\"} />\n\n <ViroSpotLight\n innerAngle={5}\n outerAngle={90}\n direction={[0,-1,-.2]}\n position={[0, 3, 1]}\n color=\"#ffffff\"\n castsShadow={true} />\n\n <ViroNode position={[0,-1,0]} dragType=\"FixedToWorld\" onDrag={()=>{}} >\n <Viro3DObject\n source={require('./res/emoji_smile/emoji_smile.vrx')}\n position={[0, .5, 0]}\n scale={[.2, .2, .2]}\n type=\"VRX\" />\n </ViroNode>\n\n </ViroARScene>\n );\n },\n});\n\nvar styles = StyleSheet.create({\n helloWorldTextStyle: {\n fontFamily: 'Arial',\n fontSize: 30,\n color: '#ffffff',\n textAlignVertical: 'center',\n textAlign: 'center',\n },\n});\n\nViroMaterials.createMaterials({\n grid: {\n diffuseTexture: require('./res/grid_bg.jpg'),\n },\n});\n\nViroAnimations.registerAnimations({\n rotate: {\n properties: {\n rotateY: \"+=90\"\n },\n duration: 250, //.25 seconds\n },\n});\n\nmodule.exports = HelloWorldSceneAR;\n", "language": "javascript" } ] } [/block]