Open-DIS - SourceForge

currygeckoSoftware and s/w Development

Dec 2, 2013 (3 years and 8 months ago)

58 views

Open
-
DIS

Open Source Distributed Interactive
Simulation

Don McGregor (mcgredo at nps dot edu)

Don Brutzman (brutzman at nps dot edu)

John Grant (johnkonradgrant at yahoo dot com)

Open
-
DIS

Very few open source DIS implementations to date. We’ve done a
couple for Java, but there are none that I know of for C++

This results in duplicated effort as people re
-
implement the wheel

You can buy a commercial license, but this tends to not work well
in an academic environment, or for projects with extremely long
product life cycles

It takes time and effort to sort out licensing and stay within the
license requirements, and avoiding this is valuable

What happens if the vendor goes away?

Free

is an easy to licensing concept understand and work with

Licensing

Open
-
DIS uses the BSD open source license. Anyone
can use or modify the code, and it is non
-
viral; using
Open
-
DIS in your project does not make your project
open source

You can modify the code if you like

You do not have to return changes to the authors
(though this is appreciated and encouraged)

You can use it in commercial products

No license fees

Just use it!


Implementation Features

Java and C++ code implementation with a
similar API

Java and C++ PDU objects can marshal
themselves to DIS format

Java objects can also marshal themselves to
XML and Java Object Serialization format

An XML schema is provided

Some supporting networking code and example
implementations

Availability

http://sourceforge.net/projects/open
-
dis/

Code is available as both tar.gz and subversion
source code control downloads

Sourceforge forums and mailing lists for tech
support

Full source code, not just binary releases

Implementation

The Java and C++ code was generated from an
XML template

From this:


<attribute name="x" comment="velocity about the x
axis">


<primitive type="float" defaultValue="0"/>


</attribute>


Implementation

To this in Java:

public class AngularVelocityVector


extends Object implements Serializable

{ /** velocity about the x axis */

protected float x = 0;



public void setX(float pX)

{ x = pX;}


@XmlAttribute

public float getX()

{ return x; }

Implementation

And this in C++

AngularVelocityVector::AngularVelocityVector():


_x(0),_y(0), _z(0)

{}


AngularVelocityVector::~AngularVelocityVector(){}


float AngularVelocityVector::getX() const

{return _x;}


void AngularVelocityVector::setX(float pX)

{x = pX;}

Implementation

Getters, setters, constructors, and destructors for each
PDU and sub
-
PDU object

Each PDU also has code to marshal itself to DIS format,
and unmarshal itself

The “@XmlAttribute” annotations specify how the java
objects should be marshalled to XML; in this case the
X field will be marshalled as an attribute to the
AngularVelocityVector element

<
AngularVelocityVector … x=“17.0”/>


Implementation

XML

Template

C++ Code

Generator

Java Code

Generator

C++

.h, .cpp

files

Java

Source

Files

C# Code

Generator

C#

Source

Files

Implementation

If there are fundamental changes, we can modify the
template code and re
-
generate the C++ and Java
code

This code that generates C++ and Java is also provided
if you want to do something different, or you can do
another language generator if you like

About 4KLines of template XML and 1KLines of code
generation to create ~30KLines of C++ and
~20KLines of Java

The generated Java and C++ is checked into source
code control, so we can modify it directly as well

Implementation

Drawbacks to the approach: the classic problem
of modifying code that is autogenerated.
Changes are lost if you regenerate code after
modifying it

Work around this by using automated patch
files; apply patches after generation to regain
manual edits

Why Not Schema

Originally we attempted to use XML Schema as the basis for
generating Java and C++ source code

• C++ schema
-
to
-
code tools generated lousy code

• The generated code didn’t handle variable length lists well

• Parsing schema is complex, and there is no semantic link
between variable length lists and the list length fields

• Different C++ and Java APIs

The template XML file and code generator gives us complete
control over how the Java and C++ source code looks, and
turned out to be not that difficult to write

XML

JDK 1.6 gives us the ability to marshal and
unmarshal XML to and from Java objects via
JAXB, which is built into the JDK release

Can generate a schema for DIS from the Java
source code (provided)

As a result we get XML interoperability for free

Efficient XML Interchange

EXI is a W3C working group activity to design a more
compact, faster to parse representation of the XML
infoset

Exactly equivalent to an XML document, only in a more
compact and faster to parse format

Relaxes XML’s text
-
only rule, implements many
compression techniques, faster to parse than gzip of
text XML

Working group is releasing to “final call” status as we
speak


EXI

Interesting outcome: DIS in XML format run through
EXI results in slightly smaller ESPDUs

Roughly 135 bytes per plain ESPDU vs. 144 for IEEE
DIS when encoding with the DIS schema

There is some variation in EXI PDU sizes depending on
the nature of the data, so they will sometimes be
larger, but the general trend seems to be “about the
same size or smaller”

This has interesting implications for DoD
communications protocols: why not specify the
protocol in XML, send it on the wire in EXI, results in
about the same size as a plain binary message

Class Hierarchy

Pdu

Entity State

PDU

Entity

Interaction

Family

Collision

PDU

Warfare

Family

PDU

Fire

PDU

Detonation

PDU

Object Hierarchy

PDUs also contain objects for major records,
such as position, EntityType, orientation, etc

EntityID

EntityType

AltEntityType

Location

ESPDU

Object Hierarchy

The major records defined in the DIS standard
are represented as objects, such as location,
an object that contains three double precision
floating point numbers

The object knows how to marshal and
unmarshal itself

Garbage Collection

This can create a problem when receiving a lot of PDUs. Every time
a new PDU is created it may contain several objects within it

In Java this stresses the garbage collector in realtime operation

Observation: the vast majority of PDUs are ESPDUs. If we can
optimize that we will solve most of the problem

The FastEntityStatePdu class “flattens” the object structure of
entity state PDUs and consists only of primitive type fields

Eliminates 11 objects per ESPDU

Supporting Java Classes

PduFactory creates new Open
-
DIS PDU objects
from binary data

Logger example saves PDU traffic to XML files

X3D example shows DIS being used to drive a
3D scene

XMPP example shows DIS in XML format being
sent across chat channels

C++ Classes

Essentially identical to the Java classes, but
lacking XML support

Uses HawkNL library for networking support.
(You can also use plain old Berkeley sockets if
you like)



Enumerations

There are a lot of arbitrary numbers associated
with DIS (and HLA) called Entity Bit Values.
Every PDU type has a number assoicated with
it: ESPDU=1, Fire=2, etc

These are included in the wire format

It is inconvienient for programmers to work
with magic numbers, so we want symbolic
names to be associated with those

This is done via enumerations

Enumerations

Luckily, SISO has an XML document that
describes these values called the EBV
document

<enum length="8" id="2" cname="pduheader.pdutype"
name="PDU Type" source="3.2">


<enumrow id="0" description="Other"/>


<enumrow id="1" description="Entity State"/>


<enumrow id="2" description="Fire"/>


Enumerations

So: we read in the XML document and use the
information contained in that to generate
programming language enumerations

public enum PduType {


OTHER(0, "Other"),


ENTITY_STATE(1, "Entity State"),


FIRE(2, "Fire"),

Future Work

Not all PDUs correctly implemented
--
radio
communications in particular needs work

Enumerations support (Done in Java)

HLA bridge

Support for DIS
-
200x

Dead Reckoning algorithms (Done)

Finite state machine support

Programming help appreciated