{"_id":"59bc03d41d2d8d001a3445bc","category":{"_id":"59bc03d31d2d8d001a344581","version":"59bc03d31d2d8d001a34457d","project":"578c4badbd223d2000cc1441","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-18T21:08:45.730Z","from_sync":false,"order":4,"slug":"develop","title":"Develop"},"project":"578c4badbd223d2000cc1441","user":"579a69d53de0a217007eda56","parentDoc":null,"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"},"__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":7,"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 ```bin``` directory. The following example shows how to convert a model into VRX format:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"./ViroFBX js/res/model.fbx js/res/model.vrx\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nOnce the VRX file is created, it can be loaded as follows into an application. 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# 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.","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 ```bin``` directory. The following example shows how to convert a model into VRX format: [block:code] { "codes": [ { "code": "./ViroFBX js/res/model.fbx js/res/model.vrx", "language": "shell" } ] } [/block] Once the VRX file is created, it can be loaded as follows into an application. 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] # 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.