Scene

Scene

The scene serves as central point for storing information related to the simulation environment. In particular, the scene provides access to individual scene objects and avatars. In the following an overview of the essential formats of the scene is given.

Scene Object

The MSceneObject builds the basic block for representing a scene object within the MMI framework. Each MSceneObject has a unique ID, a required name and a necessary transform. Moreover, optionally a collider, mesh, physic properties and meta-information (properties) can be defined.

MSceneObject
+ID: string +Name: string +Transform: MTransform +Collider: MCollider +Mesh: MMesh +PhysicsProperties: MPhysicsProperties +Properties: map<string,string> +Attachments: list +Constraints: list<constraints.MConstraint>

Detailed description of available parameters:

Parameter Name	Required	Description
ID	x	Unique id of the scene object.
Name	x	Name for the scene object.
Transform	x	The mandatory transform of the scene object.
Collider		The collider of the scene object (optional).
Mesh		The mesh of the scene object (optional).
PhysicsProperties		The physical properties of the scene object.
Properties		Optional properties/meta information of the scene object.
Attachments
Constraints

Colliders

For representing colliders in the proposed framework, the so-called MCollider class is proposed. Since Apache Thrift does not provide class inheritance for structs, the different collider types are explicitly represented within the MCollider class. The type of the assigned collider can be directly evaluated based on the MColliderType enum.

MCollider
+ID: string +Type: MColliderType +BoxColliderProperties: MBoxColliderProperties +SphereColliderProperties: MSphereColliderProperties +ConeColliderProperties: MConeColliderProperties +CapsuleColliderProperties: MCapsuleColliderProperties +CylinderColliderProperties: MCylinderColliderProperties +MeshColliderProperties: MMeshColliderProperties +PositionOffset: MVector3
+RotationOffset: MQuaternion +Properties: map<string,string>
+Colliders: list

Detailed description of available parameters:

Parameter Name	Required	Description
ID	x	The id of the collider (linked to the MSceneObject)
Type	x	The type of the collider (defined through the MColliderType enum)
BoxColliderProperties		Specific properties required for a box collider.
SphereColliderProperties		Specific properties required for a sphere collider.
ConeColliderProperties		Specific properties required for a cone collider.
CapsuleColliderProperties		Specific properties required for a capsule collider.
CylinderColliderProperties		Specific properties required for a cylinder collider.
MeshColliderProperties		Specific properties required for a mesh collider.
PositionOffset		The translational offset of the collider to the reference MSceneObject/ MTransform.
RotationOffset		The rotational offset of the collider to the reference MSceneObject/ MTransform.
Properties		Optional properties, which can be set.
Colliders		An optional list for representing a collider hierarchy.

Collider Type

The MColliderType enum contains all possible collider types in the framework.

MColliderType (enum)
Box Sphere Capsule Cone Cylinder Mesh Custom

Each collider has different properties describing its characteristics. To represent these characteristics in the framework for each available MColliderType, a respective ColliderProperties class is provided. An overview of the available Collider classes is given below.

Box Collider Properties

MBoxColliderProperties
+Size: MVector3

Detailed description of available parameters:

Parameter Name	Required	Description
Size	x	The dimensions of the box collider [m].

Sphere Collider Properties

MSphereColliderProperties
+Radius: double

Detailed description of available parameters:

Parameter Name	Required	Description
Radius	x	The radius of the sphere collider [m].

Capsule Collider Properties

MCapsuleColliderProperties
+Radius: double +Height: double MainAxis: MVector3

Detailed description of available parameters:

Parameter Name	Required	Description
Radius	x	The radius of the capsule collider [m].
Height	x	The height of the capsule collider [m].
MainAxis		The main axis of the capsule collider.

Cone Collider Properties

MConeColliderProperties
+Radius: double +Height: double

Detailed description of available parameters:

Parameter Name	Required	Description
Radius	x	The radius of the cone collider [m].
Height	x	The height of the cone collider [m].

