The GenericMotion model was originally introduced to describe platform motion, hence it’s associated platform position data (PPD) file (commonly seen with the .ppd file extension). A PPD file contains a series of records that indicate the platform’s position and orientation as a function of time. This file is an XML formatted file which makes it easier and more reliable to parse and allows the data to be authored and viewed in other software packages.

Reference Frame

The primary coordinate system in DIRSIG is the East-North-Up (ENU), where the ENU axes correlate to X, Y and Z, respectively. The ENU reference frame for motion models in DIRSIG is as follows:

  • The "forward" axis is the +Y axis.

  • The "up" axis is the +Z axis.

  • The remaining axis (+X) is the "right" wing (follows the right-hand rule).

predator xyz
Figure 1. Diagram of the reference motion frame in DIRSIG.

How do roll, pitch and yaw relate to this motion frame?

  • The "roll" axis is Y, and a positive angle corresponds to a right wing down or left wing up rotation.

  • The "pitch" axis is X, and a positive angle corresponds to a "nose up" rotation.

  • The "yaw" axis is Z, and a positive angle corresponds to a counter-clockwise rotation as viewed from above.

Important The motion defines the location and orientation of the object it is associated with. For platform motion in sensor plugins it is important to know what the default camera orientation is relative to the vehicle. For example, in the BasicPlatform plugin the default orientation of cameras is looking down the -Z axis.

Format Details

There are two generations of the XML schema that can appear in a PPD file. The older format only supported the Scene ENU coordinate system, while the newer format supports use of the Scene ENU coordinate system as well as absolute geographic coordinates (see the Coordinates Manual for more information). Regardless of the "new" vs. "old" format, the top level elements of the XML hierarchy are the same:

<platformmotion type="generic">
  <method type="raw"></method>
  <data ... >
    <entry>
      ...
      [lines deleted for documentation purposes]
      ...
    </entry>
    ...
    <entry>
      ...
    </entry>
  </data>
</platformmotion>

The "generic" platform model is chosen by supplying the name "generic" in the type attribute. The next element is the <method> is reserved for future expansion when the method and parameters used to generate specific platform positioning and pointing data will be stored here. For now, the type attribute for the method expects to see "raw" which is an free-style method that is used to describe any other means used to create the data (including hand generated data or data imported from other sources).

The differences between the "new" vs. "old" formats are isolated to the <data> section, which describes the platform position and orientation as a function of time. This is achieved through a sequence of <entry> elements

Common Conventions

Although the format of the <entry> elements in the "new" vs. "old" files varies, there are common conventions used in both. In general, each entry provides the data to construct an affine transform describing the location and orientation of the platform as a function of time.

Time

Each <entry> contains a <datetime> element that defines the relative time for this entry. This time is relative to the Reference Date/Time define in the .tasks file employed by the simulation. At this time, only relative times are supported (absolute date/time will be added at a later point).

Important The list of <entry> elements describe the position and orientation of the platform at specific points in time. If DIRSIG needs to know the location and orientation for an intermediate time, the values are linearly interpolated from the adjacent times.

Rotations

This axis rotations are based on a right-handed coordinate system that is oriented such that the +Z axis is up (normal to the earth) and the +Y axis is along the nominal/default direction of the platform. The following figures illustrate the resulting sign conventions when using an aircraft as the reference platform:

x rotation
Figure 2. X axis (right wing of plane) is out of page
y rotation
Figure 3. +Y axis (front of plane) is out of page
z rotation
Figure 4. +Z axis (top of plane) is out of page
Note These axis rotation angles are sometimes referred to as "roll", "pitch" and "yaw". In the DIRSIG platform model, "roll" is about the Y-axis, "pitch" is about the X-axis and "yaw" is about the Z-axis. However, it is not uncommon for the "yaw" angle to be referenced about a "down axis", which would require in a sign flip of the Z-axis angle in DIRSIG. Make sure to understand all axis and angle conventions when importing angles into the DIRSIG platform motion model.

The <data> element has an attribute called rotationorder that is assigned a 3-character string defining the order that the X, Y and Z rotations are applied. For example, the string xyz means that the axis rotations are applied in the order "X, then Y, then Z".

Important The order of rotations is important. The final orientation can be dramatically different if the order that rotations are applied is changed (see the affine transform documentation for an explanation).
Note The most common rotation order for a "roll, pitch and yaw" description is "roll, then pitch, then yaw", which would be a rotation order of yxz for a DIRSIG plaform.

Older Data Format

Below is an example of an older XML position/orientation data file for the "generic" platform motion model. The position and orientation of the platform as a function of time is defined by a sequence of <entry> elements:

<platformmotion type="generic>
  <method type="raw" />
  <data rotationorder="xyz">
    <entry>
      <datetime type="relative">0.000</datetime>
      <xlocation>0</xlocation>
      <ylocation>0</ylocation>
      <zlocation>1000</zlocation>
      <xrotation>0.00000</xrotation>
      <yrotation>0.00000</yrotation>
      <zrotation>0.00000</zrotation>
    </entry>
  </data>
</platformmotion>

The rotationorder attribute in the <data> element defines the order that the X, Y and Z rotations are combined. This string will be some permutation of the string "xyz" indicating Euler angle rotation order. Each axis is expected to appear exactly once in the string. A value of "xyz" means first about X-axis, then the Y-Axis and then the Z-axis.

