Important This motion model is operational as of DIRSIG 4.6 release. The interfaces for this motion model are still being developed and can be expected to change before the model is finalized.

Overview

This document describes the Flexible motion model that enhances the capabilities to model moving scene objects and imaging platforms in DIRSIG. The driving design concept is to split the calculations into a separate location calculation (which defines where an object is located) and orientation calculation (which defines how an object is oriented). By doing so, we can implement a suite of simpler calculations or "engines" for each component. The user can then configure different types of scenarios by creating different combinations of these location and orientation engines.

It is expected that future feature enhancements to motion will be accomplished by improving existing or adding new engines to this model. The existing motion engines (Generic Platform, Delta, Spin, etc.) will be maintained to provide backward support even though they could be replaced by some combination of engines within this new model.

Configuration

The Flexible motion model configuration is supplied to DIRSIG through an XML description file (like other DIRSIG components). The recommended extension for these files is .motion.

The XML description for the Flexible motion model is composed of two top level elements that define the location and orientation engine used:

<motion type="flexible">
  <locationengine type=... >
    ...
  </locationengine>
  <orientationengine type=... >
    ...
  </orientationengine>
</motion>
Note The one assumption we are making at this time is that the orientation can be driven by the location, but not the other way around.

Usage for Platform Motion

Because a graphical user interface has not been created (yet), the name of the .motion file must be added to your simulation by hand-editing the .sim and changing the name of the file associated with the platform motion (see the platformmotion element in the example below):

<simulation>
  <scene externalfile="demo.scene"/>
  <atmosphericconditions externalfile="demo.atm"/>
  <platform externalfile="demo.platform"/>
  <platformmotion externalfile="stk.motion"/>
  <tasklist externalfile="stk.tasks"/>
</simulation>

Usage for Instance Motion

The Flexible motion model can also be used to drive the motion of scene objects via the GLIST file:

<dynamicinstance>
  <motion type="flexible">
    ...
  </motion>
</dynamicinstance>

Location Engines

The location engines must be able to compute the following:

  • The location for any given time

  • The linear velocity for any given time

  • Support spatial "jitter" descriptions

Fixed

The Fixed location engine let’s the used supply the location as a fixed location as either Scene ENU, Geodetic Lat/Long, UTM or ECEF coordinates. The object does not move as a function of time, with the exception of motion due to jitter. The configuration is very simple, with the location using the <location> schema defined in the coordinates document.

The example below defines an object statically located at 0,0,12500 in the Scene ENU coordinate system:

  <locationengine type="fixed">
    <location frame="scene">
      <x>0.0</x><y>0.0</y><z>12500.0</z>
    </location>
  </locationengine>

Waypoints

The Waypoints location engine lets the user supply a set of waypoints that the object appears at as a function of time.

Internal ASCII/Text Data

The waypoints vs. time data can be stored within the motion file within an XML CDATA block:

  <locationengine type="waypoints">
    <data source="internal" datetime="relative" frame="scene" delimiter="," loop="false">
      <![CDATA[
        0.0,0.0,-1.0,1000.0
        1.0,0.0,+1.0,1000.0
      ]]>
    </data>
  </locationengine>

The following attributes in the <data> element must be provided:

  • The source must be set to internal.

  • The datetime must be set to use the relative format (for now).

  • The frame must be set either:

    • To scene when supplying Scene ENU coordinates

    • To geodetic to supply Geodetic coordinates.

    • To utm to supply UTM coordinates.

    • To ecef to supply ECEF coordinates.

  • The delimiter should be set to whatever single character separates the fields.

The following describes the fields by field number for the various coordinate types:

  • Scene ENU (time plus 3 location fields):

    1. Time

    2. Scene ENU X (meters)

    3. Scene ENU Y (meters)

    4. Scene ENU Z (meters)

  • Geodetic (time plus 3 location fields):

    1. Time

    2. Latitude (degrees, +North)

    3. Longitude (degrees, +East)

    4. Altitude (meters above the WGS-84 ellipsoid)

  • UTM (time plus 5 location fields):

    1. Time

    2. Zone

    3. Hemisphere

    4. Easting

    5. Northing

    6. Altitude (meters above the WGS-84 ellipsoid)

  • ECEF (time plus 3 location fields):

    1. Time

    2. ECEF X (meters)

    3. ECEF Y (meters)

    4. ECEF Z (meters)