Cylinder Collider Properties

MCylinderColliderProperties
+Radius: double +Height: double

Detailed description of available parameters:

Parameter Name	Required	Description
Radius	x	The radius of the cylinder collider [m].
Height	x	The height of the cylinder collider [m].

Mesh Collider Properties

MMeshColliderProperties
+Vertices: list +Triangles: list

Detailed description of available parameters:

Parameter Name	Required	Description
Vertices	x	A list of all vertices of the collider.
Triangles	x	All triangle indices of the collider.

Mesh

In addition to describing a collider, it is oftentimes required to describe a mesh that is separated from the collider. To describe a mesh in the MMI framework the so-called MMesh class is proposed. Below the class diagram, as well as a detailed description of the available parameters is provided.

MMesh
+ID: string +Vertices: list +Triangles: list +Properties: map<string,string> +UVCoordinates: list

Detailed description of available parameters:

Parameter Name	Required	Description
ID	x	The unique ID of the object.
Vertices	x	The vertices of the mesh relative to the MTransform.
Triangles	x	A list of the available triangles of the mesh. Each entry In the list represents the corresponding vertex index.
Properties		Optional properties for the mesh.
UVCoordinates

Geometry

In addition to describing a mesh, it is sometimes required to describe a geometrical component that is separated from the mesh. To describe a geometrical component in the MMI framework the so-called MGeometry class is proposed. Below the class diagram, as well as a detailed description of the available parameters is provided.

MGeometry
+ID: string +GeometryType: MGeometryType +SupportPoints: list<list> +Nodes: list<list> +Weights: list<list> +Properties: map<string,string>

Detailed description of available parameters:

Parameter Name	Required	Description
ID	x	The unique ID of the object.
GeometryType	x	The type of the geometry object.
SupportPoints	x	The support points of the geometry. 1- dimensional array for 0- and 1-dimensional objects (point, polyline and curve) and 2-dimensional array for 2-dimensional objects (plane and surface) .
Nodes		Optional nodes in 1- dimensional array for curve and 2-dimensional array for surface (B-Spline representation).
Weights		Optional weights in 1- dimensional array for curve and 2-dimensional array for surface (B-Spline representation).
Properties		Optional properties for the geometry.

Geometry Type

For the MMI framework, a base set of different geometry types (MGeometryType) is defined that are listed below.

MGeometryType (enum)
Point Polyline Curve Plane Surface, curve SupportPoints (3) (2xn), Weights (2xn), nodes (2xn)

Each MSceneObject contains additional physical properties, such as mass or velocity, which are represented using the MPhysicsProperties format outlined below.

Note
Deprecated: Couldn't find MGeometry and MGeometryType in the thrift files.

Physics Properties

MPhysicsProperties
+Mass: double +CenterOfMass: list +Inertia: list +Velocity: list +AngularVelocity: list +NetForce: list +NetTorque: list
+Mu1: double +Mu2: double +Bounciness: double +MuTorsion: double +TorsionSurfaceRadius: double

Detailed description of available parameters:

Parameter Name	Required	Description
Mass	x	The mass of the object.
CenterOfMass	x	The center of mass of the object.
Inertia	x	The present inertia of the object.
Velocity	x	The present velocity of the object.
AngularVelocity	x	The present angular velocity of the object.
NetForce
NetTorque
Mu1
Mu2
Bounciness
MuTorsion
TorsionSurfaceRadius

In order to do a pathfinding in the scene, it is important to identify the walkable areas. To quantify the walkable area, the so-called MNavigationMesh class is provided.

Navigation Mesh

MNavigationMesh
+Vertices: list +Triangles: list +Properties: map<string,string>

Detailed description of available parameters:

Parameter Name	Required	Description
Vertices	x	All vertices of the navigation mesh
Triangles	x	The triangle indices of the navigation mesh.
Properties		Optional properties for the navigation mesh.

