ORT 3.

1 Applications Manual

bitwave
March 25, 2012

Contents

List of Tables 1

List of Figures 1

1 ORT Modeller 3
1.1 Running the Modeller . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Interface Elements . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 The Vehicle Panel . . . . . . . . . . . . . . . . . . . . . 3
1.2.2 The Details Panel . . . . . . . . . . . . . . . . . . . . . 3
1.2.3 The Browser Panel . . . . . . . . . . . . . . . . . . . . . 4
1.2.4 The GNC Panel . . . . . . . . . . . . . . . . . . . . . . 4
1.2.5 The Logical View . . . . . . . . . . . . . . . . . . . . . . 4
1.2.6 The Trajectory View . . . . . . . . . . . . . . . . . . . . 5
1.2.7 Curve Panels . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3.1 Load a model file . . . . . . . . . . . . . . . . . . . . . . 5
1.3.2 Preparing for work . . . . . . . . . . . . . . . . . . . . . 6
1.3.3 Launching a vehicle . . . . . . . . . . . . . . . . . . . . 6

2 ORT Live 9
2.1 Map View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1.1 Elements of the Map . . . . . . . . . . . . . . . . . . . . 9
2.1.2 Camera Control . . . . . . . . . . . . . . . . . . . . . . 10
2.2 Logical View . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3 Invoking ORT Live . . . . . . . . . . . . . . . . . . . . . . . . . 11

1
3 ORT Headless 13
3.1 Invoking ORT Headless . . . . . . . . . . . . . . . . . . . . . . 13
3.2 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

List of Tables

0.1 ORT application overview . . . . . . . . . . . . . . . . . . . . . . . 2

2.1 Keys for camera control within the map view. . . . . . . . . . . . . 11

2.2 ORT Live command line options . . . . . . . . . . . . . . . . . . . 12

3.1 Headless driver command line options . . . . . . . . . . . . . . . . 13

3.2 ORT logger types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

List of Figures

1.1 The simulation configuration dialog. . . . . . . . . . . . . . . . . . 6

2.1 A typical view of ORT live. . . . . . . . . . . . . . . . . . . . . . . 10

2
List of Figures 3

Table 0.1: ORT application overview

Application Name Description
Modeller An editor for ORT models. Reads and writes XML
files that are consumed by the other applications.
Live Playback of launches.
Headless Non-interactive, command-line driven logging of a
simulation to spreadsheets for further processing via
external applications.

ORT is a collection of Java applications tailored to different tasks. Table 0.1

presents an overview over the applications that make up the ORT distribution.
Chapter 1

ORT Modeller

1.1 Running the Modeller

On Windows systems, the modeller can be launched via the included command
file aptly named run-modeller.cmd, and knowing the Linux users they will
have no issues whatsoever with deriving a suitable launcher from this.

1.2 Interface Elements

The Modeller opens with the main window visible, which contains the following
areas:

1.2.1 The Vehicle Panel

The purpose of the view panel is to provide access to all the vehicles present
in a model file and list all components the vehicle is made up of, including the
properties determining the characteristics of the components.
At the top of the Vehicle panel is the combo box for selecting the currently
active vehicle.
Although the view panel provides a complete summary of an entire vehicle,
it is unwieldy for large models because of the many components they contain.

1.2.2 The Details Panel

The details panel always shows the properties of the component currently se-
lected in the logical view. It serves as a property editor to quickly access the
component to work on. In addition to the physical attributes displayed in
the vehicle panel, the details panel also provides a checkbox for filing compo-
nents to the browser, lists the attributes documented on a component and its
reference data.
Attributes are always numerical in nature and can be added via the “New
Attribute” button. After the input dialog that queries the attribute name is
confirmed, the attribute will appear in the details panel. An attribute must

5
6 CHAPTER 1. ORT MODELLER

have one or multiple sources to be meaningful, and those can be added via the
attribute’s context menu. This menu also provides an entry for deleting the
entire attribute. Attribute sources provide four fields: number, unit, URL and
annotation. The number holds the effective attribute value in the indicated
unit. The URL specifies from where the attribute was taken. It is perfectly
legal to type a bibliography entry into the URL. The annotation can be used
to document additional information about the quality of the source, e.g. “ap-
proximate” if the value is not precise.

1.2.3 The Browser Panel

The browser panel lists all components “filed” as reusable components and
supports drag-and-drop into the logical view. This way, a logical model can
quickly be built by reusing existing stages, engines and the various default
components shipped with the modeller. Any component can be filed simply
by toggling the corresponding checkbox in the Details panel. Normal dragging
creates a copy of the template. shift ctrl -dragging creates a link, so it is possible
for the same component to appear in multiple views. Fundamental components,
shown as “New ...”, cannot be linked.

