Copyright © 1995 Loral Advanced Distributed Simulation, Inc.

Overview
********

Libtracked implements an instance of the hull class of components.  It provides a low-fidelity model of tracked vehicle dynamics.  Capabilities are modeled only to the second order (maximum velocity, maximum acceleration), and they depend upon the soil type.  Unlike previous models, the parameters for each soil type are specified in a data file, so the software does not need to be modified to accommodate new types of terrain.

The parameters of a tracked vehicle are specified in its configuration file as follows:

     (tracked (soils (<integer soil type> (max_speeds <float forward KPH>
                                                      <float reverse KPH>)
                                          (max_accel <float mps2>)
                                          (max_decel <float mps2>)
                                          (max_turn  <float dps>)
                                          (max_climb <float degrees>)
                                          (dust_speeds <float smallKPH>
                                                       <float mediumKPH>
                                                       <float largeKPH>)
                                          (plow_speeds
                                                (<plow_type1> Ss Sd Ps Pd)
                                                (<plow_type2> Ss Sd Ps Pd)
                                                ...
                                                (<plow_typeN> Ss Sd Ps Pd)))
                     (<integer soil type> (max_speeds <float KPH>
                                                      <float reverse KPH>)
                                          (max_accel <float mps2>)
                                          (max_decel <float mps2>)
                                          (max_turn  <float dps>)
                                          (max_climb <float degrees>)
                                          (dust_speeds <float smallKPH>
                                                       <float mediumKPH>
                                                       <float largeKPH>)
                                           (plow_speeds
                                                (<plow_type1> Ss Sd Ps Pd)
                                                (<plow_type2> Ss Sd Ps Pd)
                                                ...
                                                (<plow_typeN> Ss Sd Ps Pd)))
                      ...)
              (fuel_usage (<float speed1> <float speed2> ...)
     	             (<float rate1>  <float rate2> ...))
      )

The parameters specified for soil type 0 (or the first soil type, if no 0 type is provided) are used as a default when on a soil type not in the list.

To indicate that the vehicle should not kick up any dust on a kind of soil, specify a speed which is higher than the maximum the vehicle can travel across that soil.

The fuel_usage table consists of a list of speeds in kilometers per hour, with a list of corresponding consumption rates in liters per hour. If an older vehicle parameter file is used, with a scalar fuel_usage figure, it will ignore it and use the internal default corresponding to 8 kilometers per liter.  The minimum table size is one speed/rate pair.

The plow speeds are used to control the maximum speed for the vehicle when it has certain plows attached to it.  The <plow_type> fields are character strings that represent the name of the plow (FWMP, TWMP, moldboard, etc.).  If this vehicle can have such a plow attached (it has the plow component), then each soil type specified in the Tracked params should have an associated plow_speeds array.  Each plow that the vehicle can have attached must have an entry in each soil type.

The format of the plow data is (plow_name Ss Sd) such that the name is a character string (FWMP, TWMP, etc); Ss is the speed at which this vehicle can travel in this soil type with the plow attached but in its stowed position; Sd is the speed at which it can travel ... in its deployed position;

Be careful about setting the speeds for the plows in relation to the "max_speeds" entry.  The algorithm used it to set the current speed equal to the max speed and then check to see if that speed to greater than the speeds allowed if there is a plow attached (either stowed or deployed).  Therefore, the max_speed should be greater than or equal to at least one of the speeds Ss or Sd.  Otherwise, the plow speed data will essentially be ignored.

Applications interface to the tracked model primarily through the libhulls interface.  The most efficient interface for controlling vehicle motion is HULLS_SET_DIRECTION_SPEED.  All interfaces use only two dimensions of the provided parameters.  Also, when a direction vector is given it is not necessary to make that vector a unit vector.  Libtracked will do the normalization only if it is necessary (for example, if the vehicle is already pointing the right way, no normalization is needed).