Avatar

In many cases, it might be of interest for the MMU or target-engine developers to identify all avatars in the scene (e.g. Collision avoidance, multi-avatar interaction). Therefore, a separate format describing a specific Avatar, its properties and location is required. For describing an avatar in the MOSIM framework, the MAvatar class is utilized.

MAvatar
+ID: string +Name: string +Description: MAvatarDescription +PostureValues: MAvatarPostureValues +SceneObjects: list +Properties: map<string,string>

Detailed description of available parameters:

Parameter Name	Required	Description
ID	x	The unique ID of the avatar.
Name	x	The specified name of the avatar.
Description	x	The corresponding MAvatarDescription that defines the skeleton hierarchy.
PostureValues	x	MAvatarPosture Values which describe the current posture of the avatar.
SceneObjects		Optional: Scene objects linked to the MAvatar (e.g. Mesh, collider for the avatar). The scene objects are represented by the unique id.
Properties		Additional properties for the MAvatar.

Scene Access

The scene can be accessed in a uniform way using the MSceneAccess. The class and its provided functionality is described in the following:

<<interface>> MSceneAccess

+GetSceneObjects(): list +GetSceneObjectByID(ID: string): MSceneObject +GetSceneObjectByName(name: string): MSceneObject +GetSceneObjectsInRange(position: MVector3, distance: double): list +GetColliders(): list +GetColliderByID(ID: string): MCollider +GetCollidersInRange(position: MVector3, distance: double): list +GetMeshes(): list +GetMeshByID(ID: string): MMesh +GetTransforms(): list +GetTransformByID(ID: string): MTransform +GetAvatars(): list +GetAvatarByID(ID: string): MAvatar +GetAvatarByName(name: string): MAvatar, +GetAvatarsInRange(position: MVector3, distance: double): list +GetSimulationTime(): double +GetSceneChanges(): list +GetFullScene(): list +GetNavigationMesh(): MNavigationMesh +GetAttachments(): list +GetAttachmentsByID(id: string): list +GetAttachmentsByName(name: string): list +GetAttachmentsChildrenRecursive(id: string): list +GetAttachmentsParentRecursive(id: string): list

Detailed description of available parameters:

Function Name	Description
GetSceneObjects	Returns a list of all available scene objects.
GetSceneObjectByID	Returns a scene object based on the specified ID.
GetSceneObjectByName	Returns a scene object based on the given name (might be ambiguous -> First result is returned)
GetSceneObjectsInRange	Returns all scene objects within the specified range.
GetColliders	Returns all colliders within the scene.
GetColliderByID	Returns a collider based on the specified id.
GetCollidersInRange	Returns all MCollider within the specified range (intersecting with sphere as defined by the position and radius).
GetMeshes	Returns all meshes within the scene.
GetMeshByID	Returns a mesh based on the given id.
GetTransforms	Returns all transforms within the scene.
GetTransformByID	Returns a transform based on a given id.
GetAvatars	Returns a list of all available MAvatars.
GetAvatarByID	Returns a MAvatar based on the given id.
GetAvatarByName	Returns a MAvatar based on the given name.
GetAvatarsInRange	Returns all MAvatars within the specified range.
GetSimulationTime	Returns the absolute time of the simulation.
GetSceneChanges	Returns the changes since the last frame.
GetFullScene	Returns the MSceneManipulation to transfer the full scene.
GetNavigationMesh
GetAttachments
GetAttachmentsByID
GetAttachmentsByName
GetAttachmentsChildrenRecursive
GetAttachmentsParentsRecursive

Synchronizable Scene

Despite the previously introduced interface, which is designed from a user perspective, the scene in the target engine, or nested co-simulation needs to provide further synchronization and updating functionalities. For this purpose, the MSynchronizableScene interface is provided.

