Scene swaps

For a better understanding of what a scene is for HELIOS++, please refer to the Scene page of the wiki.

Scene swap

Next to dynamic scenes, HELIOS++ also supports scenes for which at least one of its components changes its state between rather than during repeated simulations. This feature allows creating many variations of a base scene. For example, a base scene could be an urban environment with streets, buildings, trees and parked cars. With the scene swap feature, we could define many states of this scene by swapping tree geometries (e.g., to represent them in different seasons), swapping cars or modifying their position, or swapping or removing buildings.

Scene swaps are defined at the scene part level and can be of the following types:

Replacement of the 3D geometry by loading another file (possibly with coordinate transformation filters)
Change of the coordinate transformation (translation, rotation, scale)
(Temporarily) remove a scene part

Swap Definition

The basic syntax for scene part swapping looks as follows:

<swap swapStep="1">
    <!-- settings here -->
</swap>

The swapStep parameter defines, for how many swap steps the provided scene part definition is valid. The parameter is optional, if no swapStep is defined, it is automatically set to 1.

The <swap> tag needs to be preceded by a base scene part definition, cf. Scene page of the wiki. Within the <swap> tag, filters can be defined for loading a new geometry, changing the coordinate transformation or removing the scene part.

Exchange the geometry

    <swap>
	<filter type="objloader">
	    <param type="string" key="filepath" value="data/sceneparts/toyblocks/cube.obj" />
	</filter>
    </swap>

Changing the coordinate transformation

    <swap>
        <filter type="rotate">
            <param key="rotation" type="rotation">
                <rot angle_deg="45" axis="z"/>
            </param>
        </filter>
        <filter type="scale">
            <param type="double" key="scale" value="2.0" />
        </filter>
        <filter type="translate">
            <param type="vec3" key="offset" value="-22.0;12.0;0" />
        </filter>
    </swap>

Removing the geometry

    <swap force_null="true">
    </swap>

Full example

Here is a full example, in which first a sphere is loaded to scene part 1, which is then swapped by a cube, which stays the same for two steps. Then, the cube is scaled down for one step and for the last step, the scene part is removed.

<!-- Sphere goes cube goes small cube goes nothing -->
<!-- ***************************** -->
<part id="1">
    <!-- initial state -->
    <filter type="objloader">
        <param type="string" key="filepath" value="data/sceneparts/toyblocks/sphere.obj" />
    </filter>
    <filter type="scale">
        <param type="double" key="scale" value="1.25" />
    </filter>
    <filter type="translate">
        <param type="vec3" key="offset" value="-10.0;-20.0;0" />
    </filter>
    <!-- Swap sphere by cube (for two swap steps) -->
    <swap swapStep="2">
	<filter type="objloader">
	    <param type="string" key="filepath" value="data/sceneparts/toyblocks/cube.obj" />
	</filter>
	<filter type="scale">
	    <param type="double" key="scale" value="2.0" />
	</filter>
        <filter type="translate">
            <param type="vec3" key="offset" value="-40.0;40.0;0" />
	</filter>
    </swap>
    <!-- Swap big cube by small cube -->
    <swap>
	<filter type="scale">
	    <param type="double" key="scale" value="0.5" />
	</filter>
     </swap>
    <!-- Swap cube by nothing -->
    <swap force_null="true">
    </swap>
</part>