Note A single entry results in an object that stays at a fixed location.

External ASCII/Text Data File

The waypoints vs. time data also can be stored within an simple ASCII/Text file, that is external to the motion file:

  <locationengine type="waypoints">
    <data source="external" datetime="relative" frame="scene" delimiter=",">
      <filename>waypoints.txt</filename>
    </data>
  </locationengine>

The same attributes must be supplied to the <data> element as described with the internal data option (above), except that the source attribute is set to external. The example file below is the same data used in the internal example:

0.0,0.0,-1.0,1000.0
1.0,0.0,+1.0,1000.0

STK Ephemeris Report Waypoints

The Waypoints location engine also lets the user directly import an ASCII/Text ephemeris report produced by STK.

  <locationengine type="waypoints">
    <data source="stk_report">
      <filename>WORLDVIEW-2_35946.e</filename>
    </data>
  </locationengine>

Please note the following about the current STK ephemeris (.e) file import mechanism in DIRSIG:

  • The ScenarioEpoch is ignored and the relative times in each record are assumed to be relative to the simulation reference time.

  • The data is linearly interpolated in DIRSIG, therefore the InterpolationMethod and InterpolationSamplesM1 values are ignored.

  • Only the Earth option is supported for the CentralBody.

  • Only the Fixed option is supported for the CoordinateSystem.

  • Only EphemerisTimePos and EphemerisTimePosVel format data records are supported:

    • If the supplied data is in the EphemerisTimePosVel format, the velocity is currently ignore (to be resolved at a later time).

Important Since DIRSIG only supports linear interpolation, the user should output the report from STK at high temporal resolution to avoid interpolation effects.

Extrapolation vs. Looping

The location for all times before the first time will be defined by the first time (flat extrapolation). Likewise, the location for all times after the last time will be defined by the last time (flat extrapolation). However, if the loop option is set to true then times outside the those defined by the supplied data will be determined by assuming the object continuously loops through the data (first → last, reset to first, first→last, etc.).

Straight

The Straight location engine defines a platform flying at a "straight line" (constant altitude, at a constant speed and in a constant direction). The user configures this engine using the following variables.

  • The <start> is a location (Scene ENU, Geodetic Lat/Long, UTM and ECEF coordinates are supported) at the start of simulation.

  • The <heading> is the direction heading in degrees East of North (+CW)

  • The <velocity> is the linear velocity in meters/second.

The example below shows an object starting at 0,0,12500 in Scene ENU coordinate system, heading at 20 degrees East of North (+CW) and traveling at 200 meters/second:

  <locationengine type="straight">
    <start frame="scene">
      <x>0.0</x><y>0.0</y><z>12500.0</z>
    </start>
    <heading>20</heading>
    <velocity>200</velocity>
  </locationengine>

Circling

The Circling engine supports a platform that circles about a supplied center location (Scene ENU, Geodetic Lat/Long, UTM and ECEF coordinates are supported) at a supplied radius (meters) and linear velocity (meters/second).

The example below is for an object circling around 0,0,12500 in the Scene ENU coordinate system, with a radius of 1000 meters at 500 meters/second:

  <locationengine type="circling">
    <center frame="scene">
      <x>0.0</x><y>0.0</y><z>12500.0</z>
    </center>
    <radius>1000</radius>
    <velocity>500</velocity>
  </locationengine>

SGP4

The SGP4 location engine provides access to a "simplified general perturbations" (SGP) model implementation, which performs a direct location calculation for an earth orbiting object from a Two-Line Element (TLE) set. Specifically, DIRSIG utilizes the SGP4 implementation written by David Vallado (the version referred to by Vallado as "SGP4 Version 2008-11-03"), which is available on the Celestak website.

  <locationengine type="sgp4">
    <data source="internal">
      <tle1>1 35946U 09055A   12142.38764183  .00000143  00000-0  62140-4 0  9047</tle1>
      <tle2>2 35946  98.4816 222.1443 0001101 149.9222 210.2033 14.37681035137285</tle2>
    </data>
  </locationengine>
