WSF_SA_PROCESSOR¶
Derives from: WSF_SCRIPT_PROCESSOR
Script Class: WsfSA_Processor
- processor WSF_SA_PROCESSOR¶
processor <name> WSF_SA_PROCESSOR // Update Interval Commands report_interval ... engagement_data_update_interval ... flight_data_update_interval ... fuel_data_update_interval ... nav_data_update_interval ... flight_controls_data_update_interval ... weapons_data_update_interval ... asset_data_update_interval ... asset_purge_lifetime ... perceived_item_data_update_interval ... prioritized_item_data_update_interval ... perceived_item_calculation_update_interval ... prioritized_item_calculation_update_interval ... behavior_calculation_update_interval ... // Update Interval Group Commands cognitive_update_interval ... platform_update_interval ... universal_update_interval ... // Enemy/Friendly Types enemy_side ... friendly_side ... neutral_side ... enemy_type ... friendly_type ... neutral_type ... missile_type ... asset_ignore ... filter_assets_from_tracks ... use_iff_id ... use_simple_id_by_type ... // Missile Identification Filters missile_speed_any_alt <speed-value> missile_alt_any_speed <length-value> missile_speed_with_alt <speed-value> missile_alt_with_speed <length-value> missile_nose_angle <angle-value> missile_time_to_intercept <time-value> missile_distance <length-value> // Range Settings max_range_for_perceived_assets ... max_range_for_perceived_bogies_and_bandits ... max_range_for_engagement_data ... assumed_range_for_angle_only_targets ... // Filter Settings for Engagement Assessment filter_requires_same_side ... filter_requires_not_same_side ... filter_requires_air_domain ... filter_requires_not_air_domain ... filter_requires_land_or_surface_domain ... filter_requires_not_subsurface_domain ... filter_requires_not_space_domain ... filter_requires_sa_processor ... // Optional Track Processors esm_track_processor ... mws_track_processor ... radar_track_processor ... irst_track_processor ... das_track_processor ... flir_track_processor ... eyes_track_processor ... perception_master_track_processor ... // Optional IDs flight_id ... id_flag ... // Fuel Data bingo_fuel ... joker_fuel ... // Perception Commands reports_self ... | reporting_self ... reports_others ... | reporting_others ... asset_perception ... perceive_self ... max_threat_load ... max_asset_load ... asset_coast_time ... bandit_coast_time ... bogey_coast_time ... use_simple_countermeasures ... num_chaff ... num_flares ... num_decoys ... filter_assets_from_bogies ... consideration_score_randomness ... display_perception_delay ... visual_perception_delay ... // Assessment Commands bogie_threat_score_multiplier ... bogie_target_score_multiplier ... ignore_bogies_when_grouping ... mission_task ... max_prioritized_threats ... max_prioritized_targets ... max_grouping_distance_centroid ... max_grouping_distance_neighbor ... max_grouping_speed_difference ... max_grouping_heading_difference ... min_group_radius ... use_centroid_grouping ... use_neighbor_grouping ... use_speed_grouping ... use_heading_grouping ... use_type_grouping ... ignore_missiles_as_threats ... ignore_bogies_as_threats ... ignore_missiles_as_targets ... ignore_bogies_as_targets ... missile_wez_parameters ... aircraft_signature_parameters ... // Custom Scripts script double AssetConsiderationScoring ... script double BogieBanditConsiderationScoring ... script double MissileConsiderationScoring ... script double UnfocusedGroupConsiderationScoring ... script Array<WsfSA_PerceivedItem> CreatePerceivedItemPruningArray ... script double CalculateRisk ... script double CalculateSelfRisk ... script double CalculateFlightRisk ... script double CalculatePackageRisk ... script double CalculateMissionRisk ... script double CalculateDefensiveness ... script double CalculateUrgency ... script bool CalculateWeaponSupport ... script double CalculateThreatLevel ... script double CalculateMissileThreatLevel ... script double CalculateGroupThreatLevel ... script double CalculateTargetValue ... script double CalculateMissileTargetValue ... script double CalculateGroupTargetValue ... script double CalculateRiskPosedByEntity ... script double CalculateDefensivenessInducedByEntity ... script double CalculateUrgencyInducedByEntity ... script WsfGeoPoint ProjectPositionInTime ... script WsfGeoPoint ProjectPositionForward ... script WsfGeoPoint ProjectPositionLevelTurnLeft ... script WsfGeoPoint ProjectPositionLevelTurnRight ... script WsfGeoPoint ProjectPositionTurnToHeading ... script WsfGeoPoint ProjectPositionGoToPoint ... script WsfGeoPoint ProjectPositionSlice ... script WsfGeoPoint ProjectPositionSliceToHeading ... script WsfGeoPoint ProjectPositionSplitS ... end_processor
Overview¶
The Situation Awareness (SA) Processor is a critical component of AFSIM’s cognitive model, providing perception, assessment/comprehension, and prediction/projection functions. The SA Processor is based on Endsley’s Model of Situational Awareness, and provides the means to perform the Observe and Orient (OO) components of the OODA loop, while Advanced Behavior Trees (ABTs) provide the means to perform the Decide and Act (DA) components of the OODA loop.
Perceived Items are the primary approach in the SA Processor for modeling cognitive load and limits. Perceived Items include both groups and entity perceptions. Pilots utilize groups or clusters of threats/targets to reduce the number of items being perceived. In some cases, rather than perceiving and remembering each item in a group, the pilot instead perceives and remembers the group. Hence, rather than perceiving a collection of four aircraft, the pilot instead perceives a single group, reducing the number of perceived items from 4 to 1. We call this an unfocused group perception, and it is a means to reduce the number of perceived items while still maintaining some SA. However, in other cases, the pilot may want to have detailed perception of each item in a group, and in this case, the pilot may perceive that the items form a “conceptual” group, simply as a means of organization. We call this focused or detailed group perception, since it maintains the full details of the members of group and the pilot is focused on the members of the group. This type of group does not affect the number of perceived items.
There are two ways of looking at detailed groups: entity-centric, or group-centric. From an entity-centric perspective, a detailed group neither increases nor reduces the number of perceived items, and each of the entities it contains increase the number of perceived items by one. From a group-centric perspective, a detailed group increases the number of perceived items by the number of entities that it contains. Similarly, from an entity-centric perspective, detailed groups have no consideration score, but from a group-centric perspective, a detailed group’s score is equivalent to that of its highest scoring member.
Note
Groups and cognitive limits are meant to be used for human pilots – synthetic pilots on autonomous vehicles typically do not use groups to reduce cognitive loads, since they often have rather large limits and do not need to reduce cognitive load in this manner.
Groups can be formed, disbanded, focused, or unfocused automatically by the SAP. However, many of its automatic functions can be overridden with custom scripts.
Note
The SA Processor replaces some functionality previously performed by the WSF_PERCEPTION_PROCESSOR. Although a Perception Processor is allowed on a platform with an SA Processor, that is not the intended configuration and should be avoided, whenever possible.
The cognitive model is shown in the image below. Across the bottom, in red, is Boyd’s OODA (Observe, Orient, Decide, and Act) model. In AFSIM, the OODA loop is divided into two modules, displayed just above the OODA block. SA Processors, in blue, handle observation and orientation, and Advanced Behavior Trees (ABTs), in green, carry out decision and action.
Above: AFSIM Awareness Cognitive Model, including SA Processor and ABTs¶
The image below presents Endsley’s Model of Situational Awareness. The SA Processor closely parallels the concept of perception, comprehension, and projection.
Above: Endsley’s Model of Situational Awareness, Endsley et al (2000), drawn by Dr. Peter Lankton (May 2007)¶
The table below defines common technical terms used throughout the documentation for air-to-air combat related concepts.
bogie |
A perceived entity (unknown) that has yet to be identified as a bandit, friendly, or neutral |
|---|---|
bandit |
A perceived entity that is known to be an enemy |
friendly |
A perceived entity that is known to be friendly |
neutral |
A perceived entity that is known to be neutral (often a non-combatant) |
asset |
Another term for “friendly”. This term is typically used to denote friendly forces that could provide support |
threat |
A bandit/bogie that has been prioritized by threat scoring and maintained in a prioritized/ordered list |
target |
A bandit/bogie that has been prioritized by target scoring and maintained in a prioritized/ordered list |
Visualization Tools¶
There are several visualization tools to support the WSF_SA_PROCESSOR, including (click on the name of each tool for more information)
Air Combat Engagement Summary (ACES) Display
The ACES Display is intended to provide an integrated display that provides several sets of air combat data for a platform that contains a WSF_SA_PROCESSOR in a single, reconfigurable display, including:
Tactical Situation Display
Stores Management System
Tactical Warning System
Engine Systems
Fuel Systems
Situation Awareness Display which shows a variety of data, including:
Perceived Assets, Bogies, and Bandits
Prioritized Threats
Prioritized Targets
Perceived Groups
“Truth” locations of platforms in the simulation
Allows users to quickly toggle between the perceived “picture” and the true state of the world.
This is an out-the-window (OTW) view with a generic Head-Up Display (HUD).
Air Combat Visualization - Map Display
This is a collection of visualization items for the Map Display, including:
Data Rings, which provide a means to shown normalized data in a concise manner.
Data Accents, which provide another means to shown discrete, state-based data in a concise manner.
State Data, which is a summary of top-level state data
Displayed in a similar manner to that on air traffic control screens
Provides altitude, vertical speed, airspeed, Mach, g-load, and angle of attack at a glance.
Engagement Lines, which provide an alternative to typical AFSIM track lines
Shows detection and WEZ data between two (or more) platforms
Air Combat Visualization - Air Combat Overlays (Tether View)
This is a summary of engagement data using an overlay on a tether display, providing:
Engagement data for focus aircraft versus target/threat aircraft (lower left)
Engagement data for focus target/threat versus focus aircraft (lower right)
Kinematic state data for focus aircraft (upper left)
Fuel state data for focus aircraft (upper left)
Tactical data summary for focus aircraft, including weapons state (upper right)
Update Interval Commands¶
The SA Processor has multiple responsibilities which can be carried out at different rates. These rates can be given initial values and can also be changed during the simulation through script.
Some of these only determine the rate at which data is sent through the event pipe. These have the suffix data_update_interval. However, others determine the rate at which information is processed internally. These use the suffix calculation_update_interval.
Updates can only happen when the processor itself (whose update rate is set by update_interval) updates. As a result, best practice is to make sure that the following update intervals are each multiples of update_interval.
Warning
All update interval settings in this section will be rounded to the nearest multiple of the update_interval value. To prevent rounding to zero, a positive setting less than update_interval/2 will be rounded to asset_perception; however, a value of zero can be used to disable a specific update type.
- report_interval <time-value>¶
Specifies the update interval for reporting asset status data
Default: 0 seconds (no data sent)
- engagement_data_update_interval <time-value>¶
Specifies the update interval for reporting engagement data (MsgSA_EngagementSummaryData messages)
Default: 0 seconds (no data sent)
- flight_data_update_interval <time-value>¶
Specifies the update interval for reporting flight data (MsgSA_FlightKinematicsData messages)
Default: 0 seconds (no data sent)
- fuel_data_update_interval <time-value>¶
Specifies the update interval for reporting fuel data (MsgSA_FuelData messages)
Default: 0 seconds (no data sent)
Specifies the update interval for reporting navigational data (MsgSA_NavData messages)
Default: 0 seconds (no data sent)
- flight_controls_data_update_interval <time-value>¶
Specifies the update interval for reporting controls data (MsgSA_FlightControlsData messages)
Default: 0 seconds (no data sent)
- weapons_data_update_interval <time-value>¶
Specifies the update interval for reporting weapons data (MsgSA_WeaponsData messages)
Default: 0 seconds (no data sent)
- track_data_update_interval <time-value>¶
Specifies the update interval for reporting track data (MsgSA_TrackData messages)
Default: 0 seconds (no data sent)
- asset_data_update_interval <time-value>¶
Specifies the update interval for reporting asset data (MsgSA_PerceivedAssetsData messages)
Default: 0 seconds (no delayed interval, uses current truth or received asset messages; see asset_perception)
- asset_purge_lifetime <time-value>¶
Specifies the maximum lifetime of assets that lack an update. Assets will be automatically purged if they have not been updated within the specified lifetime limit.
Default: The default value depends on whether asset_update_interval has been specified. If so, the default purge lifetime is 2.5 times the asset_update_interval. If not, a default of 5 seconds is used.
- perceived_item_data_update_interval <time-value>¶
Specifies the update interval for reporting bogie, bandit, and group data (MsgSA_PerceivedBogiesAndBanditsData and MsgSA_GroupsData messages).
Default: 0 seconds (no data sent)
- prioritized_item_data_update_interval <time-value>¶
Specifies the update interval for reporting prioritized threat data (MsgSA_PrioritizedThreatsAndTargetsData messages).
Default: 0 seconds (no data sent)
- perceived_item_calculation_update_interval <time-value>¶
Specifies the update interval for calculating bogie, bandit, and group data.
Default: 0 seconds (no data calculated)
- prioritized_item_calculation_update_interval <time-value>¶
Specifies the update interval for calculating prioritized threat data.
Default: 0 seconds (no data calculated)
- behavior_calculation_update_interval <time-value>¶
The SA Processor is unique in that the rate at which WsfAdvancedBehaviorTrees and WsfStateMachines update can be optionally set separately from the processor’s update rate. As a result, the default value of 0 means that it will update at the same rate as the processor, as opposed to never updating.
Default: 0 seconds (updates whenever the processor itself updates)
Update Interval Group Commands¶
Some of the above interval commands can be set to a common value within pre-defined groups: cognitive_update_interval, platform_update_interval, and universal_update_interval.
Note
Only data update intervals can be set this way. Calculation update intervals must be set individually.
- cognitive_update_interval <time-value>¶
The following group of Update Interval Commands is set to a common value by this command:
- platform_update_interval <time-value>¶
The following group of Update Interval Commands is set to a common value by this command:
- universal_update_interval <time-value>¶
All Update Interval Commands are set to a common value by this command (excludes asset_purge_lifetime and all calculation update interval commands).
Enemy/Friendly Types¶
The WSF_SA_PROCESSOR supports the use of multiple techniques to determine if a WsfSA_EntityPerception is perceived as a friend, foe, neutral, or unknown. The commands below allow perception based on the side of the platform, the type of platform, and whether IFF should be used. In addition, missile types can be specified and if the platform type is used for perception, it may also be perceived as a missile, rather than the default, which is an aircraft. A WsfSA_EntityPerception may also be perceived as a missile if the platform is a category missile.
- enemy_side <string>¶
Specifies the name(s) of the enemy’s side(s). If a track has the same side identification as the enemy_side, then the track is considered to be a bandit. Note that multiple entries allows multiple sides to be enemy.
- friendly_side <string>¶
Specifies the name(s) of the friendly side(s). If a track has the same side identification as the friendly_side, then the track is considered to be a friendly. Note that multiple entries allows multiple sides to be friendly. In addition, the same side of the platform containing the SA Processor is always considered friendly, even without specifying it in this manner.
- neutral_side <string>¶
Specifies the name(s) of the neutral side(s). If a track has the same side identification as the neutral_side, then the track is considered to be a neutral. Note that multiple entries allows multiple sides to be neutral.
- enemy_type <string>¶
Adds the enemy type to the list of known enemy types. If a track has the same type identification as the enemy_type, then the track is considered to be a bandit. Note that the type does not necessarily have to be a platform type, it may also be a sensor type, since some sensors will report a sensor type rather than a platform type.
- friendly_type <string>¶
Adds the friendly type to the list of known friendly types. If a track has the same type identification as the friendly_type, then the track is considered to be friendly. Note that the type does not necessarily have to be a platform type, it may also be a sensor type, since some sensors will report a sensor type rather than a platform type.
- neutral_type <string>¶
Adds the neutral type to the list of known neutral types. If a track has the same type identification as the neutral_type, then the track is considered to be neutral. Note that the type does not necessarily have to be a platform type, it may also be a sensor type, since some sensors will report a sensor type rather than a platform type.
- missile_type <string>¶
Adds the missile type to the list of known missile types. If a track has the same type identification as the missile_type, then the track is considered to be a missile. Note that the type does not necessarily have to be a platform type, it may also be a sensor type, since some sensors will report a sensor type rather than a platform type.
- asset_ignore <category-name>¶
Adds the platform category to a list of assets that will be ignored on the ACES Display.
- filter_assets_from_tracks <boolean-value>¶
If true, assets/friendlies will be filtered from track lists
Default: true
- use_iff_id <boolean-value>¶
If true, includes the use of IFF in determining identification. When used, iff_mapping must be defined.
Default: false
- use_simple_id_by_type <boolean-value>¶
If true, a simple identification-by-type approach will be used. In this case, rather than specifying list of enemy, friendly, and neutral types using enemy_side, friendly_side, and neutral_side, a much simpler approach is used, where identification-by-type is performed merely if the track supports type id.
Default: false
Missile Identification Filters¶
These commands provide a means to identify/classify tracks as missiles. Any track meeting these conditions will be considered to be a missile.
In addition, using the missile types defined in Enemy/Friendly Types allows the entity to be perceived as a missile, rather than the default, which is an aircraft. A WsfSA_EntityPerception may also be perceived as a missile if the platform is a category missile.
- missile_speed_any_alt <speed-value>¶
If the speed of the track is greater than the specified speed and at any altitude, it will be considered to be a missile/weapon (not an aircraft).
- missile_alt_any_speed <length-value>¶
If the altitude of the track is greater than the specified altitude and at any speed, it will be considered to be a missile/weapon (not an aircraft).
- missile_speed_with_alt <speed-value>¶
If the speed of the track is greater than the specified speed at (or greater than) the altitude specified in missile_alt_with_speed, it will be considered to be a missile/weapon (not an aircraft).
- missile_alt_with_speed <length-value>¶
If the altitude of the track is greater than the specified altitude at (or greater than) the speed specified in missile_speed_with_alt, it will be considered to be a missile/weapon (not an aircraft).
These commands provide a means to filter-out tracks from consideration as missiles. Any track meeting these conditions will not be considered to be a missile (they will be filtered-out).
- missile_nose_angle <angle-value>¶
If the ownship lies outside of the specified angle off the nose of the track, it will not be considered to be a missile/weapon (not an aircraft). This allows filtering-out tracks that are not heading towards the ownship.
- missile_time_to_intercept <time-value>¶
If the time to intercept of the track is greater than than the specified time, it will not be considered to be a missile/weapon (not an aircraft). This allows filtering-out tracks that will not intercept the ownship within the specified time.
- missile_distance <length-value>¶
If the distance to the track is greater than the specified distance, it will not be considered to be a missile/weapon (not an aircraft). This allows filtering-out tracks at a long distance from being considered as missiles.
Range Settings¶
- max_range_for_perceived_assets <length-value>¶
Range limit to include an asset in the perceived asset list. If not specified, no range filter will be used for assets.
- max_range_for_perceived_bogies_and_bandits <length-value>¶
Range limit to include a bogie/bandit in the perceived bogie/bandit list. If not specified, no range filter will be used for bogies or bandits.
- max_range_for_engagement_data <length-value>¶
Range limit to report engagement data. If not specified, no range filter will be used on the reporting of engagement data.
- assumed_range_for_angle_only_targets <length-value>¶
Range assumed for angle-only tracks. If not specified, the range for angle-only tracks will be assumed to be 2.0E+13 meters, which is greater than 100 times the distance from the Earth to the Sun.
Default: 2.0E+13 meters
Filter Settings for Engagement Assessment¶
- filter_requires_same_side <boolean-value>¶
If true, filters out platforms that are not on the same side
Default: false
- filter_requires_not_same_side <boolean-value>¶
If true, filters out platforms that are on the same side
Default: false
- filter_requires_air_domain <boolean-value>¶
If true, filters out platforms that are not in the air domain
Default: false
- filter_requires_not_air_domain <boolean-value>¶
If true, filters out platforms that are in the air domain
Default: false
- filter_requires_land_or_surface_domain <boolean-value>¶
If true, filters out platforms that are not in the land or surface domains
Default: false
- filter_requires_not_subsurface_domain <boolean-value>¶
If true, filters out platforms that are in the subsurface domain
Default: false
- filter_requires_not_space_domain <boolean-value>¶
If true, filters out platforms that are in the space domain
Default: false
- filter_requires_sa_processor <boolean-value>¶
If true, filters out platforms that lack a WSF_SA_PROCESSOR
Optional Track Processors¶
These optional definitions define track processors that are used for various sensor system functionality. These assist visualization tools to determine which tracks are associated with a particular sensor system, such as an ESM/RWR.
- esm_track_processor <string>¶
Optional name of a track processor for ESM/RWR tracks. This allows perception of tracks related to ESM and/or RWR sensor systems.
- mws_track_processor <string>¶
Optional name of a track processor for Missile Warning System (MWS) tracks. This allows perception of tracks related to MWS sensor systems.
- radar_track_processor <string>¶
Optional name of a track processor for radar tracks. This allows perception of tracks related to radar sensor systems.
- irst_track_processor <string>¶
Optional name of a track processor for IRST tracks. This allows perception of tracks related to IRST and/or other IR sensors used for detection of airborne platforms.
- das_track_processor <string>¶
Optional name of a track processor for DAS (Distributed Aperture System) tracks. This allows perception of tracks related to DAS and/or other multi-aperture IR/EO sensor systems.
- flir_track_processor <string>¶
Optional name of a track processor for FLIR tracks. This allows perception of tracks related to FLIRs and/or other imaging IR sensor systems that are primarily used for detection of surface-based platforms.
- eyes_track_processor <string>¶
Optional name of a track processor for eyes (visual) tracks. This allows perception of tracks related to any aircrew visual (eyes) sightings.
- perception_master_track_processor <string>¶
Optional name of a track processor for collecting/coordinating perceived tracks. If this is defined, the specified track processor will be used by the SA Processor when perceiving and assessing tracks. If not specified, the master track processor is used (default).
Optional IDs¶
Fuel Data¶
- bingo_fuel <mass-value>¶
Optional bingo fuel level. If not specified, the mover value is used (if available), else zero is used.
Default: 0
- joker_fuel <mass-value>¶
Optional joker fuel level. If not specified, the mover value is used (if available), else zero is used.
Default: 0
Perception Commands¶
- reports_self <boolean-value>¶
- reporting_self <boolean-value>¶
Specifies whether or not to report out asset status messages about this platform.
Default: true
- reports_others <boolean-value>¶
- reporting_others <boolean-value>¶
Specifies whether or not to report out messages of all received and known asset status (of other platforms).
Default: false
- asset_perception [ status_messages; truth <members> ]¶
status_messages: asset perception will utilize any received WsfSA_EntityMessage messages.
truth <members>: asset perception will traverse the command chain and use truth data.
<members> is a colon-separated list of ‘commander’, ‘subordinates’, ‘peers’, ‘all_commanders’, &/or ‘all_subordinates’. Example:
# Uses truth data for this platform's commander and all subordinates down the entire command chain asset_perception truth all_subordinates:commander
Default: truth (but no members, so empty perception).
Warning
At the present time, with the SA Processor in a “beta” release, the truth option is recommended. In some situations, using the status_messages may result in some assets being dropped due to purge problems. This will be addressed in the future.
- perceive_self¶
Include this platform in the list of perceived assets.
Default: false
- max_threat_load <integer>¶
Specifies the maximum number of bogie/bandit entities and unfocused groups (i.e. perceived items) that may be perceived.
Default: -1 (no max limit)
- max_asset_load <integer>¶
Specifies the maximum number of assets that may be perceived.
Default: -1 (no max limit)
- asset_coast_time <time-value>¶
Specifies the amount of time that asset perceptions should persist after losing a track.
Default: 0 seconds
- bandit_coast_time <time-value>¶
Specifies the amount of time that bandit perceptions should persist after losing a track.
Default: 0 seconds
- bogey_coast_time <time-value>¶
Specifies the amount of time that bogey perceptions should persist after losing a track.
Default: 0 seconds
- use_simple_countermeasures <boolean-value>¶
If true, the processor will use num_chaff, num_flares, and num_decoys as the initial countermeasure quantities. When WsfSA_Processor.DispenseChaff, WsfSA_Processor.DispenseFlare, and WsfSA_Processor.DispenseDecoy are invoked, these quantities are simply decremented (nothing is physically fired). If false, the processor will model countermeasures using instances of WSF_CHAFF_WEAPON, WSF_FLARE_WEAPON, and WSF_DECOY_WEAPON defined on the parent platform. When WsfSA_Processor.DispenseChaff, WsfSA_Processor.DispenseFlare, and WsfSA_Processor.DispenseDecoy are called, the respective countermeasures are fired.
This approach provides a simple means of using expendable countermeasures (CM), allowing weapon scripts to inquire how many CM are present when the weapon was fired and then checking again when the weapon detonates – using the difference of the two quantities provides the number of CM that were dispensed during the weapon flight, which can then be used to model an effect of the CM upon weapon effectiveness.
Default: false
- num_chaff <integer>¶
When used together with use_simple_countermeasures, specifies the initial chaff quantity.
Default: 0
Note
This command is only applicable if use_simple_countermeasures is true.
- num_flares <integer>¶
When used together with use_simple_countermeasures, specifies the initial flare quantity.
Default: 0
Note
This command is only applicable if use_simple_countermeasures is true.
- num_decoys <integer>¶
When used together with use_simple_countermeasures, specifies the initial decoy quantity.
Default: 0
Note
This command is only applicable if use_simple_countermeasures is true.
- filter_assets_from_bogies <boolean-value>¶
If true, known assets will automatically be filtered from bogies.
Default: true
- consideration_score_randomness <real>¶
If set, the consideration scores for perceived items will be randomly increased or decreased by an amount less than or equal to this value.
For more information about consideration scores for perceived items, see BogieBanditConsiderationScoring and UnfocusedGroupConsiderationScoring.
Default: 0.0
- display_perception_delay <time-value>¶
Specifies the time to wait before recognizing a new non-visual track as a perceived entity that is available for processing and classification.
Default: 0.0 seconds
- visual_perception_delay <time-value>¶
Specifies the time to wait before recognizing a new visual track (i.e. eyes_track_processor) as a perceived entity that is available for processing and classification.
Default: 0.0 seconds
Assessment Commands¶
- bogie_threat_score_multiplier <real>¶
Multiplier that is used when scoring bogies for the prioritized threat list.
Default: 1.0
- bogie_target_score_multiplier <real>¶
Multiplier that is used when scoring bogies for the prioritized target list.
Default: 1.0
- ignore_bogies_when_grouping <boolean-value>¶
If true, bogies will not be considered when forming groups.
Default: false
- mission_task <string>¶
Specifies the primary mission task. This is used in Air Combat Event Pipe data and for display purposes in the Air Combat Visualization Plugin’s Air Combat Overlays.
Default: [empty]
- max_prioritized_threats <integer>¶
Specifies limitation to prioritized threat list count.
Default: 0 no limit
- max_prioritized_targets <integer>¶
Specifies limitation to prioritized target list count.
Default: 0 no limit
- max_grouping_distance_centroid <length-value>¶
If use_centroid_grouping is true, the maximum distance an entity can be from a group centroid to be considered part of the group.
Default: 8 nautical miles
- max_grouping_distance_neighbor <length-value>¶
If use_neighbor_grouping is true, the maximum distance an entity can be from another entity in a group to be considered part of the same group.
Default: 4 nautical miles
- max_grouping_speed_difference <length-value>¶
If use_speed_grouping is true, the maximum difference in speed an entity can be from a group centroid to be considered part of the group.
Default: 100 knots
- max_grouping_heading_difference <angle-value>¶
If use_neighbor_grouping is true, the maximum difference in heading an entity can be from a group centroid to be considered part of the group.
Default: 10 degrees
- min_group_radius <length-value>¶
The minimum radius for a group. The group radius is the maximum of the min_group_radius and the largest distance between a group member and the group centroid.
Default: 1 nautical mile
- use_centroid_grouping¶
Specifies whether an entity must be within max_grouping_distance_centroid of the group centroid to be considered part of the group.
Default: true
- use_neighbor_grouping¶
Specifies whether an entity must be within max_grouping_distance_neighbor of another entity in a group to be considered part of that group.
Default: true
- use_speed_grouping¶
Specifies whether an entity must be within max_grouping_speed_difference of the group centroid to be considered part of the group. This only applies when entities are considered for joining a group, not for continuing to stay in the group.
Default: true
- use_heading_grouping¶
Specifies whether an entity must be within max_grouping_heading_difference of the group centroid to be considered part of the group. This only applies when entities are considered for joining a group, not for continuing to stay in the group.
Default: true
- use_type_grouping¶
Specifies whether an entity must be the same type as the other members of a group to be considered part of the group. This only applies when entities are considered for joining a group, not for continuing to stay in the group.
Default: false
- ignore_missiles_as_threats <boolean>¶
Specifies whether perceived missile entities should be ignored when calculating threat values. Typically, perceived missiles are considered threats and are not ignored.
Default: false
- ignore_bogies_as_threats <boolean>¶
Specifies whether perceived bogie entities should be ignored when calculating threat values. Typically, perceived bogies are considered threats and are not ignored.
Default: false
- ignore_missiles_as_targets <boolean>¶
Specifies whether perceived missile entities should be ignored when calculating target values. Typically, perceived missiles are not considered targets and are ignored.
Default: true
- ignore_bogies_as_targets <boolean>¶
Specifies whether perceived bogie entities should be ignored when calculating target values. Typically, perceived bogies are not considered targets and are ignored.
Default: true
- missile_wez_parameters … end_missile_wez_parameters¶
Defines parameters for WEZ calculations. See missile_wez_parameters.
- aircraft_signature_parameters … end_aircraft_signature_parameters¶
Defines parameters for aircraft signatures. See aircraft_signature_parameters.
Custom Scripts¶
Optionally, the user may choose to override default behaviors and functionality of the WSF_SA_PROCESSOR through the use of “custom scripts”.
Custom scripts include the following:
- AssetConsiderationScoring (script)¶
script double AssetConsiderationScoring(WsfSA_EntityPerception aAsset) end_script
This is an optional script used to measure asset importance, which is used to determine how strongly the asset should be considered for maintaining perception. If this function is present, it completely overrides the use of any script functions that try to set asset importance or unimportance. This is only useful when max_asset_load is defined, otherwise no limit will be imposed and importance is not necessary. Values returned by the script may be any value (positive or negative), but assets presenting negative scores will be discarded from consideration. High scores indicate a greater interest in the asset, as compared to others.
- BogieBanditConsiderationScoring (script)¶
script double BogieBanditConsiderationScoring(WsfLocalTrack aTarget) end_script
This is an optional script used to measure bogie/bandit importance, which is used to determine how strongly the bogie/bandit should be considered for maintaining perception. If this function is present, it completely overrides the use of any script functions that try to set bogie/bandit importance or unimportance. This is only useful when max_threat_load is defined, otherwise no limit will be imposed and importance is not necessary. Values returned by the script may be any value (positive or negative), but bogies/bandits presenting negative scores will be discarded from consideration. High scores indicate a greater interest in the bogie/bandit, as compared to others.
This is used along with MissileConsiderationScoring (below). MissileConsiderationScoring provides special scoring for missiles, whereas BogieBanditConsiderationScoring provides a general consideration scoring that can be used by both aircraft and missiles. BogieBanditConsiderationScoring may be used without MissileConsiderationScoring, in which case it provides scoring for both aircraft and missiles. If MissileConsiderationScoring is present, it will be used for all bogies/bandits that are perceived as missiles.
- MissileConsiderationScoring (script)¶
script double MissileConsiderationScoring(WsfLocalTrack aTarget) end_script
This is an optional script used to measure perceived missile bogie/bandit importance, which is used to determine how strongly the missile bogie/bandit should be considered for maintaining perception. If this function is present, it completely overrides the use of any script functions that try to set missile bogie/bandit importance or unimportance. This is only useful when max_threat_load is defined, otherwise no limit will be imposed and importance is not necessary. Values returned by the script may be any value (positive or negative), but missile bogies/bandits presenting negative scores will be discarded from consideration. High scores indicate a greater interest in the missile bogie/bandit, as compared to others.
This is used along with BogieBanditConsiderationScoring (above), to provide special scoring for missiles, whereas BogieBanditConsiderationScoring provides a general consideration scoring that can be used by both aircraft and missiles.
- UnfocusedGroupConsiderationScoring (script)¶
script double UnfocusedGroupConsiderationScoring(WsfSA_Group aGroup) end_script
This is an optional script used to measure perceived unfocused group importance, which is used to determine how strongly the group should be considered for maintaining perception. If this function is present, it completely overrides the use of any script functions that try to set bogie/bandit importance or unimportance. This is only useful when max_threat_load is defined, otherwise no limit will be imposed and importance is not necessary. Values returned by the script may be any value (positive or negative), but bogies/bandits presenting negative scores will be discarded from consideration. High scores indicate a greater interest in the bogie/bandit, as compared to others.
This is used along with BogieBanditConsiderationScoring (above), in that the score of an unfocused group is compared with the scores of bandits to determine whether the group that includes the bandit becomes unfocused, or the unfocused group is removed from perception.
- CreatePerceivedItemPruningArray (script)¶
script Array<WsfSA_PerceivedItem> CreatePerceivedItemPruningArray(Array<WsfSA_PerceivedItem> aThreatItems) end_script
This is an optional script used to override the default behavior to keep the number of perceived items within max_threat_load.
aThreatItems is the current list of all recognized groups, plus any newly considered entities. This list is sorted by increasing consideration score.
The script should return an array containing all perceived items which need to be dropped in order to keep within the perceived item limit.
It is the user’s responsibility to ensure that their custom pruning function guarantees that the perceived item limit is maintained.
The SAP’s internal list of perceived items isn’t updated until after this script returns. Use WsfSA_Processor.CalculatePerceivedItemCount(aThreatItems) to check the number of perceived items.
- Default: If no user defined script is present:
While the number of PIs exceeds the limit, choose the focused, unimportant, non-focus-protected group with the least consideration score, and unfocus it.
While the number of PIs still exceeds the limit, choose the entity or unfocused, unimportant, non-element-protected group with the least consideration score, and drop it.
If the number of PIs still exceeds the limit, repeat steps 1 and 2, but ignore focus and element protection.
If the number of PIs still exceeds the limit, repeat steps 1 and 2, but ignore importance.
If the number of PIs still exceeds the limit, repeat steps 1 and 2, but ignore importance and focus and element protection.
- CalculateRisk (script)¶
script double CalculateRisk() end_script
This is an optional script used to calculate the overall operational/tactical risk as assessed by the WSF_SA_PROCESSOR. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
Default: If no user defined script is present, the risk is computed as the highest risk posed by any bogie or bandit in the perceived bogies list and bandits list.
- CalculateSelfRisk (script)¶
script double CalculateSelfRisk() end_script
This is an optional script used to calculate the operational/tactical “self-risk” as assessed by the WSF_SA_PROCESSOR, considering only the risk faced by this platform. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
Default: If no user defined script is present, the self-risk is computed as the highest risk posed by any bogie or bandit in the perceived bogies list and bandits list.
- CalculateFlightRisk (script)¶
script double CalculateFlightRisk() end_script
This is an optional script used to calculate the operational/tactical “flight risk” as assessed by the WSF_SA_PROCESSOR, considering the risk that the flight of aircraft (often two or four aircraft) is facing. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
Default: If no user defined script is present, the flight risk is computed as the highest risk posed by any bogie or bandit in the perceived bogies list and bandits list.
- CalculatePackageRisk (script)¶
script double CalculatePackageRisk() end_script
This is an optional script used to calculate the operational/tactical “package risk” as assessed by the WSF_SA_PROCESSOR, considering the risk that the package of aircraft (often multiple flights of aircraft) is facing. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
Default: If no user defined script is present, the package risk is computed as the highest risk posed by any bogie or bandit in the perceived bogies list and bandits list.
- CalculateMissionRisk (script)¶
script double CalculateMissionRisk() end_script
This is an optional script used to calculate the operational/tactical “mission risk” as assessed by the WSF_SA_PROCESSOR, considering the risk(s) that might prevent the success of the current mission. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
Default: If no user defined script is present, the mission risk is computed as the highest risk posed by any bogie or bandit in the perceived bogies list and bandits list.
- CalculateDefensiveness (script)¶
script double CalculateDefensiveness() end_script
This is an optional script used to calculate the degree of defensiveness that the platform has assessed for the current operational/tactical situation as assessed by the WSF_SA_PROCESSOR. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
Default: If no user defined script is present, the defensiveness is computed as the highest defensiveness posed by any bogie or bandit.
- CalculateUrgency (script)¶
script double CalculateUrgency() end_script
This is an optional script used to calculate the sense of urgency imposed by the operational/tactical situation as assessed by the WSF_SA_PROCESSOR. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
Default: If no user defined script is present, the urgency is computed as the highest urgency posed by any bogie or bandit.
- CalculateWeaponSupport (script)¶
script bool CalculateWeaponSupport() end_script
This is an optional script used to calculate if a weapon is being supported (i.e., is being provided track update information by the parent platform). If a weapon is being supported, it should return true. There is no default implementation for weapon support, so if this function is omitted, the weapon support condition will always be false.
- CalculateThreatLevel (script)¶
script double CalculateThreatLevel(WsfSA_EntityPerception aThreat, bool aIsBogie) end_script
This is an optional script used to calculate the threat level presented by the specified bogie/bandit (aThreat). The boolean (aIsBogie) should be true if the threat is a bogie and false if the threat is a bandit. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
- CalculateMissileThreatLevel (script)¶
script double CalculateMissileThreatLevel(WsfSA_EntityPerception aThreat, bool aIsBogie) end_script
This is an optional script used to calculate the threat level presented by the specified missile bogie/bandit (aThreat). The boolean (aIsBogie) should be true if the threat is a bogie and false if the threat is a bandit. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation. This is used with CalculateThreatLevel, where CalculateMissileThreatLevel is used for perceived missiles, while CalculateThreatLevel is used for aircraft (and even missiles that are not yet perceived as missiles).
- CalculateGroupThreatLevel (script)¶
script double CalculateGroupThreatLevel(WsfSA_Group aThreat, bool aIsBogie) end_script
This is an optional script used to calculate the threat level presented by the specified unfocused group of bogies/bandits (aThreat). The boolean (aIsBogie) should be true if the threat is a bogie and false if the threat is a bandit. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation. This is used with CalculateThreatLevel, where CalculateGroupThreatLevel is used for perceived unfocused groups, while CalculateThreatLevel is used for aircraft (and even missiles that are not yet perceived as missiles).
- CalculateTargetValue (script)¶
script double CalculateTargetValue(WsfSA_EntityPerception aTarget, bool aIsBogie) end_script
This is an optional script used to calculate the target value offered by the specified bogie/bandit (aTarget). The boolean (aIsBogie) should be true if the target is a bogie and false if the target is a bandit. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
- CalculateMissileTargetValue (script)¶
script double CalculateMissileTargetValue(WsfSA_EntityPerception aTarget, bool aIsBogie) end_script
This is an optional script used to calculate the target value offered by the specified missile bogie/bandit (aTarget). The boolean (aIsBogie) should be true if the target is a bogie and false if the target is a bandit. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation. This is used with CalculateTargetValue, where CalculateMissileTargetValue is used for perceived missiles, while CalculateTargetValue is used for aircraft (and even missiles that are not yet perceived as missiles).
- CalculateGroupTargetValue (script)¶
script double CalculateGroupTargetValue(WsfSA_Group aTarget, bool aIsBogie) end_script
This is an optional script used to calculate the target value offered by the specified unfocused group of bogies/bandits (aTarget). The boolean (aIsBogie) should be true if the target is a bogie and false if the target is a bandit. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation. This is used with CalculateTargetValue, where CalculateGroupTargetValue is used for unfocused groups, while CalculateTargetValue is used for aircraft (and even missiles that are not yet perceived as missiles).
- CalculateRiskPosedByEntity (script)¶
script double CalculateRiskPosedByEntity(WsfSA_EntityPerception aEntity) end_script
This is an optional script used to calculate the risk posed by the specified bogie/bandit entity. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
- CalculateDefensivenessInducedByEntity (script)¶
script double CalculateDefensivenessInducedByEntity(WsfSA_EntityPerception aEntity) end_script
This is an optional script used to calculate the degree of defensiveness induced by the specified bogie/bandit entity. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
- CalculateUrgencyInducedByEntity (script)¶
script double CalculateUrgencyInducedByEntity(WsfSA_EntityPerception aEntity) end_script
This is an optional script used to calculate the sense of urgency induced by the specified bogie/bandit entity. This should return a normalized value between 0.0 and 1.0. This optional script will override the default calculation.
- ProjectPositionInTime (script)¶
script WsfGeoPoint ProjectPositionInTime(double aSimTime, WsfSA_EntityPerception aEntity) end_script
This is an optional script used to estimate a future location for an entity. This should return a valid WsfGeoPoint. This script will override the default calculation.
- ProjectPositionForward (script)¶
script WsfGeoPoint ProjectPositionForward(double aSimTime, WsfSA_EntityPerception aEntity) end_script
This is an optional script used to estimate a future location for an entity, assuming forward motion. This should return a valid WsfGeoPoint. This script will override the default calculation.
- ProjectPositionLevelTurnLeft (script)¶
script WsfGeoPoint ProjectPositionLevelTurnLeft(double aSimTime, WsfSA_EntityPerception aEntity, double aGees) end_script
This is an optional script used to estimate a future location for an entity, assuming it carries out a constant-g turn to its left. This should return a valid WsfGeoPoint. This script will override the default calculation.
- ProjectPositionLevelTurnRight (script)¶
script WsfGeoPoint ProjectPositionLevelTurnRight(double aSimTime, WsfSA_EntityPerception aEntity, double aGees) end_script
This is an optional script used to estimate a future location for an entity, assuming it carries out a g-limited level turn to its right. This should return a valid WsfGeoPoint. This script will override the default calculation.
- ProjectPositionTurnToHeading (script)¶
script WsfGeoPoint ProjectPositionTurnToHeading(double aSimTime, WsfSA_EntityPerception aEntity, double aHeading_deg, double aGees) end_script
This is an optional script used to estimate a future location for an entity, assuming it carries out a g-limited level turn to the provided heading. This should return a valid WsfGeoPoint. This optional script will override the default calculation.
- ProjectPositionGoToPoint (script)¶
script WsfGeoPoint ProjectPositionGoToPoint(double aSimTime, WsfSA_EntityPerception aEntity, WsfGeoPoint aPointOfInterest, double aGees) end_script
This is an optional script used to estimate a future location for an entity, assuming it carries out a g-limited level turn toward the provided location. This should return a valid WsfGeoPoint. This optional script will override the default calculation.
- ProjectPositionSlice (script)¶
script WsfGeoPoint ProjectPositionSlice(double aSimTime, WsfSA_EntityPerception aEntity, double aRollAngle, double aGees) end_script
This is an optional script used to estimate a future location for an entity, assuming it carries out a g-limited roll-and-pull maneuver away from its current heading. This should return a valid WsfGeoPoint. This optional script will override the default calculation.
- ProjectPositionSliceToHeading (script)¶
script WsfGeoPoint ProjectPositionSliceToHeading(double aSimTime, WsfSA_EntityPerception aEntity, double aHeading_deg, double aRollAngle, double aGees) end_script
This is an optional script used to estimate a future location for an entity, assuming it carries out a g-limited roll-and-pull maneuver to the provided heading. This should return a valid WsfGeoPoint. This optional script will override the default calculation.
- ProjectPositionSplitS (script)¶
script WsfGeoPoint ProjectPositionSplitS(double aSimTime, WsfSA_EntityPerception aEntity, double aGees) end_script
This is an optional script used to estimate a future location for an entity, assuming it carries out a g-limited split-S maneuver. This should return a valid WsfGeoPoint. This optional script will override the default calculation.