Libtracked supports only one instantiation per vehicle (i.e., a vehicle may not have more than one tracked hull).

The libhulls library defines a common set of functions (and the semantics of those functions) which are invoked on instances of the hulls class (such as those instantiated by libtracked or libfwa). It is possible to modify the tracked model by changing an exisiting hulls interface function or by adding a completely new function.

To modify an existing libtracked interface function would require the following actions:

 1. If the change occurs only in the function body, only change the function code in the libtracked library.  If the change occurs to the function's argument list, change the function code in both the libtracked library and the hulls interface structure definition found in libhulls.h.  Also to maintain the common hulls interface, change the code for the modified function in any other hull specific component libraries (such as libfwa or libmissile).

 2. Recompile ModSAF.

To add an additional libtracked function to the current model would require the following actions:

 1. Write the function as part of the libtracked library.  The function is written in the code which manages the libtracked class information attached to each vehicle (trk_class.c).

 2. Add the function and its declaration to any of the other hull specific component libraries.  This maintains the common hulls interface.

 3. In the libtracked source code that handles libhull initialization processing, include a function_number, function entry identifying the new function for the cmpnt_define_instance function and every other hull instance library (libfwa, libmissile, etc.).

 4. In libhulls.h, add an entry to identify the new macro and associate it with a function code number.  This new addition means that the number of hulls functions must be incremented by one.  The hulls interface structure definition that appears in libhulls.h must include a structure to define the new function's argument list.

 5. Recompile ModSAF.

To replace this tracked model with a completely different one would require the following actions:

 1. Decide on the get functions and set functions that would be required in the new model.  Try to map these needed functions to the existing hulls interface.  A function can map if its argument list can remain the same.  Functions that can not map must be added to the hulls interface.

 2. For those functions that can map to the existing hulls interface but whose code body you want to change, edit the code for the function in the libtracked source file that contains the code to manage the libtracked class information (trk_class.c).

 3. For those functions that can't map to the existing hulls interface, add an additional function to the hulls interface.  The addition procedure was described above.

 4. Recompile ModSAF.

Examples
********

To get the component number of my hull:

     extern int32 my_hull;

     if ((my_hull = cmpnt_locate(vehicle_id, reader_get_symbol("hull"))) ==
         CMPNT_NOT_FOUND)
       printf("Vehicle %d does not seem to have a hull\n", vehicle_id);

To then give a command to that hull:

     if (my_hull != CMPNT_NOT_FOUND)
       HULLS_SET_DIRECTION_SPEED(vehicle_id, hull, dirvec, speed, 0.0, 0.0);

Functions
*********

The following sections describe each function provided by libtracked, including the format and meaning of its arguments, and the meaning of its return values (if any).

tracked_init
============

     void tracked_init(cant, data_path, constant_env, mobility_sw)
         int32 cant;
         char *data_path;
         int32 constant_env;
         int32 mobility_sw;

cant
     Specifies whether to cant the vehicle when it is m-killed.

data_path
     Specified where the data files are located.

constant_env
     Specifies whether constant environmental models are in use (suppresses wave interaction for amphibious vehicles).

mobility_sw
     Enable CCTT soil types

tracked_init initializes libtracked.  Call this before calling any other libtracked functions.

tracked_statsOn
===============

     void tracked_statsOn()

tracked_statsOn turns on statistics collection for tracked hulls

tracked_statsOff
================

     void tracked_statsOff()

This function turns off statictics collection for tracked hulls

tracked_statsReset
==================

     void tracked_statsReset()

This function zeros out the statistics collected for tracked hulls

tracked_statsPrint
==================

     void tracked_statsPrint()

This functions prints out the statistics for tracked hulls. Uses hulls_statsPrint.

tracked_statsStatus
===================

     void tracked_statsStatus()

This function prints whether tracked hulls data collection is on or off

tracked_statsQuit
=================

     void tracked_statsQuit()

This function deallocates memory for collecting tracked statistics