Scenario Tools Visualization
Design Description
Version 1.0
Doc. No.:
ScenarioTools Visualization
Design Description
Version:
1.0
Date: 2009-10-15
Revision History
Date
Version
Description
Author
2009-10-14
0.01
Initial Draft
Josip Jurić
2009-10-15
0.02
Added section 2
Daniel Loechelt
2009-10-15
0.03
Wrote and illustrated sections 3.[1-2]
Mikael Krekola
2009-10-15
0.04
Wrote Detailed Software Design
Miroslav Vrbanac
2009-10-16
0.05
Added introduction
Zvonimir Zoltán Marić
Page 2
ScenarioTools Visualization
Design Description
Version:
1.0
Date: 2009-10-15
Table of Contents
1. Introduction ........................................................................................................................................................ 4
1.1 Purpose of this document .................................................................................................................................. 4
1.2 Intended Audience ............................................................................................................................................ 4
1.3 Scope ................................................................................................................................................................. 4
1.4 Definitions and acronyms ................................................................................................................................. 4
1.4.1 Definitions
4
1.4.2 Acronyms and abbreviations
4
1.5 References ......................................................................................................................................................... 4
2. External interfaces .............................................................................................................................................. 4
3. Software architecture .......................................................................................................................................... 6
3.1 Conceptual design ............................................................................................................................................. 6
3.2 System specification ......................................................................................................................................... 6
3.3 Error handling ................................................................................................................................................... 7
4. Detailed software design..................................................................................................................................... 7
4.1 STSimulation .................................................................................................................................................... 8
4.2 jME .................................................................................................................................................................. 8
4.3 Physics model ................................................................................................................................................... 8
4.4 Visualization model ........................................................................................................................................ 10
4.5 GUI ................................................................................................................................................................. 10
5. Approvals ......................................................................................................................................................... 11
Page 3
1.
Introduction
1.1
Purpose of this document
The purpose of this document is to present the design and architecture of the ScenarioTools visualization project
software. It sets a rigorous foundation and guideline for modular development with low coupling which is
crucial for this type of project as its functionality will be continuously and extensively broadened. During the
development process, this document will reflect the iterative development method. In other words, this design
description will incrementally improve during the development process.
1.2
Intended Audience
This paper is used both as documentation and a development guideline. Therefore it will be primarily used by
the developers (both during first system implementation and later redefinitions). On the other hand, it gives a
thorough overview of the most important concepts for the solution, providing detailed feedback for the
customers and supervisors of the project.
1.3
Scope
The design and architecture described in this document is subject to frequent changes throughout the lifespan of
the development process because of continuous increments on the planned functionality. Therefore at each
revision, this document will contain the design of what is already implemented and what yet needs to be
implemented, until the final revision.
1.4
Definitions and acronyms
1.4.1
Definitions
Keyword
Ecore model
RailCab
Java Monkey Engine
2.
Definitions
A new means of transportation developed by Neue Bahntechnik
Paderborn. The primary target of the ScenarioTools simulator.
An open source graphics framework used for creating the 3D
visualization part in this project.
External interfaces
The external interfaces are offered by the Scenariotool developed in Paderborn. The visualization
shall visualize the simulation of the Scenariotool. For this purpose, the simulation model is required to
assign objects of the simulation model with 3D objects. The simulation model is created by an EMF
generated editor and made available as an xmi file. The structure of the simulation model is described
by an Ecore model. The behavior of the modeled objects is described in an UML file by multiple
modal sequence diagrams (MSD). Furthermore the interface of the simulation is required to
dynamically visualize the simulation. For this, the simulation of the Scenariotool is component based.
The following figure gives an overview of the component architecture of the simulation of the
Scenariotool.
The
simula
tion
control
ler is
the
core
compo
nent
and
mana
ges all
requir
ed
model
s as
well as all input and output events. One of its tasks is it to handle the commands that are issued via
the IControl interface. User feedback and control commands are forwarded to or received by the GUI
and passed through to the simulation controller.
The most important interface for the visualization is ISimulation. The following class diagram gives an
overview of this interface and its functionality.
The interface to the visualization is event-based and thus uses the observer pattern. The simulation
provides the interface ISimulation which offers methods to fire events and to add a visualization as
observer/listener. To observe the simulation a visualization needs to implement the interface
IEventListener . Its method notify() is called whenever an event occurs. So the visualization has to
register as a observer to the simulation via the addEventListener() method. The visualization always
gets notified when an event is fired in one or multiple sequence diagrams. An event can be for
example a sending of a message which describes e.g. that a railcab stops. These events then have to
be used for the visualization. How the events look like is illustrated in the following class diagram
which defines the event model.
A
ControlE
vent
can be
fired on
the
simulatio
n to
start or
stop the
simulatio
n etc.
MsdEve
nts are fired by the simulation and originate from active MSDs. They can either be part of
the environment or the system (this can be determined by the method isEnvironment() ). SendEvents
and ReceiveEvents describe the send/receiving of a message. A SendEvent is fired when a message
is sent by an object/Lifeline and a ReceiveEvent is fired when it arrives at its destination
object/Lifeline. An AssignmentEvent is fired when an Assignment on a Lifeline is executed. The
HotViolationEvent is fired if a hot violation occurred. This means that behavior is executed which
should not happen and therefore has to be visualized correspondingly.
A PossibleStepsEvent is fired by the simulation when the list of steps (sending, receiving etc.), that
can be executed next, changes. Its method returns a list of the possible steps.
HiddenEvents are solely used by the simulation algorithm and are not part of the interface.
With the described interfaces and the event model the visualization can get informations from the
simulation. These informations are used by the visualization to visualize the simulation.
3.
Software architecture
3.1
Conceptual design
The ScenarioTools Visualization project will be realized as an Eclipse plug-in. The component communicates
with a Simulation plug-in as described in chapter 2. When the Simulation sends an event to this visualization
plug-in, it will allow a physical representation of the simulators object (ecore object) model to react to it. It will
also render the current state of this physical representation for the user to inspect and navigate.
The plug-in will be divided into a set of components;
 A Graphics Engine that supplies the other components with an interface to render graphics.
 A Physics Model that consists of a set (container) of physical objects representing the objects in the