Important The format of a TLE is very rigid, and very little validation of the TLE is performed at this time. Do not delete spaces, etc. which will result in parsing the various fields incorrectly.

Currently, the user must supply the TLE within the engine description. However, at a future date it is expected that extracting the TLE from a local file or remote (HTTP accessible) file will be added.

Orientation Engines

This component must be able to supply the following:

  • The orientation for any given time

  • The angular velocity for any given time

  • Support angular "jitter" descriptions

Euler Angles

The Euler Angles orientation engine lets the user specify the orientation using an Euler angle rotation sequence.

Internal ASCII/Text Angles

The angles vs. time data can be stored within the motion file within an XML CDATA block:

  <orientationengine type="euler">
    <data source="internal" datetime="relative" frame="scene" order="xyz" delimiter=" " loop="false">
      <![CDATA[
        0.00005 0.40145895 -0.03368054 1.80764509
        0.00010 0.40146901 -0.03362345 1.80757425
        0.00015 0.40146524 -0.03354615 1.80745341
        0.00020 0.40145981 -0.03352115 1.80746565
        0.00025 0.40145300 -0.03350534 1.80750217
      ]]>
    </data>
  </orientationengine>

The first field is the time, followed by the 3 axes rotation fields. These fields are the X, Y then Z rotation angles in radians.

Note A single entry results in an object that stays in a fixed orientation.

External ASCII/Text Angles File

The angles vs. time data also can be stored within an simple ASCII/Text file, that is external to the motion file:

  <orientationengine type="euler">
    <data source="external" datetime="relative" frame="scene" order="xyz" delimiter=" " loop="false">
      <filename>angles.txt</filename>
    </data>
  </orientationengine>

The same attributes must be supplied to the <data> element as described with the internal data option (above), except that the source attribute is set to external. The example file below is the same data used in the internal example:

0.00005 0.40145895 -0.03368054 1.80764509
0.00010 0.40146901 -0.03362345 1.80757425
0.00015 0.40146524 -0.03354615 1.80745341
0.00020 0.40145981 -0.03352115 1.80746565
0.00025 0.40145300 -0.03350534 1.80750217

The first field is the time, followed by the 3 axes rotation fields. These fields are the X, Y then Z rotation angles in radians.

Note A single entry results in an object that stays in a fixed orientation.

Extrapolation vs. Looping

The orientation for all times before the first time will be defined by the first time (flat extrapolation). Likewise, the orientation for all times after the last time will be defined by the last time (flat extrapolation). However, if the loop option is set to true then times outside the those defined by the supplied data will be determined by assuming the object continuously loops through the data (first → last, reset to first, first→last, etc.).

Quaternions

The Quaternion orientation engine allows the user to define the orientation using quaternions, which have the following form:

Q = W + X i + Y j + Z k

Internal ASCII/Text Quaternions

The quaternions vs. time data can be stored within the motion file within an XML CDATA block:

  <orientationengine type="quaternions">
    <data source="internal" datetime="relative" frame="scene" delimiter=" ">
      <![CDATA[
        0.0e+000 1.133500e-001 -6.376511e-001 6.956687e-001 3.723428e-001
        1.0e-002 1.133838e-001 -6.376308e-001 6.956620e-001 3.723779e-001
        2.0e-002 1.134176e-001 -6.376105e-001 6.956552e-001 3.724130e-001
        3.0e-002 1.134514e-001 -6.375902e-001 6.956485e-001 3.724480e-001
        4.0e-002 1.134851e-001 -6.375699e-001 6.956417e-001 3.724831e-001
      ]]>
    </data>
  </orientationengine>

The first field is the time, followed by the 4 fields for the quaternion. These fields are W, X, Y then Z, where W is the scalar component and XYZ is the vector component of the quaternion.

Important Some programs will list the quaternion fields in the order X, Y, Z, then W (vector followed by scalar), which does not match the order expected here.
Note A single entry results in an object that stays in a fixed orientation.

External ASCII/Text Quaternions File

The quaternions vs. time data also can be stored within an simple ASCII/Text file, that is external to the motion file:

  <orientationengine type="quaternions">
    <data source="external" datetime="relative" frame="scene" delimiter=" ">
      <filename>angles.txt</filename>
    </data>
  </orientationengine>

