{"_id":"5b36797811baf70003a15375","category":{"_id":"5b36797811baf70003a1535f","version":"5b36797811baf70003a153e5","project":"578c4badbd223d2000cc1441","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-18T21:08:45.730Z","from_sync":false,"order":3,"slug":"develop","title":"Basics"},"project":"578c4badbd223d2000cc1441","user":"579a69d53de0a217007eda56","parentDoc":null,"version":{"_id":"5b36797811baf70003a153e5","project":"578c4badbd223d2000cc1441","__v":0,"forked_from":"5b17376c3b44af00030764f0","createdAt":"2018-04-23T20:03:35.726Z","releaseDate":"2018-04-23T20:03:35.726Z","categories":["5b36797811baf70003a1535c","5b36797811baf70003a1535d","5b36797811baf70003a1535e","5b36797811baf70003a1535f","5b36797811baf70003a15360","5b36797811baf70003a15361","5b36797811baf70003a15362","5b36797811baf70003a15363","5b36797811baf70003a15364"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.8.1","version":"2.8.1"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-24T22:59:16.269Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"The ```<Viro3DObject>``` component enables loading 3D objects (also known as models or meshes) into a scene. \n\nThe ```<Viro3DObject>``` defines the *structure* of the 3D object: its vertices, faces, and texture coordinates. The scene graph, or ```<ViroNode>``` node hierarchy, determines the *orientation and placement* of the object. And finally, the *appearance* of the object is defined by its materials.\n\n# Loading 3D Objects\n\nViro supports loading 3D models in FBX and OBJ formats. Viro will load the geometry, textures, and  lighting parameters in the file. For FBX Viro will additionally load all installed skeletal animations. OBJ files are loaded directly by setting the ```source``` attribute of ```<Viro3DObject>```, while FBX files need to converted into Viro's own [VRX format](#section-fbx). \n\n3D models must be loaded from the application bundle. The following snippet shows how a model of the human heart would be loaded, for example. The ```position``` attribute positions the object relative to the coordinate system of its parent ```<ViroNode>```, and the ```materials``` attribute sets the materials that should be used.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Viro3DObject source={require('./res/heart.obj')}\\n                      position={[-0.0, -5.5, -1.15]}\\n                      materials={[\\\"heart\\\"]}\\n                      type=\\\"OBJ\\\" />\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n# Orientation and Placement\n\nThe node hierarchy and its transforms determine how 3D objects are positioned in the scene. See the [Scene Graph](doc:scenes#scene-graph) guide for more information.\n\n# Materials\n\nMaterials define the appearance of 3D objects. Materials control how an object responds to light. For detailed information see the [Lighting and Materials](doc:3d-scene-lighting) guide.\n\nFor OBJ models, materials can either be explicitly set (as in the example above), or they can be loaded via an MTL file. MTL is an extension of the OBJ file format, that allows material properties to be set for each surface of a model. To load an OBJ with an associated MTL file, the MTL file and all of its associated textures must be specified, as in the following example:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Viro3DObject source={require('./res/model.obj')}\\n           resources={[require('./res/model.mtl'),\\n                       require('./res/texture1.jpg'),\\n                       require('./res/texture2.jpg'),\\n                       require('./res/texture3.jpg')]}\\n           position={[0.0, 0.0, -10]}\\n           scale={[0.1, 0.1, 0.1]}\\n           type=\\\"OBJ\\\"\\n/>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNote that the OBJ file itself already references the specified MTL file and textures, but we must include them in the resources array in the ```<Viro3DObject>``` so that Viro knows to package these resources with your application.\n\n# Callbacks\n\nOBJ loading is performed asynchronously, so as not to introduce lag into your application. Viro provides callbacks to respond to each step of the OBJ loading process. You can register functions to listen for load start, load end, and loading errors. The following example illustrates all three callbacks, printing out a message to the console on receipt of each event.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var OBJTest = React.createClass({\\n  render: function() {\\n    <ViroScene>\\n  \\t\\t<Viro3DObject source={require('./res/model.obj')}\\n           resources={[require('./res/model.mtl'),\\n                       require('./res/texture1.jpg'),\\n                       require('./res/texture2.jpg'),\\n                       require('./res/texture3.jpg')]}\\n           type=\\\"OBJ\\\"\\n           position={[0.0, 0.0, -10]}\\n           scale={[0.1, 0.1, 0.1]}\\n           onLoadStart={this._onLoadStart}\\n           onLoadEnd={this._onLoadEnd}\\n           onError={this._onError}     \\n      />\\n    </ViroScene>\\n  },\\n  \\n  _onLoadStart() {\\n     console.log(\\\"OBJ loading has started\\\"); \\n  }\\n  _onLoadEnd() {\\n     console.log(\\\"OBJ loading has finished\\\");\\n  },\\n  _onError(event) {\\n    console.log(\\\"OBJ loading failed with error: \\\" + event.nativeEvent.error);\\n  },\\n});\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n# FBX\n\nFBX is an expansive and flexible 3D model format supported by most 3D authoring software. To load FBX files, use the ViroFBX script to convert the FBX file into a VRX file. The VRX file can then be loaded using ```<Viro3DObject>```. The ViroFBX script can found in your project's ````node_modules/react-viro/bin```` directory. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Mac OSX Support Only\",\n  \"body\": \"Currently the ViroFBX tool runs only on Mac OS X. Support for other platforms is on the way.\"\n}\n[/block]\nThe ViroFBX script can be found [here](https://s3-us-west-2.amazonaws.com/virocore/1_5_0/ViroFBX.zip).\n\nThe following example shows how to convert a model into VRX format:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"./ViroFBX path/to/model.fbx path/to/model.vrx\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nIn the example above, ```path/to/model.fbx``` is the path to the FBX file to convert, and ```path/to/model.vrx``` is the path to the VRX file to create. Once the VRX file is created, it can be loaded into an application with ```<Viro3DObject>```. Again, remember to place the model's associated textures in the same directory as the VRX file. Below is a simple example for loading a VRX file. Notice type is set to VRX here:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Viro3DObject source={require('./res/model.vrx')}\\n           resources={[require('./res/texture1.jpg'),\\n                       require('./res/texture2.jpg'),\\n                       require('./res/texture3.jpg')]}\\n           position={[0.0, 0.0, -10]}\\n           scale={[0.1, 0.1, 0.1]}\\n           type=\\\"VRX\\\"\\n/>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Model Not Appearing?\",\n  \"body\": \"You may need to add a Light to your scene. Try adding an Ambient light to see if your model appears:\\n```\\n<ViroAmbientLight color=\\\"#FFFFFF\\\" />\\n```\\nSee the [Lighting and Materials](doc:3d-scene-lighting) guide for more details.\"\n}\n[/block]\n# Skeletal Animation\n\nFBX models support skeletal animation. Skeletal animation is a hierarchical technique for animating complex geometries like humanoids. Viro supports these animations through its standard animation system. To run a skeletal animation, simply set the animation's name to the name given to the animation in the FBX file. For example, if the FBX file had an animation called \"Take 001\", you would run the animation like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Viro3DObject source={require('./res/model.vrx')}\\n           resources={[require('./res/texture1.jpg'),\\n                       require('./res/texture2.jpg'),\\n                       require('./res/texture3.jpg')]}\\n           position={[0.0, 0.0, -10]}\\n           scale={[0.1, 0.1, 0.1]}\\n           type=\\\"VRX\\\"\\n           animation={{name:'Take 001',\\n                      run:true,\\n                      loop:true,\\n                     delay:1000}}\\n/>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nFor more information on animations, see the [Animation](doc:animation) guide.\n\n# GLTF\n\nThe GL Transmission Format (glTF) is an API-neutral runtime asset delivery format. glTF bridges the gap between 3D content creation tools and modern 3D applications by providing an efficient, extensible, and interoperable format for the transmission and loading of 3D content. Viro currently supports gLTF 2.0. \n\n## glTF Model Format\nglTF assets are represented by the following 3 subcomponents:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/517c2d6-files.png\",\n        \"files.png\",\n        480,\n        235,\n        \"#f1edf1\"\n      ]\n    }\n  ]\n}\n[/block]\n1. A JSON-formatted file (.gltf) containing a full scene description: node hierarchy, materials, cameras, as well as descriptor information for meshes, animations, and other constructs\n2. Binary files (.bin) containing geometry and animation data, and other buffer-based data\n3. Image files (.jpg, .png) for textures\n\n## Loading glTF Models\n\nThere are 3 ways you can provide your glTF data to Viro to be rendered:\n1. Import the basic 3 components individually: The .gltf, its corresponding binary, and its image files.\n2. Import a single .gltf file, where both the binary and image data are embedded into the .gltf file as Base64-encoded data.\n3. Import a single [.glb file](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#glb-file-format-specification) that represents all required glTF components in a raw binary format. \n\nLike FBX, you can use the ```<Viro3DObject>``` component to load a glTF model into your scene. When loading glTF files, set the ```type``` property to either \"GLTF\" (for options 1 and 2 above), or \"GLB\" (for option 3: raw glTF binary). \n\nIt is also **important** to note that any related glTF assets (like binary data or image files) are always referenced by the URI's specified within the glTF file. Relative paths are with respect to the location of the glTF file.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"At the moment, Viro supports rendering static 2.0 glTF models. We are also currently in the process of implementing the full support for the complete set of gLTF features, so stay tuned! :) \\n\\nIncoming features includes:\\n- GLTF Animations (Skeletal and Non-Skeletal)\\n- Support for additional gLTF Extensions.\\n- Emissive Maps\\n- Sparse Accessor Data Formats\\n- Non-indexed mesh rendering (drawArray rendering)\\n- Additional Primitive Modes (Line_Loop & Triangle_Fan)\\n- Material Alpha Mask Mode\\n- Additional Min / Mag Filter modes\\n- Double sided rendering\\n- Baked in gLTF Camera\",\n  \"title\": \"Incoming GLTF features and known limitations\"\n}\n[/block]","excerpt":"Working with 3D content","slug":"3d-objects","type":"basic","title":"3D Objects"}

3D Objects

Working with 3D content

The ```<Viro3DObject>``` component enables loading 3D objects (also known as models or meshes) into a scene. The ```<Viro3DObject>``` defines the *structure* of the 3D object: its vertices, faces, and texture coordinates. The scene graph, or ```<ViroNode>``` node hierarchy, determines the *orientation and placement* of the object. And finally, the *appearance* of the object is defined by its materials. # Loading 3D Objects Viro supports loading 3D models in FBX and OBJ formats. Viro will load the geometry, textures, and lighting parameters in the file. For FBX Viro will additionally load all installed skeletal animations. OBJ files are loaded directly by setting the ```source``` attribute of ```<Viro3DObject>```, while FBX files need to converted into Viro's own [VRX format](#section-fbx). 3D models must be loaded from the application bundle. The following snippet shows how a model of the human heart would be loaded, for example. The ```position``` attribute positions the object relative to the coordinate system of its parent ```<ViroNode>```, and the ```materials``` attribute sets the materials that should be used. [block:code] { "codes": [ { "code": "<Viro3DObject source={require('./res/heart.obj')}\n position={[-0.0, -5.5, -1.15]}\n materials={[\"heart\"]}\n type=\"OBJ\" />", "language": "javascript" } ] } [/block] # Orientation and Placement The node hierarchy and its transforms determine how 3D objects are positioned in the scene. See the [Scene Graph](doc:scenes#scene-graph) guide for more information. # Materials Materials define the appearance of 3D objects. Materials control how an object responds to light. For detailed information see the [Lighting and Materials](doc:3d-scene-lighting) guide. For OBJ models, materials can either be explicitly set (as in the example above), or they can be loaded via an MTL file. MTL is an extension of the OBJ file format, that allows material properties to be set for each surface of a model. To load an OBJ with an associated MTL file, the MTL file and all of its associated textures must be specified, as in the following example: [block:code] { "codes": [ { "code": "<Viro3DObject source={require('./res/model.obj')}\n resources={[require('./res/model.mtl'),\n require('./res/texture1.jpg'),\n require('./res/texture2.jpg'),\n require('./res/texture3.jpg')]}\n position={[0.0, 0.0, -10]}\n scale={[0.1, 0.1, 0.1]}\n type=\"OBJ\"\n/>", "language": "javascript" } ] } [/block] Note that the OBJ file itself already references the specified MTL file and textures, but we must include them in the resources array in the ```<Viro3DObject>``` so that Viro knows to package these resources with your application. # Callbacks OBJ loading is performed asynchronously, so as not to introduce lag into your application. Viro provides callbacks to respond to each step of the OBJ loading process. You can register functions to listen for load start, load end, and loading errors. The following example illustrates all three callbacks, printing out a message to the console on receipt of each event. [block:code] { "codes": [ { "code": "var OBJTest = React.createClass({\n render: function() {\n <ViroScene>\n \t\t<Viro3DObject source={require('./res/model.obj')}\n resources={[require('./res/model.mtl'),\n require('./res/texture1.jpg'),\n require('./res/texture2.jpg'),\n require('./res/texture3.jpg')]}\n type=\"OBJ\"\n position={[0.0, 0.0, -10]}\n scale={[0.1, 0.1, 0.1]}\n onLoadStart={this._onLoadStart}\n onLoadEnd={this._onLoadEnd}\n onError={this._onError} \n />\n </ViroScene>\n },\n \n _onLoadStart() {\n console.log(\"OBJ loading has started\"); \n }\n _onLoadEnd() {\n console.log(\"OBJ loading has finished\");\n },\n _onError(event) {\n console.log(\"OBJ loading failed with error: \" + event.nativeEvent.error);\n },\n});\n", "language": "javascript" } ] } [/block] # FBX FBX is an expansive and flexible 3D model format supported by most 3D authoring software. To load FBX files, use the ViroFBX script to convert the FBX file into a VRX file. The VRX file can then be loaded using ```<Viro3DObject>```. The ViroFBX script can found in your project's ````node_modules/react-viro/bin```` directory. [block:callout] { "type": "info", "title": "Mac OSX Support Only", "body": "Currently the ViroFBX tool runs only on Mac OS X. Support for other platforms is on the way." } [/block] The ViroFBX script can be found [here](https://s3-us-west-2.amazonaws.com/virocore/1_5_0/ViroFBX.zip). The following example shows how to convert a model into VRX format: [block:code] { "codes": [ { "code": "./ViroFBX path/to/model.fbx path/to/model.vrx", "language": "shell" } ] } [/block] In the example above, ```path/to/model.fbx``` is the path to the FBX file to convert, and ```path/to/model.vrx``` is the path to the VRX file to create. Once the VRX file is created, it can be loaded into an application with ```<Viro3DObject>```. Again, remember to place the model's associated textures in the same directory as the VRX file. Below is a simple example for loading a VRX file. Notice type is set to VRX here: [block:code] { "codes": [ { "code": "<Viro3DObject source={require('./res/model.vrx')}\n resources={[require('./res/texture1.jpg'),\n require('./res/texture2.jpg'),\n require('./res/texture3.jpg')]}\n position={[0.0, 0.0, -10]}\n scale={[0.1, 0.1, 0.1]}\n type=\"VRX\"\n/>", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "title": "Model Not Appearing?", "body": "You may need to add a Light to your scene. Try adding an Ambient light to see if your model appears:\n```\n<ViroAmbientLight color=\"#FFFFFF\" />\n```\nSee the [Lighting and Materials](doc:3d-scene-lighting) guide for more details." } [/block] # Skeletal Animation FBX models support skeletal animation. Skeletal animation is a hierarchical technique for animating complex geometries like humanoids. Viro supports these animations through its standard animation system. To run a skeletal animation, simply set the animation's name to the name given to the animation in the FBX file. For example, if the FBX file had an animation called "Take 001", you would run the animation like this: [block:code] { "codes": [ { "code": "<Viro3DObject source={require('./res/model.vrx')}\n resources={[require('./res/texture1.jpg'),\n require('./res/texture2.jpg'),\n require('./res/texture3.jpg')]}\n position={[0.0, 0.0, -10]}\n scale={[0.1, 0.1, 0.1]}\n type=\"VRX\"\n animation={{name:'Take 001',\n run:true,\n loop:true,\n delay:1000}}\n/>", "language": "javascript" } ] } [/block] For more information on animations, see the [Animation](doc:animation) guide. # GLTF The GL Transmission Format (glTF) is an API-neutral runtime asset delivery format. glTF bridges the gap between 3D content creation tools and modern 3D applications by providing an efficient, extensible, and interoperable format for the transmission and loading of 3D content. Viro currently supports gLTF 2.0. ## glTF Model Format glTF assets are represented by the following 3 subcomponents: [block:image] { "images": [ { "image": [ "https://files.readme.io/517c2d6-files.png", "files.png", 480, 235, "#f1edf1" ] } ] } [/block] 1. A JSON-formatted file (.gltf) containing a full scene description: node hierarchy, materials, cameras, as well as descriptor information for meshes, animations, and other constructs 2. Binary files (.bin) containing geometry and animation data, and other buffer-based data 3. Image files (.jpg, .png) for textures ## Loading glTF Models There are 3 ways you can provide your glTF data to Viro to be rendered: 1. Import the basic 3 components individually: The .gltf, its corresponding binary, and its image files. 2. Import a single .gltf file, where both the binary and image data are embedded into the .gltf file as Base64-encoded data. 3. Import a single [.glb file](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#glb-file-format-specification) that represents all required glTF components in a raw binary format. Like FBX, you can use the ```<Viro3DObject>``` component to load a glTF model into your scene. When loading glTF files, set the ```type``` property to either "GLTF" (for options 1 and 2 above), or "GLB" (for option 3: raw glTF binary). It is also **important** to note that any related glTF assets (like binary data or image files) are always referenced by the URI's specified within the glTF file. Relative paths are with respect to the location of the glTF file. [block:callout] { "type": "info", "body": "At the moment, Viro supports rendering static 2.0 glTF models. We are also currently in the process of implementing the full support for the complete set of gLTF features, so stay tuned! :) \n\nIncoming features includes:\n- GLTF Animations (Skeletal and Non-Skeletal)\n- Support for additional gLTF Extensions.\n- Emissive Maps\n- Sparse Accessor Data Formats\n- Non-indexed mesh rendering (drawArray rendering)\n- Additional Primitive Modes (Line_Loop & Triangle_Fan)\n- Material Alpha Mask Mode\n- Additional Min / Mag Filter modes\n- Double sided rendering\n- Baked in gLTF Camera", "title": "Incoming GLTF features and known limitations" } [/block]