1.2.4 The GNC Panel

The GNC panel summarizes all guidance, navigation and control (GNC) com-
ponents present in the vehicle currently selected in the vehicle panel. This is
the place where the trajectory of a vehicle is defined. Commands are added to
a ProgrammedGNC by dragging them from the browser onto the GNC com-
ponent, after which they are available for further editing in the GNC panel.

1.2.5 The Logical View

The logical view presents one of the vehicle diagrams (“schematics”) present
in the model file. The purpose of the logical view is to provide a graphical
view of a vehicle, including all stages and components that define the vehicle’s
behavior, and allow the user to work on the diagram. The bottom of the view
features a combo-box for switching between existing diagrams.
Components can be added to a vehicle by dragging them into the logical
view. A single component in the view can be selected by left-clicking, which
will also train the Details view on it. Multiple components can be selected
by surrounding them with a selection rectangle, which is done simply by left-
dragging the mouse beginning on an empty spot on the diagram. By holding
the Alt key, a selection rectangle can be drawn even within a larger component.
Selected components can be moved by click-dragging them. A single selected
component can be resized if the component allows to do so, which is indicated
by a solid square at the bottom right corner. shift ctrl -dragging from one
component to another will “put” the former into the latter, which affects the
model structure and thus the behavior of the vehicle.
1.3. TASKS 7

New diagrams can be created by selecting “Edit | New Diagram...” from

the main menu.
The logical view can be panned by shift -dragging the canvas, and zoomed
by turning the mouse wheel.

1.2.6 The Trajectory View

The trajectory view displays all celestial bodies included in the simulation and
the trajectories of all individual mass points traced during the last launch. The
view’s context menu can be used to change the view plane. The first three en-
tries in the menu align the view with the three principal planes in the reference
frame of the celestial root body. Depending on the vehicle that was launched,
additional entries become avilable - one for each GNC component used in the
simulation. For trajectory optimization, the view should be aligned with the
GNC component governing the relevant part of the trajectory, because that
way the trajectory will be free of distortions introduced by the view projection.
The launch view can be panned by shift -dragging the canvas, and zoomed
by turning the mouse wheel. It is currently not possible to set an arbitrary
rotation of the view plane.

1.2.7 Curve Panels

The curve panels provide insight into the performance of the vehicle post-
launch. If the vehicle model contains reference data, the data will be overlaid
on top of the graphs. Curve panels can be zoomed and panned just like the
logical view and the trajectory view.

1.3 Tasks
This section details common tasks performed in ORT Modeller.

1.3.1 Load a model file

ORT saves its workspace into model XML files. These files can contain any
number of vehicles, celestial bodies and diagrams. ORT can load different
files sequentially, but only one file can be open at any time. It is currently
not possible to merge or link files, so care must be taken to group everything
required for a simulation into the same file. Because model files tend to be
rather small in size, it’s not the worst practice to stick everyting into a single
file.
The modeller starts up with an empty workspace, so the first action usually
consists in loading an existing model file. This can be done via “File | Load. . . ”
in the application’s main menu. The file selection dialog always opens in the
ORT work directory which can be configured with command line option “-
Dort-work-folder”.
8 CHAPTER 1. ORT MODELLER

Figure 1.1: The simulation configuration dialog.

After loading a model file, the combo-box in the Vehicle Panel will list all
vehicles contained in the model. The combo-box at the bottom of the Logical
View Panel will list all the diagrams contained in the model.

1.3.2 Preparing for work

Preparing for work consists of selecting the vehicle to work on in the Vehicle
Panel and the corresponding diagram in the Logical View Panel. Because there
can be multiple diagrams for the same vehicle, or even a diagram containing
multiple vehicles, ORT cannot automatically open the “right” diagram for the
vehicle selected.
bitwave There is a pending task for improving usability in case the vehicle appears
on only one diagram.

1.3.3 Launching a vehicle

F5 or entry “File | Launch" in the main menu brings up the simulation con-
figuration dialog shown in figure 1.1.
The duration specifies the number of seconds that will be simulated, begin-
ning at simulation time 0.
bitwave ORT currently has no notion of real world time and is not capable of
modelling a true representation of the solar system. This will very likely change in
the future.
1.3. TASKS 9

