The Anatomy of a Scene File

There are some circumstances where you may want to create your scene file procedurally either to represent changes in your model, or because you have a large number of actors and loading them all manually is more difficult that generating the list of meshes, textures, objects, and actors through the use of code. This help page outlines the structure of the scene file used by the visualization blocks so you can manually create a scene file if you so choose. In many cases though, it is easier to compose a scene using the Visualization Initialize block.

The Basic Structure

The following is the scene file used by the X-Ray Visualization demo. The original file can be found in your QUARC Installation folder as $(QUARC_DIR)/quarcdemos/scene_files/quarc_visualization_x_ray.xml. Now we will examine the code in parts and comment on each section as we go. Let us begin with the basic structure:

    <?xml version="1.0" encoding="utf-8"?>
    <Scene xmlns="http://www.quarcservice.com/schemas/visualization_scene_file.xsd" Version="1.3">
        <SceneParameters>    
            ...
        </SceneParameters>
        <MeshPool>
            ...
        </MeshPool>
        <TexturePool>
            ...
        </TexturePool>
        <ObjectPool>
            ...
        </ObjectPool>
        <ActorPool>
            ...
        </ActorPool>
    </Scene>

Every scene file will begin with the first two lines. The first line indicates that this is an xml file. The second line is the schema (rules) of this scene file and the current version. This version number is checked by both the 3D viewer and the Visualization Initialize block user interface to ensure compatibility. Although future versions will attempt to maintain backwards compatibility with older versions, this is not guaranteed. Schemas prior to version 1.3 are not supported.

After the initial file definition is the SceneParameters. This defines what keys, buttons, and motions are used for the mouse and keyboard actions, and global parameters such as the initial window size, ambient light, and clipping planes. The details will be discussed shortly. SceneParameters is followed by MeshPool for the list of meshes, TexturePool for the list of textures, ObjectPool for the combinations of meshes and textures, and finally the ActorPool which contains the list of actors.

The Scene Parameters

The scene parameters for the X-Ray demo are as follows:

    <SceneParameters>
        <Mouse>
            <Forward Button="wheel" Direction="forward" Speed="0.002"/>
            <Left Button="right" Direction="left" Speed="0.002"/>
            <Up Button="right" Direction="backward" Speed="0.002"/>
            <Roll Alt="true" Button="left" Direction="right" Speed="0.002"/>
            <Pitch Button="left" Direction="forward" Speed="0.002"/>
            <Yaw Button="left" Direction="left" Speed="0.002"/>
        </Mouse>
        <Keyboard>
            <Translation Backward="s" Down="q" Forward="w" PanLeft="a" PanRight="d" Speed="1" Up="e"/>
            <Rotation PitchDown="k" PitchUp="i" RollLeft="j" RollRight="l" Speed="1.5707963267948966" YawLeft="u" YawRight="o"/>
        </Keyboard>
        <Camera ClipFar="1000" ClipNear="0.1" ViewAngle="45"/>
        <Light Ambient="0.314 0.314 0.314" Background="0.678 0.922 1"/>
        <Window DisplayMode="window" FrameRate="30" Height="768" Menu="false" StatusBar="true" Width="1024"/>
        <Fog Color="1 1 1" Density="0.5" End="50" Mode="linear" Start="25"/>
    </SceneParameters>

Let us being by examining the mouse parameters:

    <Mouse>
        <Forward Button="wheel" Direction="forward" Speed="0.002"/>
        <Left Button="right" Direction="left" Speed="0.002"/>
        <Up Button="right" Direction="backward" Speed="0.002"/>
        <Roll Alt="true" Button="left" Direction="right" Speed="0.002"/>
        <Pitch Button="left" Direction="forward" Speed="0.002"/>
        <Yaw Button="left" Direction="left" Speed="0.002"/>
    </Mouse>

The Mouse tag defines how each translation (Forward, Left, and Up) and each rotation (Roll, Pitch, and Yaw) are controlled with the mouse. Every motion must contain a Button property with one of the following:

It must also contain a direction:

And finally, each line must have a Speed property. There are no meaningful units to the speed as it is a function of your screen resolution and the mouse speed you set in Windows. Each line can also optionally contain Alt="true", Ctrl="true", and/or Shift="true" which indicates these modifier keys must also be pressed for the desired motion. If these modifiers are set to false, or are not present, then they are assumed to not be used. It is also implied that to translate backward, right, or down is the opposite direction of what is defined by forward, left, and up. The same is to be said of the rotations. If the entire mouse section is not present, then manual control by means of the mouse is assumed to be disabled. However, if the mouse section is defined, then all six motion definitions must be present.

The next section of the scene parameters is the keyboard:

  <Keyboard>
    <Translation Backward="s" Down="q" Forward="w" PanLeft="a" PanRight="d" Speed="1" Up="e"/>
    <Rotation PitchDown="k" PitchUp="i" RollLeft="j" RollRight="l" Speed="1.57079" YawLeft="u" YawRight="o"/>
  </Keyboard>