The same attributes must be supplied to the <data> element as described with the internal data option (above), except that the source attribute is set to external. The example file below is the same data used in the internal example:

0.0e+000 1.133500e-001 -6.376511e-001 6.956687e-001 3.723428e-001
1.0e-002 1.133838e-001 -6.376308e-001 6.956620e-001 3.723779e-001
2.0e-002 1.134176e-001 -6.376105e-001 6.956552e-001 3.724130e-001
3.0e-002 1.134514e-001 -6.375902e-001 6.956485e-001 3.724480e-001
4.0e-002 1.134851e-001 -6.375699e-001 6.956417e-001 3.724831e-001

The first field is the time, followed by the 4 fields for the quaternion. These fields are W, X, Y then Z, where W is the scalar component and XYZ is the vector component of the quaternion.

Important Some programs will list the quaternion fields in the order X, Y, Z, then W (vector followed by scalar), which does not match the order expected here.
Note A single entry results in an object that stays in a fixed orientation.

STK Attitude Report Quaternions

The Quaternions engine lets the user directly import an ASCII/Text attitude report produced by STK.

  <orientationengine type="quaternions">
    <data source="stk_report">
      <filename>WORLDVIEW-2_35946.a</filename>
    </data>
  </orientationengine>

Please note the following about the current STK attitude (.a) file import mechanism in DIRSIG:

  • The ScenarioEpoch is ignored and the relative times in each record are assumed to be relative to the simulation reference time.

  • The data is linearly interpolated in DIRSIG, therefore the BlockingFactor and InterpolationOrder values are ignored.

  • Only the Earth option is supported for the CentralBody.

  • Only the Fixed option is supported for the CoordinateSystem.

  • Only AttitudeTimeQuaternions format data records are supported.

Important Since DIRSIG only supports linear interpolation, the user should output the report from STK at high temporal resolution to avoid interpolation effects.

The STK attitude (.a) file import mechanism in DIRSIG automatically accounts for the difference in the vehicle body coordinate convention differences between DIRSIG and STK.

Important The AttitudeTimeQuaternions format orders the quaternion values X, Y, Z, W and not W, X, Y, Z as one might expect. The DIRSIG report parser knows this, but it is a subtle and important piece of knowledge if you use or create your own STK report files.

Velocity

The Velocity orientation engine allows the orientation to be driven by the current velocity supplied from the location engine. This engine is useful for when an object is always oriented to point along the current velocity direction (for example, a vehicle generally points in the direction it is headed). This engine assumes the object that it is associated with is oriented in its local coordinate system such that the "front" is along the +Y axis.

Important The velocity provided by the location engine must be non-zero for the velocity vector to define the orientation. If the velocity at any time is 0, this engine will issue an error.

However, the current velocity vector is not enough to fully constrain the orientation because the coordinate system can rotate about the velocity heading. Therefore, a second vector is needed to constrain the orientation. This vector is usually referred to as the "up" vector because it is used to define the "up" (+Z) direction of the local coordinate system.

Important If this "up" vector is parallel to the velocity, then the orientation is still undefined. For example, if a rocket is headed straight up (the velocity is parallel to Scene ENU +Z) then using Scene ENU +Z as "up" does not constrain the orientation.

If the user wishes to override the "up" vector, they can do so via the optional <up> element. This element has two attributes:

frame

This attribute defines the reference frame to the supplied direction. It can be assigned either scene (for Scene ENU) or ecef (for ECEF).

vector

This attribute defines the vector in the reference frame. It must be assigned a comma-separated triplet that represents the vectr components. The components do not need to produce a unit length vector.

The following XML configuration shows the setup of this engine with the Scene ENU +Z axis explicitly defined as the "up" vector:

  <orientationengine type="velocity">
    <up frame="scene" vector="0,0,1"/>
  </orientationengine>

The default "up" vector for the Velocity engine is the Scene ENU +Z vector.

Look At

The Look At orientation engine provides a great deal of flexibility because it lets the user specify the orientation by forcing the object to "look at" another location from whatever it’s current location is. This makes it easy to configuration scenarios combining static (stationary) and dynamic (moving) pointing and tracking scenarios. For example:

  • Stationary and staring at a stationary target.

  • Stationary and tracking a moving target.

  • Moving and staring at a stationary target.

  • Moving and tracking a moving target.