The resolution specifies the step size of the Euler integration. A simulation
of 200 s with a resolution of 0.1 s will log 2000 data points for position, velocity,
acceleration etc, each.
bitwave The resolution mechanism is a temporary hack. ORT will most likely
introduce automatic adaption of resolution based on the launches being simulated.
bitwave Care must be taken when simulating long periods at high resolution. Out
of memory exceptions loom because ORT does not yet perform any checks on the
memory required by a simulation.
The celestial body specifies the root body of the simulation. Celestial bodies
are modelled in exactly the same way as launch vehicles, see diagram “Celestial
Bodies” included in the models.xml file distributed with ORT. Any celestial
body defined in the workspace is made available in this combo-box. All detail
bodies of the root body are automatically included in the simulation.
bitwave In this release, ORT does not yet realize the detail bodies of a celestial
body in the simulation.
The “launches” table is used to configure all vehicles launched during the
course of the simulation. Each launch record specifies the vehicle to be launched,
the launch site, the T0 offset from simulation time 0 and the azimuth of the
trajectory plane. A launch always takes place from ground level, and the ve-
hicle will rotate along with its parent body until it actually takes off. The
default azimuth of 90◦ launches the vehicle in an eastward direction, and the
inclination of the trajectory plane depends solely on the latitude of the launch
site. An azimuth of 0◦ launches the vehicle towards true north, however, the
inclination of the trajectory plane will not be 90◦ for almost any launch site
due to the longitudinal velocity imparted to the vehicle at launch time as a
result of the rotation of its parent body.
bitwave ORT is currently limited to a single launch per simulation.
Chapter 2

ORT Live

ORT Live plays back launch simulations in real time or using an arbitrary time
lapse/dilatation while providing visual feedback on the vehicle state. Unlike
the modeller it does not offer any editing functionality but relies on existing
models and the data is only visualized for a particular moment in time, as
opposed to an entire simulation run. Consequently, at T0 the user has no cue
as to how the launch will actually develop. On the other hand there is no
predetermined end to the integration like in traditional simulation runs – the
simulation is open-ended.
As of ORT 3.0, the live application supports rendering of the universe map
via jME31 .
The application window consists of two areas (see figure 2.1) separated by a
movable splitter. The left hand side houses the map view, which initially shows
the celestial root body as a textured sphere, including any locations defined on
the body model and a position indicator for the vehicle being launched. The
right hand side displays the first logical view that features the vehicle to be
launched. This view corresponds to the logical view used in the modeller, but
minus the editing functionality.

2.1 Map View

The map view presents a 3D projection of the current simulation state with
the intent of providing visual cues as to the position of objects. The goal is not
to display a photo-realistic image of the scene but to allow the user to examine
the simulation state. The map is always rendered from a bird’s eye perspective
and the camera can be moved around at leisure.

2.1.1 Elements of the Map

Elements displayed on the map include celestial bodies, vehicle mass point
indicators, labeled location indicators and planes.
1 JMONKEYENGINE 3.0, see http://jmonkeyengine.com/

11
12 CHAPTER 2. ORT LIVE

Figure 2.1: A typical view of ORT live.

The map view is theoretically capable of rendering any celestial body con-
tained in the model file being used. However, because texturing of the body is
currently still hardcoded against the name of the body, only “Earth”, “Mars”
or “Moon” will actually work at this point. In the future, celestial bodies will
feature a code to which texturing can be bound, allowing multiple bodies to
share the same texture, or use none at all.
For each celestial body, the equatorial plane is indicated with a light blue
disc.
Vehicle mass points are represented as black and white spheres. The local
+X vector (pointy end) is indicated by means of a white disc, the local -X
vector (business end) by a red disc. For vehicles that contain an active GNC
component, a light red disc is displayed to show the orientation of the trajectory
plane.

2.1.2 Camera Control

The view can be manipulated using the mouse and keyboard (see table 2.1).
The map panel must be focused by clicking into it before it can be controlled
through mouse and keys.
If the camera is attached to an object by right-clicking it, that object will
be tracked until the connection is broken by an explicit camera movement via
the WASD keys.
 2.2. LOGICAL VIEW 13

Table 2.1: Keys for camera control within the map view.
Key Function
w move the camera upwards.
a move the camera to the left.
s move the camera downards.
d move the camera to the right.
q roll the camera counter-clockwise.
e roll the camera clockwise.

The view direction is adjusted by left-clicking and dragging inside the map
panel. The camera always revolves around a point ahead of the camera, and
the distance of the camera to that point can be adjusted via the mouse wheel.
The camera can be flicked to induce a continuous spin that will only dampen
out slowly. Keep the mouse still for a fraction of a second before releasing the
mouse button to avoid accidental spinning.

2.2 Logical View