Translation and rotation each define keys for each of their possible six motions. Speed for translation is in units per second, and the speed for rotation is in radians per second. Both translation and rotation do not need to be present simultaneously. The absence of one will disable the respective six control motions. However, if translation or rotation are defined, then all six of their respective motions plus the speed must be defined.

  <Camera ClipFar="1000" ClipNear="0.1" ViewAngle="45"/>

The camera has three properties. ClipFar defines the far clipping plane in units. ClipNear defines the near clipping plane in units. Both planes must be positive values greater than zero and ClipFar must be greater than ClipNear. The ViewAngle property defines the lens angle in degrees. Note, large lens angles may result in undesirable distortion of your scene. A typical value is 45 degrees.

  <Light Ambient="0.314 0.314 0.314" Background="0.678 0.922 1"/>>

The light tag in the scene parameters has two properties. Ambient defines what the color of the shadowed areas of your actors will be. This is a three element vector (red, green, blue) on a scale of 0 to 1. Background defines the background color of your scene assuming you are not using a skybox. Again, this is a three element vector on a scale of 0 to 1.

  <Window DisplayMode="window" FrameRate="30" Height="768" Menu="false" StatusBar="true" Width="1024"/>

The window tag defines what the window will look like when the scene file is loaded. DisplayMode has the following options:

The FrameRate defines the maximum frame rate that the viewer window will attempt to maintain. The frame rate may drop to a lower rate in order to avoid interfering with your controller if it is running on the same machine, if other applications are vying for CPU time, or if your scene is simply too detailed for your computer hardware to handle. Note that if your animation appears choppy, but the status bar indicates that you are achieving the desired frame rate, then this may be due to a communication issue such as the nagle option on TCP/IP.

Height and width define the initial window size. If the DisplayMode is set to fullscreen, then the viewer will attempt to change to a fullscreen resolution using the values set here. Failing that, the fullscreen option will switch to the fullscreen of your current screen resolution. Refer to the Fullscreen Resolution submenu of the Window menu of the 3D viewer for a list of valid resolutions for your system.

Finally the Menu and StatusBar properties determine if the menu and status bar are shown. If the viewer is loaded with the scene file either from Simulink or from a command line with the Menu property equal to false, then the menu will be inaccessible. If the 3D viewer is loaded independently and then the scene file is loaded from the viewer's file menu with the Menu property equal to false, then the menu will simply be hidden. A hidden menu can be revealed by moving the mouse near the top of the viewer window.

  <Fog Color="1 1 1" Density="0.5" End="50" Mode="linear" Start="25"/>

The final property of the scene parameters is fog. The color property is a three element vector (red, green, blue) on a scale of 0 to 1. The mode can take on the following values:

The Mesh Pool

The sole purpose of the mesh pool is to list the mesh files that will be used and associate an identification name (ID) with them. The following is the mesh list from the X-Ray demo:

    <MeshPool>
        <Mesh Filename="..\..\resources\meshes\optical\magnifying_glass\magnifying_glass.x3d" ID="mesh.magnifying_glass"/>
        <Mesh Filename="..\..\resources\meshes\environment\sky\skybox.x3d" ID="mesh.skybox"/>
        <Mesh Filename="..\..\resources\meshes\environment\terrain\infinite_plane.x3d" ID="mesh.infinite_plane"/>
        <Mesh Filename="..\..\resources\meshes\mechanical\gears\gear.x3d" ID="mesh.gear"/>
        <Mesh Filename="..\..\resources\meshes\primitives\teapot.x3d" ID="mesh.teapot"/>
        <Mesh Filename="..\..\resources\meshes\primitives\teapot_inverted_normals.x3d" ID="mesh.teapot_inverted_normals"/>
    </MeshPool>

Each mesh will contain a Filename property with a value that lists either a relative or absolute path to an x3d or q3d file. It will also contain an ID with a unique name among the mesh pool. Duplicate names will result in an error returned from the viewer.

The Texture Pool

The texture pool is very similar to the mesh pool:

    <TexturePool>
        <Texture Filename="..\..\resources\images\optical\magnifying_glass\magnifying_glass_x_ray.png" ID="image.magnifying_glass_x_ray"/>
        <Texture Filename="..\..\resources\images\environment\sky\skybox_tropical.png" ID="image.skybox_tropical"/>
        <Texture Filename="..\..\resources\images\environment\terrain\infinite_plane_grid.png" ID="image.infinite_plane_grid"/>
    </TexturePool>

As with the mesh pool, each texture will contain a filename with a relative or absolute path. Images can be bmp, png, jpg, or tif. Any actors that reference objects that use bmp or png will be flagged as potentially transparent. Render priorities will need to be set appropriately where necessary to ensure there are no conflicts. Each texture will also include a unique ID among the texture pool.

The Object Pool

The objects are responsible for connecting the meshes to the textures. Here is what the object pool from the X-Ray demo looks like:

    <ObjectPool>
        <Object ID="object.magnifying_glass" Mesh="mesh.magnifying_glass" Texture="image.magnifying_glass_x_ray"/>
        <Object ID="object.skybox" Mesh="mesh.skybox" Texture="image.skybox_tropical"/>
        <Object ID="object.infinite_plane" Mesh="mesh.infinite_plane" Texture="image.infinite_plane_grid"/>
        <Object ID="object.gear" Mesh="mesh.gear"/>
        <Object ID="object.teapot" Mesh="mesh.teapot"/>
        <Object ID="object.teapot_inverted_normals" Mesh="mesh.teapot_inverted_normals"/>
    </ObjectPool>