The Look At engine requires the user to specify the location to "look at" by configuring a location engine.

  <orientationengine type="lookat">
    <locationengine type=... >
      ...
    </locationengine>
  </orientationengine>

Any of the previously described location engines can be used to define the location to "look at". That location engine can be static (stationary) or dynamic (moving) with time.

Note In the future, we expect to add the option to "look at" named instances within the scene and special objects like the Sun and Moon.

This engine works by computing a line-of-sight (LOS) vector between the current location and the location being "looked at". Like the Velocity engine, this one vector is not enough to fully constrain the orientation because the coordinate system can rotate about that LOS vector. Therefore a second "up" vector is required to constrain the orientation. The only requirement for this second vector is that it is not parallel to the LOS vector.

If the user wishes to override the "up" vector, they can do so via the optional <up> element. This element has two attributes:

frame

This attribute defines the reference frame to the supplied direction. It can be assigned either scene (for Scene ENU) or ecef (for ECEF).

vector

This attribute defines the vector in the reference frame. It must be assigned a comma-separated triplet that represents the vectr components. The components do not need to produce a unit length vector.

The following XML configuration shows the setup of this engine with the Scene ECEF +Z axis explicitly defined as the "up" vector:

  <orientationengine type="velocity">
    <up frame="ecef" vector="0,0,1"/>
  </orientationengine>

The default "up" vector for the Look At engine is the ENU +Z vector.

Example Use Cases

The point of this section is to outline how a variety of complex scenarios can be created by mixing and matching combinations of location and orientation engines.

Fixed Platform

The scenario is a platform fixed at some location in space, staring at another location in space. This probably the most common DIRSIG use case.

  • The Fixed location engine

  • The Euler orientation engine

<motion type="flexible">
  <locationengine type="fixed">
    <location frame="scene">
      <x>0.0</x><y>0.0</y><z>12500.0</z>
    </location>
  </locationengine>
  <orientationengine type="euler">
    <data source="internal" datetime="relative" frame="scene" order="xyz" delimiter=" ">
      <![CDATA[
        0 0 0 0
      ]]>
    </data>
  </orientationengine>
</motion>

Straight Flight Path

The scenario is a simple flight line at some altitude, speed and heading. This can be accomplished with the following engine pairing:

  • The Straight location engine

  • The Velocity orientation engine

<motion type="flexible">
  <locationengine type="straight">
    <heading>20</heading>
    <velocity>200</velocity>
    <start frame="scene">
      <x>0.0</x><y>0.0</y><z>12500.0</z>
    </start>
  </locationengine>
  <orientationengine type="velocity">
  </orientationengine>
</motion>

Straight Flight Path with a Stare Point

In this scenario the platform flies a straight line while staring at a fixed point. This can be accomplished with the following engine pairing:

  • The Straight location engine defines the straight flight line.

  • The Look At orientation engine using a Fixed location defines the point to stare at.

<motion type="flexible">
  <locationengine type="straight">
    <heading>10</heading>
    <velocity>200</velocity>
    <start frame="scene">
      <x>100.0</x><y>0.0</y><z>12500.0</z>
    </start>
  </locationengine>
  <orientationengine type="lookat">
    <locationengine type="fixed">
      <location frame="scene">
        <x>0.0</x><y>0.0</y><z>0.0</z>
      </location>
    </locationengine>
  </orientationengine>
</motion>

Circling Flight Path with a Stare Point

The scenario is that the object flies in circle around a center point, with the orientation such that it stares at the center point. This can be accomplished with the following engine pairing:

  • The Circling location engine

  • The Look At orientation engine using a Fixed location defines the point to stare at.

<motion type="flexible">
  <locationengine type="circling">
    <center frame="scene">
      <x>0.0</x><y>0.0</y><z>12500.0</z>
    </center>
    <radius>1000</radius>
    <velocity>500</velocity>
  </locationengine>
  <orientationengine type="lookat">
    <locationengine type="fixed">
      <location frame="scene">
        <x>0.0</x><y>0.0</y><z>0.0</z>
      </location>
    </locationengine>
  </orientationengine>
