{"_id":"5bec8a59a9db0c0012d540fa","category":{"_id":"5bec8a59a9db0c0012d540d5","version":"5bec8a59a9db0c0012d54110","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":"Basics"},"project":"5a065a6134873d0010b396ab","user":"579a69d53de0a217007eda56","parentDoc":null,"version":{"_id":"5bec8a59a9db0c0012d54110","project":"5a065a6134873d0010b396ab","__v":0,"forked_from":"5ba1a04d4f89f700039d85d0","createdAt":"2018-04-18T18:19:34.288Z","releaseDate":"2018-04-18T18:19:34.288Z","categories":["5bec8a59a9db0c0012d540d4","5bec8a59a9db0c0012d540d5","5bec8a59a9db0c0012d540d6","5b05923ea5a2f9000357b452","5b05f793c2c86c0003cbe414","5bec8a59a9db0c0012d540d7","5bec8a59a9db0c0012d540d8","5bec8a59a9db0c0012d540d9"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.12.0","version":"1.12.0"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-24T22:59:16.269Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"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, OBJ, and GLTF formats. Viro will load the geometry, textures, and lighting parameters in the file. Installed skeletal animations will also be loaded automatically for FBX models, with this support coming soon for GLTF (which currently supports static models only). OBJ and GLTF files can be fed 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.\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/3ece45d-files.png\",\n        \"files.png\",\n        480,\n        235,\n        \"#f1edf1\"\n      ],\n      \"sizing\": \"smart\"\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 ViroCore's [Object3D][1] component and the [loadModel()][2] API to load a glTF model into your scene. When loading glTF files, set the [Object3D.Type][3] to either ```Object3D.Type.GLTF``` (for options 1 and 2 above), or ```Object3D.Type.GLB```(for option 3: raw glTF binary). \n\nIt is also **important** to note that any related glTF assets (like binary or image files) are always referenced by the URIs specified within the glTF file. Relative paths are with respect to the location of the glTF file.\n\n[1]:https://developer.viromedia.com/virocore/reference/com/viro/core/Object3D.html\n[2]:https://developer.viromedia.com/virocore/reference/com/viro/core/Object3D.html#loadModel(com.viro.core.ViroContext,%20android.net.Uri,%20com.viro.core.Object3D.Type,%20com.viro.core.AsyncObject3DListener)\n[3]:https://developer.viromedia.com/virocore/reference/com/viro/core/Object3D.Type.html\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- 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- Morph Targets\",\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 [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, OBJ, and GLTF formats. Viro will load the geometry, textures, and lighting parameters in the file. Installed skeletal animations will also be loaded automatically for FBX models, with this support coming soon for GLTF (which currently supports static models only). OBJ and GLTF files can be fed 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. # 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/3ece45d-files.png", "files.png", 480, 235, "#f1edf1" ], "sizing": "smart" } ] } [/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 ViroCore's [Object3D][1] component and the [loadModel()][2] API to load a glTF model into your scene. When loading glTF files, set the [Object3D.Type][3] to either ```Object3D.Type.GLTF``` (for options 1 and 2 above), or ```Object3D.Type.GLB```(for option 3: raw glTF binary). It is also **important** to note that any related glTF assets (like binary or image files) are always referenced by the URIs specified within the glTF file. Relative paths are with respect to the location of the glTF file. [1]:https://developer.viromedia.com/virocore/reference/com/viro/core/Object3D.html [2]:https://developer.viromedia.com/virocore/reference/com/viro/core/Object3D.html#loadModel(com.viro.core.ViroContext,%20android.net.Uri,%20com.viro.core.Object3D.Type,%20com.viro.core.AsyncObject3DListener) [3]:https://developer.viromedia.com/virocore/reference/com/viro/core/Object3D.Type.html [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- 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- Morph Targets", "title": "Incoming glTF features and known limitations" } [/block]