<<interface>> MSynchronizableScene
+ApplyUpdates(sceneUpdates: MSceneUpdate): MBoolResponse +ApplyManipulations(sceneManipulations: list) :MBoolResponse

Detailed description of available parameters:

Function Name	Description
ApplyUpdates	Applies transmitted MSceneUpdates to the scene. For instance, this might be utilized for a scene contained in an adapter, which continuously buffers the scene (only deltas are transmitted).
ApplyManipulations	Function to apply manipulation as expressed using the MSceneManipulation class. The function is utilized in the target engine/ by the co-simulation to apply manipulations as intended by MMUs (e.g., move object).

Formats for transferring scene information: In order to allow an efficient transfer of the overall scene data, further formats optimized with respect to the data sizes are used. Below a detailed overview of these classes is given.

The MSceneObject class contains all changed elements within the scene.

Scene Update

MSceneUpdate
+AddedSceneObjects: list +ChangedSceneObjects: list +RemovedSceneObjects: list +AddedAvatars: list +ChangedAvatars: list +RemovedAvatars: list

Detailed description of available parameters:

Parameter Name	Required	Description
AddedSceneObjects		List of newly added MSceneObjects.
ChangedSceneObjects		List of all scene object changes.
RemovedSceneObjects		List of the ids of all removed scene objects.
AddedAvatars		List of newly added MAvatars.
ChangedAvatars		List of the MAvatarUpdates.
RemovedAvatars		List of the ids of all removed avatars.

Scene Object Updates

For describing and transferring the changes of a specific MSceneObject, the MSceneObjectUpdate class is used.

MSceneObjectUpdate
+ID: string +Name: string +Transform: MTransformUpdate +Collider: MCollider +Mesh: MMesh +PhysicsProperties: MPhysicsProperties +Properties: list +HandPoses: list<avatar.MHandPose> +Attachments: list +Contraints: list<contraints.MConstraint>

Detailed description of available parameters:

Parameter Name	Required	Description
ID	x	The id of the MSceneObject that should be updated.
Name
Transform		The changed transforms (absolute).
Collider		The collider (if changed).
Mesh		The mesh (if changed).
PhysicsProperties		The changed physics properties.
Properties		A list of changed properties.
HandPoses
Attachments
Constraints

Transform Updates

To efficiently transfer changed transform values, as frequently required during the simulation, the MTransformUpdate class is used.

MTransformUpdate
+Position: list +Rotation: list +Parent: string

Detailed description of available parameters:

Parameter Name	Required	Description
Position		The changed position.
Rotation		The changed rotation.
Parent		The changed parent.

Property Updates

To describe changes with respect to properties. The MPropertyUpdate class is provided, which is outlined below.

MPropertyUpdate
+Key: string +Value:string

Detailed description of available parameters:

Parameter Name	Required	Description
Key	x	The key of the property, which is adjusted/added.
Value	x	The value of the property.

Avatar Updates

The MAvatarUpdate class is used to describe all occurred changes regarding a specific MAvatar. In particular, the changes can include changed posture values, properties, the description itself or the involved list of scene object IDs.

MAvatarUpdate
+ID: string +PostureValues: MAvatarPostureValues +SceneObjects: list +Description: MAvatarDescription +Properties: list

Detailed description of available parameters:

Parameter Name	Required	Description
ID	x	The unique ID of the avatar, which should be manipulated.
PostureValues		The changed posture values of the avatar (if defined).
SceneObjects		The changed assignment of scene objects (if defined).
Description		The adjusted description of the avatar (if defined).
Properties		A list of changed properties.

Attachment

MAttachment
+Parent: string +Child: string +Type: string

Detailed description of available parameters/functions:

Parameter Name	Required	Description
Parent
Child
Type

MAttachmentManipulation
+Parent: string +Child: string +AddRemove: bool +Type: string

Detailed description of available parameters/functions:

Parameter Name	Required	Description
Parent
Child
AddRemove
Type