Simulator compoent. The component is also responsible for calculating the physical behaviour of
objects and interact with the Simulator's generated events.
 A Visualization Model that inherits all of the properties of (and thus also depends heavily on) the
Physics Model. The component extends the behaviour to visualize the content of the physical objects
with the specific Graphics Engine interface.
 A Graphical User Interface (GUI) component that allows the user to see and interact with the
Visualization Model.
One of the main drivers for separating the Physics Model and the Visualization Model is as described in the
Project risks; we need to “Design a flexible, extensible and well-formed front-end object model”. This
separation allows multiple Visualization models to be developed for the same physical model.
3.2
System specification
Because the project has to be an Eclipse plug-in, the GUI component will have to use SWT (The Standard
Widget Toolkit).
To comply with req. 2.5.1; the Graphics Engine needs to be a graphic component that supports 3D graphics.
Several such engines was evaluated:
 Java OpenGL (JOGL)
 Java 3D
 Lightweight Java Game Library (LWJGL)
 jMonkey Engine (jME)
Both the Java 3D and jME provides a scene graph based interface allowing the developers to think about
behaviour and not as much on polygon positioning and rendering flags. The development team decided to use
jME because of its ease of use. It supports many common 3D model formats and the community provides
several tutorials. JME also has an SWT canvas widget, that allows it to easily integrate with Eclipse.
How the different components interact is illustrated with the following component diagram:
More detailed information about the structure and behaviour of the components and the definitions of the
interfaces are explained in chapter 4.
3.3
Error handling
Error
4.
Action
Detailed software design
As explained in section 3 the software architecture is divided into 5 parts:
1.
2.
3.
4.
5.
STSimulation
jME
Physics model
Visualization model
GUI
This part of documentation will explain them in more detail.
4.1
STSimulation
Simulation model is the external part of the project and it is explained in detail in other document.
4.2
jME
Classification : jME (jMonkey Engine) is a high performance scene graph based graphics API. It is included as
external package in the project.
Definition: The purpose of this component is rendering scenes and objects on the screen. It is a flexible package
that can use any rendering system to be plugged in, such as JOGL or LWJGL. That will allow this software to
work on any platform, the only thing that will have to be changed is native rendering library.
Responsabilities: This package will be used to render scenes and objects. It will also provide a way to
manipulate with camera to Visualization part described in section 4.3.
Uses/Interactions: This package calls PhysicsModel to get information about how to update objects that jME
itself is rendering.
Resources: This package relies on some of the native rendering libraries such as LWJGL. That library should be
referenced from the project.
4.3
Physics model
Figure 4.3.1 Physics model
Figure 4.3.2 Physics and Visualization models
Classification : Physics model is a package that is responsible for interaction between STSimulation and
visualization part of the project.
Definition: The specific purpose of this part is to define objects that correspond to ecore objects. Those ecore
objects are provided by STSimulation part and these are the objects and their interaction is needed to be
visualized. It will have information about all the objects provided and shown on the scene. In every moment of
the visualization this part will have information about position of all objects and about their movement. The
movement is calculated by this part of the project. Physics model also provides STSimulation part about events
that occurred. These events can be possible hazards, collisions…
Responsabilities: Mapping ecore objects to visualized objects, providing movement logic, providing information
about the events to STSimulation part
Constraints: Physics model should not use jME, jME is used from Visualization part, but this part provides
information about position of the objects
Uses/Interactions: Physics model is shown in figure 4.3.1. Physics model interacts highly with STSimulation
part. It also interacts with Visualization part since it contains interfaces that are implemented by Visualization
part. This interaction is shown in Figure 4.3.2. The figure can be explained in next sentences: There is one
JMEModel that is a class inherited from PhysicalModel that contains provisional number of instances that of
type PhysicalObject. PhysicalObject is inherited by PhysicalTrack, PhysicalCurvedTrack and PhysicalRailCab.
The physical objects don’t have visual representation, but they calculate positions and movements of
themselves. That is because JMETrack, JMERailCab and JMECurvedTrack exist. These objects implement
VisualObject interface and the most important method this interface provides is updateVisual. Every object that
has to be visualized will have information about position and movement provided by PhysicalObject and
calling updateVisual method will call jME package to render this object on position that is is currently at. This
way the physics and visualization part are decoupled as much as they can be.
4.4
Visualization model
Classification : Visualization model is a part that is responsible for controlling jME. It gives information to jME
about where to render objects that need to be visualized.
Definition: The specific purpose of this part is to provide objects that correspond to physical objects. Physical
objects have information about their position and calculate their movement but they do not render themselves on
those positions. Objects in this part inherit from physical objects and also have methods that will be called to
provide information to jME about where to render each object. The visualization part is shown on figure 4.3.2.
Responsabilities: Providing objects that contain methods to be called by jME. These methods have information
about where to render the objects.
Constraints: This layer does not do any calculations, just responsible for providing information about where to
render the objects.
Uses/Interactions: This layer interacts highly with jME and Physics model. Interaction with Physics model is
described in section 4.3 in Uses/Interaction part.
Resources: Uses jME library
4.5
GUI
Classification : GUI is a library that is responsible for user interaction with the system
Definition: GUI is a part that provides graphical user interface for creating and observing visualization. There
will be two modes of GUI. One mode is “World editor” mode that gives the user a possibility to position objects
on the scene. The second part is visualization mode for observing the visualization. This part also contains
window for observing this visualization.
Responsabilities: Positioning of non-moving objects on the scene, and initial positioning of moving objects on
the scene. Observing the visualization.
Uses/Interactions: This This part is imagined to be similar to shown below, in the middle of the screen is a part
where the scene will be shown and where the visualization will be able to be observed :
Figure 4.5 World editor
When in “World editor” mode user will be able to drag and drop objects from the list of objects on the left side
on the scene. The objects on the left are ecore objects that will have to be visualized. Once the object is dropped
on the scene it gets a physical and visual representation and is shown on the right part of the screen.
User can then enter visualization mode and the visualization will be ran in the center of the screen. There will
also be shown a list of events that occurred during the visualization running. So the user will be able to browse
the events and focus on the point where last event occurred.
The camera movement will be done by keyboard and mouse.
Resources: Collects input from mouse and keyboard.
Interface/Exports: Exports provide information about how the visualization was running so that information can
later be loaded back or analyzed in the future.
5.
Approvals
Name
Josip Jurić
Zvonimir Zoltán Marić
Miroslav Vrbanac
Jens Frieben
Sascha Burdick
Daniel Loechelt
Mikael Krekola
Mohsin Khan
Vinay Hiremath
Title
Mr.
Mr.
Mr.
Mr.
Mr.
Mr.
Mr.
Mr.
Mr.
Date
yyyy-mm-dd
2009-10-14
2009-10-16
2009-10-16
2009-10-16
2009-10-16
2009-10-16
2009-10-16
2009-10-16
2009-10-16
Signature