</motion>

STK Import

The addition of STK I/O handlers to the appropriate engines streamlines the process of importing these STK scenarios into DIRSIG and eliminates the need to perform external conversions from the STK reports to something like the DIRSIG PPD file format. This can be accomplished with the following engine pairing:

  • The Waypoints location engine using an STK "ephemeris" file

  • The Quaternions orientation engine using an STK "attitude" file

<motion type="flexible">
  <locationengine type="waypoints">
    <data source="stk_report">
      <filename>WORLDVIEW-2_35946.e</filename>
    </data>
  </locationengine>
  <orientationengine type="quaternions">
    <data source="stk_report">
      <filename>WORLDVIEW-2_35946.a</filename>
    </data>
  </orientationengine>
</motion>

Landsat Orbit

Landsat is in a fixed orbit and the orientation is such that the platform is always pointed down towards the center of the earth. This can be accomplished using the following engine combination:

  • The SGP4 location engine (with the Landsat-7 Two-Line Element (TLE))

  • The Look At orientation engine using a Fixed location setup to point at the ECEF origin.

<motion type="flexible">
  <locationengine type="sgp4">
    <data source="internal">
      <tle1>1 25682U 99020A   14090.14765210  .00000891  00000-0  20793-3 0  1054</tle1>
      <tle2>2 25682  98.2230 160.7720 0000916  60.4131 299.7179 14.57105940795622</tle2>
    </data>
  </locationengine>
  <orientationengine type="lookat">
    <locationengine type="fixed">
      <location frame="ecef">
        <x>0.0</x><y>0.0</y><z>0.0</z>
      </location>
    </locationengine>
  </orientationengine>
</motion>

Ground Platform Tracking an Orbiting Object

In this scenario, we have a ground based imaging platform that is tracking an orbiting object. The location of the ground platform is known and the TLE for the orbiting object is used to tell the platform where to point.

  • The Fixed location engine defining the location of the ground station.

  • The Look At orientation engine using the SGP4 location engine configured with the TLE for the orbiting object to be tracked.

<motion type="flexible">
  <locationengine type="fixed">
    <location type="geodetic">
      <latitude>43.120</latitude>
      <longitude>-78.450</longitude>
      <altitude>80.000</altitude>
    </location>
  </locationengine>
  <orientationengine type="lookat">
    <locationengine type="sgp4">
      <data source="internal">
        <tle1>1 25682U 99020A   14090.14765210  .00000891  00000-0  20793-3 0  1054</tle1>
        <tle2>2 25682  98.2230 160.7720 0000916  60.4131 299.7179 14.57105940795622</tle2>
      </data>
    </locationengine>
  </orientationengine>
</motion>

Orbiting Platform Tracking an Orbiting Object

In this scenario, we have an orbiting imaging platform that is tracking another orbiting object. The location of the imaging platform is defined by the TLE for that objects orbit. A second TLE (for the orbiting object) is used to tell the imaging platform where to point.

  • The SGP4 location engine is used to define the location of the imaging platform.

  • The Look At orientation engine using the SGP4 location engine configured with the second TLE for the orbiting object to be tracked.

In the following example, we are using the TLE for the Anik-F1 communications satellite (in a geo-synchronous orbit) to track the Landsat-7 satellite in a low-earth orbit (LEO).

<motion type="flexible">
  <locationengine type="sgp4">
    <data source="internal">
      <tle1>1 26624U 00076A   14089.47582350 -.00000103  00000-0  00000+0 0  2761</tle1>
      <tle2>2 26624   0.0132 149.1043 0002095 256.2280 206.4314  1.00272123 48999</tle2>
    </data>
  </locationengine>
  <orientationengine type="lookat">
    <locationengine type="sgp4">
      <data source="internal">
        <tle1>1 25682U 99020A   14090.14765210  .00000891  00000-0  20793-3 0  1054</tle1>
        <tle2>2 25682  98.2230 160.7720 0000916  60.4131 299.7179 14.57105940795622</tle2>
      </data>
    </locationengine>
    <up frame="ecef" vector="0,0,1"/>
  </orientationengine>
</motion>