Adding 3D Models and Object Types to 3DView2

Adding 3D Models and Object Types to 3DView2

Object Types are defined by the microPSI world server. 3DView2 connects to the server and receives a list of world objects including their positions and states. Every object has a class name. The class name is basically the object type, for instance 'Tree' or 'Mushroom'. In order to visualize the world with 3DView2 you must associate one or more 3D models with every object class. This is done in a so-called 'visualization file' for 3DView2. The microPSI core system and the world server have no knowledge about the viewer or 3d models. The creation of 3d models is covered in Creating 3D Models and Animations for 3DView2

A visualization completely defines the look of the world in 3DView2. There can be more than one visualization. Think of visualizations as skins - there could, for instance, be a Middle European visualization where objects of type 'Tree' appear as broad-leafed trees and a Caribbean visualization where the same object type looks like a palm tree.

Visualizations are defined in XML-Files. All visualization files are located in the folder 3dview2/data/visualizations. Only one visualization file is used at a time. There is always a default visualization called standard.xml. If you want to create a new visualization it is a good starting point to copy this file and edit it as needed.

The basic structure of a visualization xml file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!-- microPSI 3Dview2 visualization file -->
<visualization>
    <description> … </description>
    <terrain> … </terrain>
    <skybox> … </skybox>
    <objects> … </objects>
</visualization>

The description tag contains a descriptive text, for instance 'my very own Caribbean island visualization'. The terrain tag is not covered here, it is discussed in Creating Terrains for 3DView2. The skybox tag defines a model that represents the sky, the objects tag contains the definitions of all world objects.

Skybox

The skybox tag contains the name of a model file that is used as a sky box, for instance

<skybox>skybox.x</skybox>

The skybox model is different from all other models. It is the sky you see behind the terrain and all other objects. Typically, it is a box with a sky texture on the inside (therefore the name). The skybox model moves with the camera, so the viewer is always in the center of it, that means at (0,0,0) in the local coordinate system of the model. The skybox is rendered in a way so that it always appears to be in the background. It does not obscure any other objects but is obscured by everything else. The actual size of the skybox does not matter; it can be as small as 1x1x1 meter. Because of the special rendering it will appear to have an infinite size. The skybox can in fact be an arbitrary model, it does not have to be a box. It should, however, be a closed mesh. The viewer should be on the inside of the mesh and it sound not be possible to look out of it.

World Objects

The objects tag contains information how to visualize different object types. In the ideal case this section contains an entry for every object class the microPSI world server defines. If 3DView2 encounters an object with a type which has no such entry it will display the object with a default model, e.g. a small blue box with the text 'unknown object type' printed on it.

You can define an number of variations for every object class. Variations are alternative models that can be used to display a particular object. This is because a large forest, for instance, which consists of many objects of type 'Tree' would look pretty dull if all trees looked the same. Therefore, you can create a number of different tree models and 3DView2 will pick a random variation for every Tree object in the world.

For every variation you can define a number of LOD levels. LOD stands for 'Level of Detail'. In 3DView2 hundreds of objects can be visible at the same time and 3d models can become very complex. For performance reasons it is often necessary to reduce the visual detail of objects that are far away from the camera, i.e. you can use a very detailed model for an object if it is close to the camera but use a very simple one if the object is far away and therefore appears only very small on the screen anyway. 3DView2 allows you to define a number of LOD models for every variation of an object. For every LOD level you define a maximum distance in meters where this model can be used. Let us have a look at a few examples:

<object>
´       <classname>PalmTree</classname>
        <variation>
            <lodlevel>
                <model>bananatree.x</model>
            </lodlevel>
        </variation>
    </object>

This is the easiest way to define an object, it contains only one variation with only one LOD level. This piece of xml code says that objects of type 'PalmTree' will always be displayed with model file 'bananatree.x'. Note that the LOD level in this example does not contain a distance limit, the limit it therefore considered to be infinite.

<object>
        <classname>Grass</classname>
        <variation>
            <lodlevel>
                <model>grass.x</model>
                <maxdistance>8.0</maxdistance>
            </lodlevel>
            <lodlevel>
                <model>grass_reduced.x</model>
                <maxdistance>16.0</maxdistance>
            </lodlevel>
            <lodlevel>
                <model>grass_billboard.x</model>
            </lodlevel>
         </variation>
     </object>

This second example contains two LOD levels. Objects of type 'Grass' will use model 'grass.x' up to a distance of 8.0 meters from the viewer. Between 8.0 and 16.0 meters the application will use 'grass_reduced.x'. Beyond 16.0 meters 'grass_bill.x' will be used. If more that one LOD level exists for an object 3DView2 will always use the one with the smallest acceptable limit. The order in which you specify the LOD levels in the xml file does not matter. Again, there is one LOD level in the example that has no limit (i.e. an infinite limit). This does not have to be the case.

<object>
        <classname>FlyAgaric</classname>
        <variation>
            <lodlevel>
                <model>element_fliegenpilz_a.x</model>
                <maxdistance>100.0</maxdistance>
            </lodlevel>
        </variation>
    </object>

In this third example there is only one LOD level but it has a limit of 100.0 meters. That means that objects of type 'FlyAgaric' will not be visible beyond a distance of 100.0 meters. They will completely disappear which saves performance and is acceptable for smaller objects.

Finally, here's an example of a tree object which defines three variations with two levels of detail each:

<object>
        <classname>PineTree</classname>
        <variation>
            <lodlevel>
                <model>element_nadelbaum_a.x</model>
                <maxdistance>150.0</maxdistance>
            </lodlevel>
            <lodlevel>
                <model>element_nadelbaum_a_bill.x</model>
            </lodlevel>
        </variation>
        <variation>
            <lodlevel>
                <model>element_nadelbaum_b.x</model>
                <maxdistance>150.0</maxdistance>
            </lodlevel>
            <lodlevel>
                <model>element_nadelbaum_b_bill.x</model>
            </lodlevel>
        </variation>
       <variation>
           <lodlevel>
               <model>element_nadelbaum_c.x</model>
               <maxdistance>150.0</maxdistance>
           </lodlevel>
           <lodlevel>
               <model>element_nadelbaum_c_bill.x</model>
           </lodlevel>
       </variation>
    </object>