Every object will reference a mesh with a value equal to a valid ID from the mesh pool. Every object will have a unique ID among the object pool. The ID cannot be "light", "camera", or "dummy" as those words have been reserved. Each object will optionally contain a texture property with a reference to an ID from the texture pool. If a texture property is not present, then any actors derived from this object will default to white (shaded as a function of the lighting if the mesh has normals) unless otherwise modified in the actor properties.

The Actor Pool

The actor pool is the list of actual items that will appear in your scene a long with their initial properties. Let's take a look at the actor pool from our example:

    <ActorPool>
        <Actor Color="1 1 1 1" Fog="true" ID="actor.camera" Object="camera" Orientation="0 0 0" Position="-5 0 0" Priority="0" Scale="1 1 1">
            <Actor Color="1 1 1 1" Fog="false" ID="actor.skybox" InheritOrientation="false" Object="object.skybox" Orientation="0 0 0" Position="0 0 0" Priority="10" Scale="1000 1000 1000"/>
        </Actor>
        <Actor Color="1 1 1 1" Fog="true" ID="actor.light" Object="light" Orientation="0 0 0" Position="-30 0 100" Priority="0" Scale="1 1 1"/>
        <Actor Color="1 1 1 1" Fog="true" ID="actor.magnifying_glass" Object="object.magnifying_glass" Orientation="-0.523599 0 0" Position="-3.02271 -0.0957576 0" Priority="0" Scale="1 1 1"/>
        <Actor Color="1 1 1 1" Fog="true" ID="actor.infinite_plane" Object="object.infinite_plane" Orientation="0 0 0" Position="0 0 -3" Priority="0" Scale="1 1 1"/>
        <Actor Color="1 1 1 1" Fog="true" ID="actor.gear.1" Object="object.gear" Orientation="0 0 0" Position="0 0.191522 -0.194809" Priority="0" Scale="0.5 0.5 0.5"/>
        <Actor Color="1 1 1 1" Fog="true" ID="actor.gear.2" Object="object.gear" Orientation="0 0 0" Position="0 -0.221629 0.077525" Priority="0" Scale="0.5 0.5 0.5"/>
        <Actor Color="1 1 1 1" Fog="true" ID="actor.gear.3" Object="object.gear" Orientation="0 0 0" Position="0 -0.64752 -0.193719" Priority="0" Scale="0.5 0.5 0.5"/>
        <Actor Color="1 1 1 1" Fog="true" ID="actor.teapot" Object="object.teapot" Orientation="0 0 1.5708" Position="0 -0.153208 -0.689053" Priority="-1" Scale="1 1 1">
            <Actor Color="1 1 1 1" Fog="true" ID="actor.teapot_inverted_normals" Object="object.teapot_inverted_normals" Orientation="0 0 0" Position="0 0 0" Priority="0" Scale="1 1 1"/>
        </Actor>
    </ActorPool>

Each actor will contain an Object property with one of the following the following options:

Each actor will also contain a unique ID among the list of actors, a four element vector of the actors color (red, green, blue, alpha) on a scale of 0 to 1, a three element vector describing the initial position (x, y, z) in units, a three element vector describing the initial orientation (roll, pitch, yaw) in radians, and a three element vector describing the initial scale (x, y, z) as a multiplier of the original size along each axis. Each actor will optionally contain a fog property (default is true if not present) which if set to false will not be affected by the global fog settings, and a priority property (default is 0 if not present) which will be an integer value on the range of -1000 to 1000 (see the Visualization Initialize block reference page for more details on render priority).

Any actor node can have child actor nodes which indicates that the actor is a child of the parent actor. By default the child will inherit all changes to position, orientation, and scale of the parent unless they define the InheritPosition="false", InheritOrientation="false", and/or InheritScale="false" in which case the corresponding properties can be set independently of the parent. If a property is not inherited and also not driven, then it will retain its initial value. The skybox for instance does not inherit the orientation of the camera and stays at a constant orientation of [0 0 0] (the initial orientation). However, the skybox will inherit the position so it will give the impression of the camera being able to look around the environment while the sky remains an infinite distance away.

Taking Advantage of XML

Now that you know the structure of the visualization scene file, you either edit xml scene files by hand, or create scripts to automatically generate scene files for you. Part of the power of using xml is that it is an extensible markup language. You can add your own properties and tags to the scene file so you can parse the same file with other blocks for different information. For example, you might include the mass and inertia, or the electrical conductivity of an actor. Since the 3D viewer does not know about those properties, they will be ignored, but you could load the same scene file by your own custom blocks to find the necessary properties and use it as a system-wide configuration file. It is open to your imagination.

Copyright ©2024 Quanser Inc. This page was generated 2024-04-16. Submit feedback to Quanser about this page.

Link to this page.