Managing viewer states from the API

February 26, 2015

By Philippe Leefsma

Here is a quick post that demo a new feature added to the viewer client JavaScript API: viewer states. A viewer state holds information about the currently loaded model, the visible/isolated components, viewport information and rendering options.

Here is a basic way to use the API: save current state, do some modification and restore the state if needed:

1 var state = viewer.getState();
2 
3 //do some stuff
4     
5 viewer.restoreState(state);

You also have the possibility to set a filter if you are only interested in some properties of the state but not the others, to build our filter, let's take a look at how a state looks like (simply dump a state object in the browser console):

 1 {
 2     "guid":"165b78a714bbbcaa62e",
 3     "seedURN":"dXJuOmF ...",
 4     "overrides":{
 5         "transformations":[]
 6     },
 7     "objectSet":[
 8         {
 9             "id":[],
10             "isolated":[],
11             "hidden":[59, 92],
12             "explodeScale":0
13         }
14     ],
15     "viewport":{
16         "name":"",
17             "eye":[
18             11.8967666290891,
19             18.261480587275184,
20             15.07569790673083
21         ],
22             "target":[
23             -3.768804682150914,
24             2.5959099531173706,
25             -0.5898730659680815
26         ],
27             "up":[
28             -0.4082482860526343,
29             0.8164965897501829,
30             -0.4082482772301776
31         ],
32             "worldUpVector":[
33             0,
34             1,
35             0
36         ],
37             "pivotPoint":[
38             -3.768804682150914,
39             2.5959099531173706,
40             -0.5898730659680815
41         ],
42             "distanceToOrbit":27.133564854290718,
43             "aspectRatio":3.427480916030534,
44             "projection":"orthographic",
45             "isOrthographic":true,
46             "orthographicHeight":27.13356485429072
47     },
48     "renderOptions":{
49         "environment":"Riverbank",
50             "ambientOcclusion":{
51             "enabled":true,
52                 "radius":10,
53                 "intensity":0.5
54         },
55         "toneMap":{
56             "method":1,
57                 "exposure":-5.7,
58                 "lightMultiplier":-1e-20
59         },
60         "appearance":{
61             "ghostHidden":true,
62                 "ambientShadow":true,
63                 "antiAliasing":true,
64                 "progressiveDisplay":true,
65                 "displayLines":true
66         }
67     }
68 }

So to build a state filter, we use the same structure and set true or false wether or not we want to keep that property in the state:

 1 //example of a state filter
 2 var stateFilter1 = {
 3 
 4     seedURN: false,
 5     objectSet: true,
 6     viewport: true,
 7     renderOptions: true
 8 };
 9 
10 //another example of a state filter
11 var stateFilter2 = {
12 
13     seedURN: false,
14     objectSet: true,
15     viewport: true,
16     renderOptions: {
17         environment: false,
18         ambientOcclusion: false,
19         toneMap: {
20             exposure: false
21         },
22         appearance: false
23     }
24 }

We can use filters while getting or restoring states:

1 var state = viewer.getState(stateFilter1);
2 
3 viewer.restoreState(state, stateFilter2, false);

Finally you notice the third parameter of "restoreState". This is used if you want to have a smooth transition while restoring the view. If immediate = false there will be a transition. However a word of caution concerning the transition: at the time of my testing renderOptions needs to be false in the state filter in order for the transition to work. If you restore the renderOptions, you wont have the view transition or a workaround would be to do a two-step approach: restore view without renderOptions then restore renderOptions or the other way around...

Here is the declaration of that function from the API source code:

 1 /**
 2  * Restores the viewer state from a given object.
 3  * @param {Object} viewerState
 4  * 
 5  * @param {Object} [filter] 
 6  * Similar in structure to viewerState used 
 7  * to filter out values that should not be restored.
 8  * 
 9  * @param {boolean} [immediate] 
10  * Whether the new view is applied with  
11  * or without transition 
12  *
13  * @returns {boolean} 
14  * true if restore operation was successful
15  *
16  * @virtual
17  */
18 Autodesk.Viewing.Viewer.prototype.restoreState =
19     function (viewerState, filter, immediate)

Posts by author

Philippe Leefsma
Cloud Fellow

I write JavaScript for the future 3D World Wide Web, A.K.A Forge Platform