{"_id":"5ad78c382cfba50003554c4a","category":{"_id":"5ad78c362cfba50003554bfe","version":"5ad78c362cfba50003554bfc","project":"5a065a6134873d0010b396ab","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-18T21:08:45.730Z","from_sync":false,"order":1,"slug":"develop","title":"Develop"},"project":"5a065a6134873d0010b396ab","user":"579a69d53de0a217007eda56","parentDoc":null,"version":{"_id":"5ad78c362cfba50003554bfc","project":"5a065a6134873d0010b396ab","__v":1,"createdAt":"2018-04-18T18:19:34.288Z","releaseDate":"2018-04-18T18:19:34.288Z","categories":["5ad78c362cfba50003554bfd","5ad78c362cfba50003554bfe","5ad78c362cfba50003554bff","5ad78c362cfba50003554c00"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.6.0","version":"1.6.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":18,"body":"The [Object3D](https://developer.viromedia.com/virocore/reference/com/viro/core/Object3D.html) component enables loading 3D objects (also known as models or meshes) into a scene. \n\nObject3D defines the *structure* of the 3D object: its vertices, faces, and texture coordinates. The scene graph, or Node hierarchy, determines the *orientation and placement* of the object. And finally, the *appearance* of the Object3D 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 into Object3D, while FBX files need to converted into Viro's own [VRX format](#section-fbx). \n\n3D models may be loaded from any URI. To load assets in the application bundle, use URIs of the form `file:///android_asset/[asset-name]`. Models are always loaded asynchronously into the Object3D. The following snippet shows how a model of the human heart would be loaded.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Object3D heart = new Object3D();\\nheart.loadModel(Uri.parse(\\\"file:///android_asset/heart.obj\\\"), Object3D.Type.OBJ, new AsyncObject3DListener() {\\n    public void onObject3DFailed(String error) {\\n        Log.w(TAG, \\\"Failed to load the model\\\");\\n    }\\n    public void onObject3DLoaded(Object3D object, Object3D.Type type)\\n         Log.i(TAG, \\\"Successfully loaded the model!\\\");\\n    }\\n});\\n\\nScene scene = new Scene();\\nscene.getRootNode().addChildNode(heart);\",\n      \"language\": \"java\"\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 via `Object3D.getGeometry().setMaterials(List<Material>)`, 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 placed in the *same directory* as the OBJ file. They will then be automatically retrieved and applied.\n\n# Callbacks\n\nModel loading is performed asynchronously, so as not to introduce lag into your application. Viro provides callbacks through [AsyncObject3DListener](https://developer.viromedia.com/virocore/reference/com/viro/core/AsyncObject3DListener.html] to respond to the model loading process. \n\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 Object3D.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"MacOS X 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 Object3D. 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Object3D model = new Object3D();\\nmodel.loadModel(Uri.parse(\\\"file:///android_asset/model.vrx\\\"), Object3D.Type.FBX, new AsyncObject3DListener() {\\n    public void onObject3DFailed(String error) {\\n        Log.w(TAG, \\\"Failed to load the model\\\");\\n    }\\n    public void onObject3DLoaded(Object3D object, Object3D.Type type)\\n        Log.i(TAG, \\\"Successfully loaded the model!\\\");\\n    }\\n});\\n\\nScene scene = new Scene();\\nscene.getRootNode().addChildNode(model);\",\n      \"language\": \"java\"\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```\\nAmbientLight ambient = new AmbientLight(Color.WHITE, 1000.0f);\\nnode.addLight(ambient);\\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 and keyframe animation. Skeletal animation is a hierarchical technique for animating complex geometries like humanoids. Keyframe animation is a technique for chaining together smooth transitions by their start and end points. Viro automatically loads all skeletal and keyframe animations into the Object3D. \n\nTo run these animations, retrieve the animation via `Node.getAnimation(String)`. Using the [Animation](https://developer.viromedia.com/virocore/reference/com/viro/core/Animation.html) object, you can then configure the animation and run it. For example, if the FBX file had an animation called \"Take 001\", you could run it as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Object3D model = new Object3D();\\nmodel.loadModel(Uri.parse(\\\"file:///android_asset/model.vrx\\\"), Object3D.Type.FBX, new AsyncObject3DListener() {\\n    public void onObject3DFailed(String error) {\\n        Log.w(TAG, \\\"Failed to load the model\\\");\\n    }\\n    public void onObject3DLoaded(Object3D object, Object3D.Type type)\\n        // Now that the model is loaded, get its animation\\n        Animation animation = object.getAnimation(\\\"Take 001\\\");\\n        \\n        // Make the animation loop, then play it\\n        animation.setLoop(true);\\n        animation.play();\\n    }\\n});\\n\\nScene scene = new Scene();\\nscene.getRootNode().addChildNode(model);\",\n      \"language\": \"java\"\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 [Object3D](https://developer.viromedia.com/virocore/reference/com/viro/core/Object3D.html) component enables loading 3D objects (also known as models or meshes) into a scene. Object3D defines the *structure* of the 3D object: its vertices, faces, and texture coordinates. The scene graph, or Node hierarchy, determines the *orientation and placement* of the object. And finally, the *appearance* of the Object3D 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 into Object3D, while FBX files need to converted into Viro's own [VRX format](#section-fbx). 3D models may be loaded from any URI. To load assets in the application bundle, use URIs of the form `file:///android_asset/[asset-name]`. Models are always loaded asynchronously into the Object3D. The following snippet shows how a model of the human heart would be loaded. [block:code] { "codes": [ { "code": "Object3D heart = new Object3D();\nheart.loadModel(Uri.parse(\"file:///android_asset/heart.obj\"), Object3D.Type.OBJ, new AsyncObject3DListener() {\n public void onObject3DFailed(String error) {\n Log.w(TAG, \"Failed to load the model\");\n }\n public void onObject3DLoaded(Object3D object, Object3D.Type type)\n Log.i(TAG, \"Successfully loaded the model!\");\n }\n});\n\nScene scene = new Scene();\nscene.getRootNode().addChildNode(heart);", "language": "java" } ] } [/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 via `Object3D.getGeometry().setMaterials(List<Material>)`, 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 placed in the *same directory* as the OBJ file. They will then be automatically retrieved and applied. # Callbacks Model loading is performed asynchronously, so as not to introduce lag into your application. Viro provides callbacks through [AsyncObject3DListener](https://developer.viromedia.com/virocore/reference/com/viro/core/AsyncObject3DListener.html] to respond to the model loading process. # 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 Object3D. [block:callout] { "type": "info", "title": "MacOS X 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 Object3D. 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. [block:code] { "codes": [ { "code": "Object3D model = new Object3D();\nmodel.loadModel(Uri.parse(\"file:///android_asset/model.vrx\"), Object3D.Type.FBX, new AsyncObject3DListener() {\n public void onObject3DFailed(String error) {\n Log.w(TAG, \"Failed to load the model\");\n }\n public void onObject3DLoaded(Object3D object, Object3D.Type type)\n Log.i(TAG, \"Successfully loaded the model!\");\n }\n});\n\nScene scene = new Scene();\nscene.getRootNode().addChildNode(model);", "language": "java" } ] } [/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```\nAmbientLight ambient = new AmbientLight(Color.WHITE, 1000.0f);\nnode.addLight(ambient);\n```\nSee the [Lighting and Materials](doc:3d-scene-lighting) guide for more details." } [/block] # Skeletal Animation FBX models support skeletal and keyframe animation. Skeletal animation is a hierarchical technique for animating complex geometries like humanoids. Keyframe animation is a technique for chaining together smooth transitions by their start and end points. Viro automatically loads all skeletal and keyframe animations into the Object3D. To run these animations, retrieve the animation via `Node.getAnimation(String)`. Using the [Animation](https://developer.viromedia.com/virocore/reference/com/viro/core/Animation.html) object, you can then configure the animation and run it. For example, if the FBX file had an animation called "Take 001", you could run it as follows: [block:code] { "codes": [ { "code": "Object3D model = new Object3D();\nmodel.loadModel(Uri.parse(\"file:///android_asset/model.vrx\"), Object3D.Type.FBX, new AsyncObject3DListener() {\n public void onObject3DFailed(String error) {\n Log.w(TAG, \"Failed to load the model\");\n }\n public void onObject3DLoaded(Object3D object, Object3D.Type type)\n // Now that the model is loaded, get its animation\n Animation animation = object.getAnimation(\"Take 001\");\n \n // Make the animation loop, then play it\n animation.setLoop(true);\n animation.play();\n }\n});\n\nScene scene = new Scene();\nscene.getRootNode().addChildNode(model);", "language": "java" } ] } [/block] For more information on animations, see the [Animation](doc:animation) guide.