Tutorial: Loading Models

In this tutorial you will learn about the mechanisms that you can use to load models in Voxelent.

Loading API

The easiest way to load models is by using the load public API method:

vxl.api.load(arguments, path, mode, scene)

Where:

• arguments: is a string containing the file name of the model to be loaded. As of version 0.89.4 formats supported are Polydata ASCII VTK and JSON. This parameter can contain the relative path where the model is located. If not, it is assumed that the path will be passed as the second parameter.arguments can also be a list of file names (see bran demo code )
• path: contains the relative path where the model (or models) contained in the arguments parameter can be found.
• mode: the loading mode determines how the models will be processed once they have been downloaded.
• scene: this parameter is optional. It indicates the scene where the loaded models will be displayed. If this parameter is not present, the current scene (vxl.c.scene) will be used.

Loading modes

There are three different loading modes. These are:

• LIVE: It indicates that the loaded models should be processed as soon as they are transferred from the server. Using this mode, actors representing these models will appear progressively on the scene. Unless it is indicated otherwise, this is the model used by default.
• LATER: The models will be processed only when all of them have been downloaded. This mode can be seen in action in the brain demo.
• DETACHED: Models will never be added to any scene once they have been downloaded. This is useful when further processing is required before displaying the model or for instance to download models in the background without affecting the current user interaction.An example of how this method is used can be found in the bouncing balls demo. There, the geometry of a ball is downloaded from the server but it is never added to the scene (see runVoxApp function). The model is retrieved in the handleEvent function.

These modes are defined as constants in the vxl.def.model.loadingMode object

Loading models LIVE

There are many cases where models need to be shown as soon as they are downloaded. Think for example of a game where the hero is moving around the world. In that case we would like not to load all the objects in the world at the same time but instead load them as soon as the hero goes close to the area where these objects are supposed to be located.

The LIVE mode is set by default. Take for instance the Quick Start tutorial code:

var view = vxl.api.setup('view-1');
vxl.api.load('assets/models/simple/cone.json');
view.start();

Here there is no need to add the mode parameter. The same code could be written like this:

var view = vxl.api.setup('view-1');
vxl.api.load('cone.json','assets/models/simple', vxl.def.model.loadingMode.LIVE);
view.start();

Much simpler when we take advantage of the default configuration!

Loading models LATER

Sometimes, we want all the objects in our scene to be downloaded and ready before we can start interacting with them. This could be for instance the case for a surgical simulation where we need to see all the tissue layers before proceeding.

To do so we just need to switch the mode to LATER. From the brain demo code:

var list = ["part1.json","part2.json", "part3.json",
            "part4.json", "part5.json", "part6.json"];
vxl.api.load(list,'assets/models/brain',vxl.def.model.loadingMode.LATER);
vxl.c.view.start();

The natural question to ask is then: How do we know when all the models have been loaded?

For this we need to subscribe to the vxl.events.MODELS_LOADED.

Once we are notified in our handleEvent function we proceed to update the scene accordingly:

function handleEvent(event, src){
    if (event == vxl.events.MODELS_LOADED){
        vxl.api.setLookupTable('default');
        //... more stuff here
   }
}

Loading objects in the background: the DETACHED mode

For some applications it is useful to load objects in the background while the user is busy interacting with the current scene. To this effect, the objects can be loaded in the background without referencing any scene. We achieve this behaviour by writing:

vxl.go.notifier.subscribe(vxl.events.MODELS_LOADED, this);
var view = vxl.api.setup('view-id');
var list = ['model.json','model2.json',...]; #contains a list of files to load
vxl.api.load(list, null, vxl.def.model.loadingMode.DETACHED);
view.start();

Similarly to the LATER mode we can be notified when the models have been downloaded by subscribing to the vxl.events.MODELS_LOADED event in our main function.

Accessing detached models using the model manager

When we receive a MODELS_LOADED event in handleEvent, we obtain a reference to a vxlModelManager through the source parameter. We can retrieve any background loaded model using this reference. For exmaple:

function handleEvent(event, source){
     if (event == vxl.event.MODELS_LOADED){
           var model = source.getModelByName('model.json');
     }
}

Once we are ready to add the model to the scene, we create an actor for it:
view.scene.createActor(model);
or if we want to add all the models that we loaded in the background to the current scene:
vxl.c.scene.createActors(source.models);