:orphan: .. **************************************************************************** .. CUI .. .. The Advanced Framework for Simulation, Integration, and Modeling (AFSIM) .. .. The use, dissemination or disclosure of data in this file is subject to .. limitation or restriction. See accompanying README and LICENSE for details. .. **************************************************************************** platform -------- .. contents:: :local: **Script Class:** :class:`WsfPlatform` .. command:: platform ... end_platform .. parsed-literal:: platform_ ** ** acoustic_signature_ ... altitude_ ... aux_data_ ... category_ ... clear_categories_ commander_ ... command_chain_ ... concealment_factor_ ... creation_time_ ... empty_mass_ ... fuel_ ... end_fuel fuel_mass_ ... geo_point_ ... group_join_ ... group_leave_ ... heading_ ... height_ ... icon_ ... indestructible_ ... infrared_signature_ ... inherent_contrast_ ... initial_damage_factor_ ... length_ ... marking_ ... mgrs_coordinate_ ... add_mover_ ... end_mover mover_ ... end_mover navigation_errors_ ... end_navigation_errors nutation_update_interval_ ... on_broken_ ... optical_reflectivity_ ... optical_signature_ ... payload_mass_ ... position_ ... precession_nutation_update_interval_ ... radar_signature_ ... route_ ... end_route side_ ... spatial_domain_ ... :ref:`\` ... end_ add_ ... end_ edit_ ... end_ delete_ ... track_ ... end_track track_manager_ ... end_track_manager use_zone_ ... width_ ... zone_ ... end_zone zone_set_ ... end_zone_set # `Script Interface`_ :command:`on_initialize` ... end_on_initialize :command:`on_initialize2` ... end_on_initialize2 :command:`on_update` ... end_on_update :command:`_.script_commands.script_variables` ... end_script_variables :command:`_.script_commands.script` ... end_script ... Other Script_Commands ... script void on_damage_received_\ () ... end_script script void on_platform_deleted_\ () ... end_script script void on_commander_deleted_\ (:class:`WsfPlatform` aCommander) ... end_script script void on_peer_deleted_\ (:class:`WsfPlatform` aPeer) ... end_script script void on_subordinate_deleted_\ (:class:`WsfPlatform` aSubordinate) ... end_script :command:`platform.callback` ... end_callback end_platform Overview ======== The **platform_type** command is used to create a platform type object that can be used as the source for the platform command. The **platform** command creates an object instance in the simulation and usually uses a previously defined platform_type as its base. Both platform_type and platform use many of the same subcommands. However, it is recommended to use only subcommands that apply to static definitions when using the **platform_type** command. In addition, creating a detailed platform without using a predefined platform base does not allow for easy reuse of the object in the simulation. Creating a New Instance ^^^^^^^^^^^^^^^^^^^^^^^ .. command:: platform ... end_platform .. parsed-literal:: platform ** ** ... *platform commands* ... end_platform Defines a platform instance in the simulation or can be used to edit a platform instance. The ** specifies the name and must be a unique name in the simulation. Convention is to make ** lowercase. The ** can either be a previously defined **platform_type** or **WSF_PLATFORM**. **WSF_PLATFORM** is the only predefined platform type in WSF. A unique platform name can be generated by specifying **** (with the brackets) as the **. The generated name will be *:*. Creating a New Type ^^^^^^^^^^^^^^^^^^^ .. block:: platform .. command:: platform_type ... end_platform_type .. parsed-literal:: platform_type ** ** ... *platform commands* ... end_platform_type Defines a platform type that can be referenced by the platform command. The ** must be unique to the simulation. Convention is to make ** uppercase. The ** can either be a previously defined platform type or be **WSF_PLATFORM**. **WSF_PLATFORM** is the only ** predefined platform type in WSF. Editing an Instance ^^^^^^^^^^^^^^^^^^^ :: edit platform ... end_platform edit platform ... platform commands ... end_platform This command is useful if a platform is defined in a common scenario file, but one wants to override a setting without modifying the common scenario file. For instance, if one wants to change the route of a platform that was defined in a common scenario file... This might be part of the common scenario file 'common_scenario.txt':: platform airliner-1 AIRLINER route ... the baseline route ... end_route end_platform This is how one would override the route for *airliner-1*:: include common_scenario.txt edit platform airliner-1 route ... a different route ... end_route end_platform Commands ======== .. block:: platform .. command:: side Specify the 'side' ('team' or 'affiliation') to which platforms of this type belong. The side subcommand refers to blue, red, country or team name. Refer to the specific visualization application or tool to see what sides are supported. **Default** None. .. command:: icon Specify the name of the icon to be used when platforms of this type are displayed and if the platform type does not have an associated :command:`dis_interface.entity_type` subcommand in the :command:`dis_interface` block. **Default** The value of or . .. command:: marking Specifies a *marking* to be applied to the platform. This text field is associated with this platform in the :command:`dis_interface`. **Default** No marking. .. command:: indestructible (or destructible) Indicates that the platform type is indestructible. Each hit will update the cumulative probability of survival according to the formula: Ps(new) = Ps(old) * (1 - Pk) **Default** destructible .. command:: on_broken [ remove | disable | disabled_but_movable ] Indicates what should be done when the platform is broken. If **remove** is specified, the platform will be removed from the simulation when it is broken. If **disable** is specified, the platform will remain in the simulation when it is broken. The motion of the platform will be halted and all of the subsystems will be set to 'nonoperational' so they cannot be turned back on. The script method :method:`WsfPlatform.DamageFactor` will return a value of 1.0. If **disabled_but_movable** is specified, the platform will remain in the simulation when it is broken. The motion of the platform will continue. Some movers may allow motion to be affected by the broken condition, such as slowing down and losing control. All of the subsystems will be set to 'nonoperational' so they cannot be turned back on. The script method :method:`WsfPlatform.DamageFactor` will return a value of 1.0. **Default** **remove** .. note:: The on_damage_received_ script will be called whenever damage is received, even if the platform is broken. The script may be used to change the signature state, appearance, etc. It should be remembered however, that all subsystems will be disabled, so the platform will probably not be able to perform any meaningful action after it is has been broken. .. command:: spatial_domain [ land | air | subsurface | surface | space] Indicates the primary spatial domain in which the platform operates. This is sometimes used to classify if an object is a 'land' object, 'space' object, etc. **Default** If the platform has a mover then the default will be inferred from the type of the mover (e.g., for :model:`WSF_AIR_MOVER` it will be 'air'). If the platform does not have a mover then a default of 'land' will be assumed. land, air, surface, subsurface, space .. command:: acoustic_signature Specifies the acoustic signature definition for this platform type. The signature type must have been defined with :command:`acoustic_signature`. **Default** None. .. command:: infrared_signature Specifies the infrared signature definition for this platform type. The signature type must be previously defined with :command:`infrared_signature`. **Default** None. .. note:: If **infrared_signature** is not specified and a sensing event occurs that requires it, a default of 1000 w/sr will be assumed. .. command:: inherent_contrast **Default** None. .. command:: optical_reflectivity Specifies the optical reflectivity definition for this platform type. The signature type must have been defined with :command:`optical_reflectivity`. **Default** None. .. note:: If **optical_reflectivity** is not specified and a sensing event occurs that requires it, a default of 1.0 will be assumed. .. command:: optical_signature Specifies the optical signature definition for this platform type. The signature type must have been defined with :command:`optical_signature`. **Default** None. .. note:: If **optical_signature** is not specified, but length_, width_ and height_ are specified, those values will be used to compute the optical cross section when needed. .. note:: If **optical_signature** is not specified and **length**, **width** and **height** are not specified, a default of 1000 m^ will be assumed. .. command:: radar_signature Specifies the radar signature definition for this platform type. The signature type must have been defined with :command:`radar_signature`. **Default** None. .. note:: If **radar_signature** is not specified and a sensing event occurs that requires it, a default of 1000 m^2 will be assumed. .. command:: geo_point Defines a named location with a latitude, longitude, altitude tuple. The location can be accessed using the :method:`WsfPlatform.GeoPoint` script method. .. command:: position Specifies the latitude and longitude of the platform. This command is only for static platforms without movers. **Default** 0n 0e .. command:: nutation_update_interval Specifies the time interval between updates to nutation calculations that are used in WCS-ECI coordinate conversions. **Default** 1000 s .. command:: precession_nutation_update_interval Specifies the time interval between updates to nutation calculations that are used in WCS-ECI coordinate conversions. **Default** 1000 s .. deprecated:: 2.9 This command will be replaced by nutation_update_interval_. .. command:: mgrs_coordinate Specifies the coordinates of the platform in the Military Grid Reference System. This command is only for static platforms without movers. .. command:: altitude [ agl | msl ] Specifies the altitude of the platform. This command is only for static platforms without movers. It is ignored if a mover is defined in the platform. **Default** 0 m msl .. command:: creation_time Specifies the simulation time at which the platform is to be added to the simulation. The platform exists in memory but is not yet a player in the simulation. **Default** 0 sec (created at the start of the simulation). .. command:: heading Specifies the orientation of the platform. This command is only for static platforms without movers. It is ignored if a mover is defined in the platform. **Default** 0 deg .. command:: empty_mass Specifies the empty mass of the platform, which is usually a fixed quantity. **Default** 0 kg .. note:: Some movers provide a different mechanism for providing this value. .. command:: fuel_mass Specifies the fuel mass of the platform. When specified by a user in an input file, the value is assumed to be a fixed quantity. However, if the platform contains a :command:`fuel` object, it is permitted and even expected to modify the fuel mass during run time, overwriting what was specified with this keyword. **Default** 0 kg .. note:: Some movers provide a different mechanism for providing this value. .. command:: payload_mass Specifies the payload mass of the platform. When specified by a user in an input file, the value is assumed to be a fixed quantity. However, certain run-time events (e.g., dropping buoys) may change the payload mass. **Default** 0 kg .. note:: Some movers provide a different mechanism for providing this value. .. command:: concealment_factor Used to denote how well a platform is VISUALLY concealed. A value of 0.0 means there is no attempt to hide. A factor of 1.0 means that it is hidden in such a way as to be undetectable (such as in a building or in an underground bunker). Values between the endpoints represent increasing amounts of camouflage. Most sensors will not detect platforms with a concealment factor of 1.0, but any lesser value has no effect. **Default** 0.0 .. command:: initial_damage_factor The damage factor is a value in the range [0 .. 1] and is used to indicate the amount of damage to the platform. A value of 0 indicates no damage while a value of 1 indicates the platform is 'broken.' **Default** 0.0 .. command:: track_manager track_manager#Commands track-manager-commands ... end_track_manager Commands within this block are processed by the platform's master track manager. See :command:`track_manager`. .. command:: aux_data ... end_aux_data Defines auxiliary data for a platform. See :command:`_.aux_data`. .. command:: height .. command:: length .. command:: width Specifies the dimensions of the platform. **Default** 0 for all values .. note:: If all of these have non-zero values and optical_signature_ was not specified, these values will be used to compute the optical cross section when needed. .. command:: category Specifies that the platform is a member of the category specified. Categories can be used to force sensors to :command:`sensor.ignore` the platform. Categories are also accessible through the :method:`WsfPlatform.CategoryMemberOf` script method. **Default** The platform is not a member of any categories. .. command:: clear_categories Has the effect of canceling any previous category_ command. .. command:: group_join .. command:: group_leave Adds or removes the platform from the specified :class:`group `. .. command:: commander .. command:: command_chain **commander** specifies the platform's immediate superior (commander) in the default chain of command. **command_chain** specifies the platform's immediate superior (commander) in the given chain of command. A chain of command is used by decision making routines to determine the recipients of orders and/or reports. .. note:: See :doc:`command_chains` for more information and examples. The name of the command chain of to which this command applies. (The default command chain is implied for commander). | SELF The name of the platform that is the immediate superior (commander) of this platform. **Default** commander SELF .. command:: route route-commands ... end_route The :command:`route` subcommand provides a collection of waypoints that define a path, or route, for platform movers. .. command:: add_mover mover-commands ... end_mover .. command:: mover mover-commands ... end_mover A :command:`mover` defines the domain in which a platform can move and how it moves within the domain. * The **add mover** command is only required inside of the **platform** command (i.e., not inside of the **platform_type** command). .. command:: fuel fuel-commands .. end_fuel A :command:`fuel object ` can be attached to a platform to model the effects of fuel consumption. **Default** No fuel object is defined (fuel consumption is not modeled). .. note:: Some movers model fuel consumption internally. .. _platform.component: ** [] component-commands ... end_** .. command:: add component-commands ... end_ .. command:: edit component-commands ... end_ .. command:: delete Adds a component to the platform, modifies or removes an existing component. * The **add ** command adds a new component to the platform/platform_type. * The **edit ** command modifies an existing component on the platform/platform_type. * The **delete ** command removes an existing component on the platform/platform_type. * The **** command is an abbreviated version, which adds a component if used inside a **platform_type** and modifies an existing component when used inside a **platform**. * A valid **** includes :command:`comm`, :command:`fuel`, :command:`mover`, :command:`processor`, :command:`sensor`, etc. .. note:: When using edit or delete commands with a fuel or mover, you do not specify the . .. note:: Zones can be removed with the delete command but can't be modified via the add or edit commands. .. command:: track ... end_track Defines a pre-briefed :command:`track`. .. command:: use_zone as Attach a copy of the specified zone to the platform under the name . If the specified zone does not define a pose, the copied zone uses the current pose of the platform. This command can be repeated as necessary. .. command:: zone ... end_zone .. command:: zone_set ... end_zone_set The :command:`zone` and :command:`zone_set` subcommands define: * Relative zones which align with the platform pose. * Relative zones which maintain a static pose. * Absolute zones which maintain a static pose. .. seealso:: :command:`zone` and :command:`zone_set` for subcommands to affect simulated behavior. .. command:: navigation_errors ... end_navigation_errors The :command:`_.navigation_errors` block provides a method to define error in where the platform thinks it is located versus where it is really located. Please see :command:`_.navigation_errors` for a description of the inputs. **Default** No navigation errors. Script Interface ================ :command:`platform` uses the capabilities of the :ref:`Common_Script_Interface` and implements the following additional commands: .. command:: on_damage_received :: script void on_damage_received() ... end_script An optional script that can be defined which will receive control whenever there is damage to the platform. This script is generally used with the indestructible_ or on_broken_ command. Normally, when a platform takes damage, the platform is removed from the simulation if it is determined that this damage caused the platform to break. If **indestructible**, **on_broken disable**, or **on_broken disabled_but_movable** are specified, the platform will not be deleted, but instead the damage factor (DamageFactor) will be incremented and this script will be called. The script can do things like stop movement, turn off sensors, change appearance, etc. .. note:: If **on_broken disable** was specified, the platform motion will be halted and all subsystems will be set to nonoperational without any additional intervention. If **on_broken disabled_but_movable** was specified, the platform motion will continue, but and all subsystems will be set to nonoperational without any additional intervention. .. command:: on_platform_deleted :: script void on_platform_deleted() ... end_script An optional script that can be defined which will receive control just before the platform is removed from the simulation. .. command:: on_commander_deleted .. command:: on_peer_deleted .. command:: on_subordinate_deleted .. parsed-literal:: script void on_commander_deleted(:class:`WsfPlatform` aCommander) ... end_script script void on_peer_deleted(:class:`WsfPlatform` aPeer) ... end_script script void on_subordinate_deleted(:class:`WsfPlatform` aSubordinate) ... end_script Optional scripts that can be defined which will be executed just before other platforms within the platform's command_chain_ hierarchy are removed from the simulation. The single argument to each script is a reference to the platform pending removal. .. command:: callback callback-commands end_callback A :command:`platform.callback` is a named action that can be called via the :command:`route.execute` command of a :command:`route` when the platform reaches a particular waypoint within the route. .. note:: This is an obsolete form that has been replaced by scripts. .. include:: _platform.wsf_mil.txt