The logical view behaves in the same way as in the modeller, so it can be panned
and zoomed. The view always reflects the current state of the vehicle model
it represents, which can be seen in propellant tanks draining during burns and
gross mass numbers being updated. During staging, additional mass points
appear in the map view, but the logical view always shows the summary of the
entire vehicle.
Because there is only a single logical view, ORT Live is currently limited
to single launches. This will change in the future.

2.3 Invoking ORT Live

ORT Live does not provide a user interface for configuring launches but instead
relies on command line arguments (see table 2.2 for options). Launches are
specified in the same way as for the headless driver. Listing 2.1 shows an
invocation example for launching the Vauguard off the surface of Earth, using
JME as the visualization engine.

Listing 2.1: Sample invocation of ORT Live.

1 j a v a −c l a s s p a t h " c l a s s e s ; l i b \∗ " ch . bitwave . o r t . d r i v e r . H e a d l e s s −m
models . xml −v JME −r Earth " Vanguard ␣S1 "
14 CHAPTER 2. ORT LIVE

Table 2.2: ORT Live command line options

Short Name Long Name Description
m model-file Specifies the path and name of the model file.
r root-body Specifies the name of the root celestial body of the
simulation.
v visualization Specifies the render engine to use for 3D content.
Possible values are SWING and JME.
 Chapter 3

ORT Headless

The headless driver is a non-interactive command line application for running

ORT simulations. The driver reads a model file, configures a simulation based
on elements contained in that file and outputs the results of the simulation into
a specified directory.

3.1 Invoking ORT Headless

Listing 3.1 shows an example command line invocation of the headless driver
for launching the Vanguard from planet Earth (both defined in ‘models.xml”),
simulating 10000 seconds at a resolution of 0.1 seconds with output being
written to the "logs" folder. Refer to table 3.1 for a summary of available
options.

Listing 3.1: Sample invocation of the headless driver.

1 j a v a −c l a s s p a t h " c l a s s e s ; l i b \∗ " ch . bitwave . o r t . d r i v e r . H e a d l e s s −m
models . xml −d 10000 −s 0 . 1 − l l o g s −r Earth " Vanguard ␣S1 "
Regular arguments (everything that is not an option) are interpreted as
launch specifiers. Currently, a launch specifier only contains the name of a
logical component that should be launched, and the launch site always is at

Table 3.1: Headless driver command line options

Short Name Long Name
m model-file
l log-folder
r root-body
d run-duration
s step-size
Description
Specifies the path and name of the model file.
Specifies which folder the logs are written to.
Specifies the name of the root celestial body of the
simulation.
Specifies the number of seconds to simulate. Default
is 200 s.
Specifies the step size in s. Default is 0.1 s.

15
16 CHAPTER 3. ORT HEADLESS

Table 3.2: ORT logger types

Name Unit Dimensions Description
position m 3 The position vector of the mass point.
Frame of reference is the Universe.
velocity m s−1 3 The velocity vector. Frame of reference
is the surface of the parent body, so ve-
locity will initially be zero regardless of
the latitude of the launch site.
mach 1 1 The current mach number within the
atmosphere of the parent body.
acceleration m s−2 3 The acceleration vector.
altitude m 1 The altitude above the surface of the
parent body.
drag N 1 The atmospheric drag force acting on
the vehicle.
grossMass kg 1 The gross mass of the vehicle.
pitch rad 1 The angle between the +X axis at
launch time and the current +X axis
of the vehicle.

longitude 0 and latitude 0 of the root body. This is going to change in future
ORT releases.

3.2 Output
The headless driver creates the folders along the output path, so there is no need
to prepare them manually. The actual files written to the log folder depend on
the loggers attached to the mass points, which are currently hardcoded but will
be open to configuration in the future. The same loggers are used internally
in the modeller to record the data displayed in the performance charts after a
launch. Currently, ORT supports the loggers summarized in table 3.2.
Log files are written in CSV format, with each logger writing to its own file.
The files do not contain header lines and are named according to the logical
element associated with the mass point for which the logging is done, suffixed
with the logger name shown in table 3.2.
Example: The velocity of the masspoint for the first stage of the vanguard
is logged to file “Vanguard S1 velocity.csv”, because element “Vanguard S1” is
the root element of the Vanguard stack and the name of the velocity logger is
“velocity”.
Depending on the number of dimensions of the data element being logged,
the CSV will contain two or five columns. For one-dimensional elements, the
first column is the simulation time in seconds and the second column is the ele-
ment value. For three-dimensional elements, the first column is the simulation
3.2. OUTPUT 17

time, followed by three columns for x, y and z components. The fifth column
contains the vector length.