The xlocation, ylocation and zlocation variables define the XYZ location of the platform in meters in the Scene ENU coordinate system.

The xrotation, yrotation and zrotation variables define the XYZ rotation angles about the respective Scene ENU axis in radians.

Newer Data Format

The newer <data> format added support for geographic coordinate systems. To support this flexibility, a series of new XML attributes were added to the <data> element:

<platformmotion type="generic">
  <method type="raw" />
  <data rotationframe="sceneenu" rotationorder="xyz" angletype="absolute" angularunits="radians" spatialunits="meters">
    <entry>
      <datetime type="relative">0</datetime>
      <position>
        <scenelocation>
          <point><x>0.000</x><y>0.000</y><z>1000.000</z></point>
        </scenelocation>
      </position>
      <orientation>
        <eulerangles>
          <cartesiantriple><x>0.000</x><y>0.000</y><z>0.000</z></cartesiantriple>
        </eulerangles>
      </orientation>
    </entry>
  </data>
</platformmotion>

These <data> element attributes are defined as follows:

rotationframe

The reference frame for orientation vectors, which can be:

  • Scene relative East-North-Up ("sceneenu"),

  • Platform relative East-North-Up ("platformenu"), or

  • Earth-Centered, Earth-Fixed ("ecef")

rotationorder

The order in which orientation Euler rotations are applied. The order "xyz" indicates to first rotate around the X-axis, then the Y-axis, then the Z-axis. Arbitrary combinations of the three axes are allowed, such as "zyx" and "yxz". See the Affine Transform document for a more detailed explanation.

angletype

Currently only the "absolute" is supported, which indicates that orientation Euler rotations are relative to the vectors (0,0,-1) and (0,1,0) in the specified "rotationframe".

angularunits

The units used for rotations. Only "radians" is currently supported.

spatialunits

The units used for local-coordinate positioning. Only "meters" is currently supported.

Each <entry> contains a <position> and an <orientation> element. Depending on the reference coordinate system, reference rotation frame, etc. the entries will contain different data.

Scene ENU Position

Support for Scene-ENU coordinate systems for the position are supported via the <scenelocation> element:

      <position>
        <scenelocation>
          <point><x>600</x><y>600</y><z>1200</z></point>
        </scenelocation>
      </position>

Geodetic Position

Support for geodetic coordinate systems for the position are provided via the <geodeticlocation> element:

      <position>
        <geodeticlocation>
          <latitude>43.120</latitude>
          <longitude>-78.450</longitude>
          <altitude>1500.000</altitude>
        </geodeticlocation>
      </position>

Or via the updated <location> format introduced in DIRSIG 4.5.0:

      <position>
        <location frame="geodetic">
          <latitude>43.120</latitude>
          <longitude>-78.450</longitude>
          <altitude>1500.000</altitude>
        </location>
      </position>

UTM Position

Support for UTM coordinate systems for the position are provided via the <utmlocation> element:

      <position>
        <utmlocation>
          <zone>17</zone>
          <hemisphere>N</hemisphere>
          <easting>707445.963</easting>
          <northing>4777297.178</northing>
          <altitude>1500.000</altitude>
        </utmlocation>
      </position>

Or via the updated <location> format introduced in DIRSIG 4.5.0:

      <position>
        <location frame="utm">
          <zone>17</zone>
          <hemisphere>N</hemisphere>
          <easting>707445.963</easting>
          <northing>4777297.178</northing>
          <altitude>1500.000</altitude>
        </location>
      </position>

ECEF Position

Support for ECEF coordinate systems for the position are provided via the <eceflocation> element:

      <position>
        <eceflocation>
          <point><x>933829.296</x><y>-4569502.813</y><z>4338267.397</z></point>
        </eceflocation>
      </position>

Or via the updated <location> format introduced in DIRSIG 4.5.0:

      <position>
        <location frame="ecef">
          <x>933829.296</x>
          <y>-4569502.813</y>
          <z>4338267.397</z>
        </location>
      </position>

Orientation

The orientation data for a given <entry> is limited to a triplet of Euler rotation angles:

      <orientation>
        <eulerangles>
          <cartesiantriple><x>0</x><y>0</y><z>-5.06145483</z></cartesiantriple>
        </eulerangles>
      </orientation>

The order that these angles are combined is defined by the rotationorder attribute in the <data> element. The reference coordinate system for these angles is defined by the rotationframe attribute.

DIRSIG5 Specific Options

With DIRSIG5 this motion model includes a similar start/end "hidden" option that is available in the DeltaMotion model when used for in-scene geometry. This is enabled with the optional <options> element inside the <motion> element in a GLIST file:

<geometrylist>
  <object>
    <basegeometry>
      <obj><filename>sedan_red_subaru.obj</filename></obj>
    </basegeometry>
    <dynamicinstance>
      <motion type="generic">
        <options starthidden="true" endhidden="true"/>
        <filename>$SCENE_DIR/geometry/sedan_red_subaru.ppd</filename>
      </motion>
    </dynamicinstance>
  </object>
</geometrylist>

The starthidden and endhidden attributes in the <options> element control the respective start and end hidden flags for the instance the motion model is associated with.

Note The default behavior is that the instance does not start or end "hidden". To enable the hidden flags, the <options> element must be introduced.