@@ -628,6 +640,34 @@ The following iterator methods are currently available within the DATABASE:
+
+
+
+-
+
+
+
+DATABASE.COUNTRY_ID
+
+
+-
+
+
+
+
+
+
+-
+
+
+
+DATABASE.COUNTRY_NAME
+
+
+-
+
+
+
diff --git a/docs/Documentation/Detection.html b/docs/Documentation/Detection.html
index 4c3e89eab..43b39e832 100644
--- a/docs/Documentation/Detection.html
+++ b/docs/Documentation/Detection.html
@@ -39,11 +39,11 @@
Fsm
Group
Identifiable
- MOVEMENT
Menu
Message
MissileTrainer
Mission
+ Movement
Object
Point
Positionable
@@ -61,8 +61,8 @@
Static
Task
Task_A2G
+ Task_A2G_Dispatcher
Task_PICKUP
- Task_SEAD
Unit
Utils
Zone
@@ -77,14 +77,17 @@
-
- The Detection#DETECTION_BASE class defines the core functions to administer detected objects.
- The Detection#DETECTION_BASE class will detect objects within the battle zone for a list of Groups detecting targets following (a) detection method(s).
+ # 1) #DETECTION_BASE class, extends Fsm#FSM
- 1.1) DETECTION_BASE constructor
- Construct a new DETECTION_BASE instance using the Detection#DETECTION_BASE.New() method.
+ The #DETECTION_BASE class defines the core functions to administer detected objects.
+ The #DETECTION_BASE class will detect objects within the battle zone for a list of Groups detecting targets following (a) detection method(s).
+
+ ## 1.1) DETECTION_BASE constructor
+
+ Construct a new DETECTION_BASE instance using the DETECTION_BASE.New() method.
+
+ ## 1.2) DETECTION_BASE initialization
- 1.2) DETECTION_BASE initialization
By default, detection will return detected objects with all the detection sensors available.
However, you can ask how the objects were found with specific detection methods.
If you use one of the below methods, the detection will work with the detection method specified.
@@ -93,55 +96,246 @@
Use the following functions to report the objects it detected using the methods Visual, Optical, Radar, IRST, RWR, DLINK:
- 1.3) Obtain objects detected by DETECTION_BASE
- DETECTION_BASE builds Sets of objects detected. These Set#SET_BASEs can be retrieved using the method Detection#DETECTION_BASE.GetDetectedSets().
- The method will return a list (table) of Set#SET_BASE objects.
+ ## 1.3) DETECTION_BASE derived classes group the detected units into a DetectedItems[] list
+
+ DETECTIONBASE derived classes build a list called DetectedItems[], which is essentially a first later
+ of grouping of detected units. Each DetectedItem within the DetectedItems[] list contains
+ a SETUNIT object that contains the detected units that belong to that group.
+
+ Derived classes will apply different methods to group the detected units.
+ Examples are per area, per quadrant, per distance, per type.
+ See further the derived DETECTION classes on which grouping methods are currently supported.
+
+ Various methods exist how to retrieve the grouped items from a DETECTION_BASE derived class:
+
+
+ - The method Detection#DETECTION_BASE.GetDetectedItems() retrieves the DetectedItems[] list.
+ - A DetectedItem from the DetectedItems[] list can be retrieved using the method Detection#DETECTION_BASE.GetDetectedItem( DetectedItemIndex ).
+ Note that this method returns a DetectedItem element from the list, that contains a Set variable and further information
+ about the DetectedItem that is set by the DETECTION_BASE derived classes, used to group the DetectedItem.
+ - A DetectedSet from the DetectedItems[] list can be retrieved using the method Detection#DETECTION_BASE.GetDetectedSet( DetectedItemIndex ).
+ This method retrieves the Set from a DetectedItem element from the DetectedItem list (DetectedItems[ DetectedItemIndex ].Set ).
+
+
+ ## 1.4) Apply additional Filters to fine-tune the detected objects
+
+ By default, DCS World will return any object that is in LOS and within "visual reach", or detectable through one of the electronic detection means.
+ That being said, the DCS World detection algorithm can sometimes be unrealistic.
+ Especially for a visual detection, DCS World is able to report within 1 second a detailed detection of a group of 20 units (including types of the units) that are 10 kilometers away, using only visual capabilities.
+ Additionally, trees and other obstacles are not accounted during the DCS World detection.
+
+ Therefore, an additional (optional) filtering has been built into the DETECTION_BASE class, that can be set for visual detected units.
+ For electronic detection, this filtering is not applied, only for visually detected targets.
+
+ The following additional filtering can be applied for visual filtering:
+
+
+ - A probability factor per kilometer distance.
+ - A probability factor based on the alpha angle between the detected object and the unit detecting.
+ A detection from a higher altitude allows for better detection than when on the ground.
+ - Define a probability factor for "cloudy zones", which are zones where forests or villages are located. In these zones, detection will be much more difficult.
+ The mission designer needs to define these cloudy zones within the mission, and needs to register these zones in the DETECTION_ objects additing a probability factor per zone.
+
+
+ I advise however, that, when you first use the DETECTION derived classes, that you don't use these filters.
+ Only when you experience unrealistic behaviour in your missions, these filters could be applied.
+
+ ### 1.4.1 ) Distance visual detection probability
+
+ Upon a visual detection, the further away a detected object is, the less likely it is to be detected properly.
+ Also, the speed of accurate detection plays a role.
+
+ A distance probability factor between 0 and 1 can be given, that will model a linear extrapolated probability over 10 km distance.
+
+ For example, if a probability factor of 0.6 (60%) is given, the extrapolated probabilities over 15 kilometers would like like:
+ 1 km: 96%, 2 km: 92%, 3 km: 88%, 4 km: 84%, 5 km: 80%, 6 km: 76%, 7 km: 72%, 8 km: 68%, 9 km: 64%, 10 km: 60%, 11 km: 56%, 12 km: 52%, 13 km: 48%, 14 km: 44%, 15 km: 40%.
+
+ Note that based on this probability factor, not only the detection but also the type of the unit will be applied!
+
+ Use the method Detection#DETECTION_BASE.SetDistanceProbability() to set the probability factor upon a 10 km distance.
+
+ ### 1.4.2 ) Alpha Angle visual detection probability
+
+ Upon a visual detection, the higher the unit is during the detecting process, the more likely the detected unit is to be detected properly.
+ A detection at a 90% alpha angle is the most optimal, a detection at 10% is less and a detection at 0% is less likely to be correct.
+
+ A probability factor between 0 and 1 can be given, that will model a progressive extrapolated probability if the target would be detected at a 0° angle.
+
+ For example, if a alpha angle probability factor of 0.7 is given, the extrapolated probabilities of the different angles would look like:
+ 0°: 70%, 10°: 75,21%, 20°: 80,26%, 30°: 85%, 40°: 89,28%, 50°: 92,98%, 60°: 95,98%, 70°: 98,19%, 80°: 99,54%, 90°: 100%
+
+ Use the method Detection#DETECTION_BASE.SetAlphaAngleProbability() to set the probability factor if 0°.
+
+ ### 1.4.3 ) Cloudy Zones detection probability
+
+ Upon a visual detection, the more a detected unit is within a cloudy zone, the less likely the detected unit is to be detected successfully.
+ The Cloudy Zones work with the ZONE_BASE derived classes. The mission designer can define within the mission
+ zones that reflect cloudy areas where detected units may not be so easily visually detected.
+
+ Use the method Detection#DETECTION_BASE.SetZoneProbability() to set for a defined number of zones, the probability factors.
+
+ Note however, that the more zones are defined to be "cloudy" within a detection, the more performance it will take
+ from the DETECTIONBASE to calculate the presence of the detected unit within each zone.
+ Expecially for ZONEPOLYGON, try to limit the amount of nodes of the polygon!
+
+ Typically, this kind of filter would be applied for very specific areas were a detection needs to be very realisting for
+ AI not to detect so easily targets within a forrest or village rich area.
+
+ ## 1.5 ) Accept / Reject detected units
+
+ DETECTION_BASE can accept or reject successful detections based on the location of the detected object,
+ if it is located in range or located inside or outside of specific zones.
+
+ ### 1.5.1 ) Detection acceptance of within range limit
+
+ A range can be set that will limit a successful detection for a unit.
+ Use the method Detection#DETECTION_BASE.SetAcceptRange() to apply a range in meters till where detected units will be accepted.
+
+ local SetGroup = SET_GROUP:New():FilterPrefixes( "FAC" ):FilterStart() -- Build a SetGroup of Forward Air Controllers.
+
+ -- Build a detect object.
+ local Detection = DETECTION_BASE:New( SetGroup )
+
+ -- This will accept detected units if the range is below 5000 meters.
+ Detection:SetAcceptRange( 5000 )
+
+ -- Start the Detection.
+ Detection:Start()
+
+
+
+ ### 1.5.2 ) Detection acceptance if within zone(s).
+
+ Specific ZONEBASE object(s) can be given as a parameter, which will only accept a detection if the unit is within the specified ZONEBASE object(s).
+ Use the method Detection#DETECTION_BASE.SetAcceptZones() will accept detected units if they are within the specified zones.
+
+ local SetGroup = SET_GROUP:New():FilterPrefixes( "FAC" ):FilterStart() -- Build a SetGroup of Forward Air Controllers.
+
+ -- Search fo the zones where units are to be accepted.
+ local ZoneAccept1 = ZONE:New( "AcceptZone1" )
+ local ZoneAccept2 = ZONE:New( "AcceptZone2" )
+
+ -- Build a detect object.
+ local Detection = DETECTION_BASE:New( SetGroup )
+
+ -- This will accept detected units by Detection when the unit is within ZoneAccept1 OR ZoneAccept2.
+ Detection:SetAcceptZones( { ZoneAccept1, ZoneAccept2 } )
+
+ -- Start the Detection.
+ Detection:Start()
+
+
+ ### 1.5.3 ) Detection rejectance if within zone(s).
+
+ Specific ZONEBASE object(s) can be given as a parameter, which will reject detection if the unit is within the specified ZONEBASE object(s).
+ Use the method Detection#DETECTION_BASE.SetRejectZones() will reject detected units if they are within the specified zones.
+ An example of how to use the method is shown below.
+
+ local SetGroup = SET_GROUP:New():FilterPrefixes( "FAC" ):FilterStart() -- Build a SetGroup of Forward Air Controllers.
+
+ -- Search fo the zones where units are to be rejected.
+ local ZoneReject1 = ZONE:New( "RejectZone1" )
+ local ZoneReject2 = ZONE:New( "RejectZone2" )
+
+ -- Build a detect object.
+ local Detection = DETECTION_BASE:New( SetGroup )
+
+ -- This will reject detected units by Detection when the unit is within ZoneReject1 OR ZoneReject2.
+ Detection:SetRejectZones( { ZoneReject1, ZoneReject2 } )
+
+ -- Start the Detection.
+ Detection:Start()
+
+
+ ## 1.6) DETECTION_BASE is a Finite State Machine
+
+ Various Events and State Transitions can be tailored using DETECTION_BASE.
+
+ ### 1.6.1) DETECTION_BASE States
+
+
+ - Detecting: The detection is running.
+ - Stopped: The detection is stopped.
+
+
+ ### 1.6.2) DETECTION_BASE Events
+
+
+ - Start: Start the detection process.
+ - Detect: Detect new units.
+ - Detected: New units have been detected.
+ - Stop: Stop the detection process.
+
-
+ # 2) Detection#DETECTION_UNITS class, extends Detection#DETECTION_BASE
+
+ The Detection#DETECTION_UNITS class will detect units within the battle zone.
+ It will build a DetectedItems list filled with DetectedItems. Each DetectedItem will contain a field Set, which contains a Set#SET_UNIT containing ONE UNIT object reference.
+ Beware that when the amount of units detected is large, the DetectedItems list will be large also.
+
+ # 3) Detection#DETECTION_TYPES class, extends Detection#DETECTION_BASE
+
+ The Detection#DETECTION_TYPES class will detect units within the battle zone.
+ It will build a DetectedItems[] list filled with DetectedItems, grouped by the type of units detected.
+ Each DetectedItem will contain a field Set, which contains a Set#SET_UNIT containing ONE UNIT object reference.
+ Beware that when the amount of different types detected is large, the DetectedItems[] list will be large also.
+
+ # 4) Detection#DETECTION_AREAS class, extends Detection#DETECTION_BASE
+
The Detection#DETECTION_AREAS class will detect units within the battle zone for a list of Groups detecting targets following (a) detection method(s),
and will build a list (table) of Set#SET_UNITs containing the Unit#UNITs detected.
The class is group the detected units within zones given a DetectedZoneRange parameter.
A set with multiple detected zones will be created as there are groups of units detected.
- 2.1) Retrieve the Detected Unit sets and Detected Zones
- The DetectedUnitSets methods are implemented in Detection#DECTECTION_BASE and the DetectedZones methods is implemented in Detection#DETECTION_AREAS.
+ ## 4.1) Retrieve the Detected Unit Sets and Detected Zones
- Retrieve the DetectedUnitSets with the method Detection#DETECTION_BASE.GetDetectedSets(). A table will be return of Set#SET_UNITs.
- To understand the amount of sets created, use the method Detection#DETECTION_BASE.GetDetectedSetCount().
- If you want to obtain a specific set from the DetectedSets, use the method Detection#DETECTION_BASE.GetDetectedSet() with a given index.
+ The methods to manage the DetectedItems[].Set(s) are implemented in Detection#DECTECTION_BASE and
+ the methods to manage the DetectedItems[].Zone(s) is implemented in Detection#DETECTION_AREAS.
+
+ Retrieve the DetectedItems[].Set with the method Detection#DETECTION_BASE.GetDetectedSet(). A Set#SET_UNIT object will be returned.
Retrieve the formed Zones as a result of the grouping the detected units within the DetectionZoneRange, use the method Detection#DETECTION_BASE.GetDetectionZones().
To understand the amount of zones created, use the method Detection#DETECTION_BASE.GetDetectionZoneCount().
If you want to obtain a specific zone from the DetectedZones, use the method Detection#DETECTION_BASE.GetDetectionZone() with a given index.
- 1.4) Flare or Smoke detected units
+ ## 4.4) Flare or Smoke detected units
+
Use the methods Detection#DETECTION_AREAS.FlareDetectedUnits() or Detection#DETECTION_AREAS.SmokeDetectedUnits() to flare or smoke the detected units when a new detection has taken place.
- 1.5) Flare or Smoke detected zones
- Use the methods Detection#DETECTION_AREAS.FlareDetectedZones() or Detection#DETECTION_AREAS.SmokeDetectedZones() to flare or smoke the detected zones when a new detection has taken place.
+ ## 4.5) Flare or Smoke or Bound detected zones
+
+ Use the methods:
+
+
+
+ the detected zones when a new detection has taken place.
### Contributions:
- - Mechanist : Concept & Testing
+ - Mechanist : Early concept of DETECTION_AREAS.
### Authors:
- - FlightControl : Design & Programming
+
- FlightControl : Analysis, Design, Programming, Testing
@@ -157,39 +351,33 @@
DETECTION_BASE |
+ |
+
+
+ | DETECTION_BASE:AcceptChanges(DetectedItem) |
+
+ Accepts changes from the detected item.
+ |
+
+
+ | DETECTION_BASE.AcceptRange |
+
+
+ |
+
+
+ | DETECTION_BASE.AcceptZones |
+
+
+ |
+
+
+ | DETECTION_BASE:AddChangeItem(DetectedItem, ChangeCode, ItemUnitType) |
+
+ Add a change to the detected zone.
+ |
+
+
+ | DETECTION_BASE:AddChangeUnit(DetectedItem, ChangeCode, ChangeUnitType) |
+
+ Add a change to the detected zone.
+ |
+
+
+ | DETECTION_BASE:AddDetectedItem(DetectedItemIndex, Set) |
+
+ Adds a new DetectedItem to the DetectedItems list.
+ |
+
+
+ | DETECTION_BASE:AddDetectedItemZone(DetectedItemIndex, Set, Zone) |
+
+ Adds a new DetectedItem to the DetectedItems list.
+ |
+
+
+ | DETECTION_BASE.AlphaAngleProbability |
+
+
+ |
+
+
| DETECTION_BASE.ClassName |
+ |
+
+
+ | DETECTION_BASE.CountryID |
+
+
|
| DETECTION_BASE:CreateDetectionSets() |
Make a DetectionSet table.
+ |
+
+
+ | DETECTION_BASE:Detect() |
+
+ Synchronous Event Trigger for Event Detect.
|
@@ -432,6 +604,36 @@
| DETECTION_BASE.DetectVisual |
+ |
+
+
+ | DETECTION_BASE:Detected() |
+
+ Synchronous Event Trigger for Event Detected.
+ |
+
+
+ | DETECTION_BASE.DetectedItemCount |
+
+
+ |
+
+
+ | DETECTION_BASE.DetectedItemMax |
+
+
+ |
+
+
+ | DETECTION_BASE:DetectedItemReportSummary(Index) |
+
+ Report summary of a detected item using a given numeric index.
+ |
+
+
+ | DETECTION_BASE.DetectedItems |
+
+
|
@@ -444,6 +646,24 @@
| DETECTION_BASE.DetectedObjectsIdentified |
Map of the DetectedObjects identified.
+ |
+
+
+ | DETECTION_BASE:DetectedReportDetailed() |
+
+ Report detailed of a detectedion result.
+ |
+
+
+ | DETECTION_BASE.DetectionCount |
+
+
+ |
+
+
+ | DETECTION_BASE.DetectionInterval |
+
+
|
@@ -468,6 +688,30 @@
| DETECTION_BASE.DetectionSetGroup |
The Set of GROUPs in the Forward Air Controller role.
+ |
+
+
+ | DETECTION_BASE.DistanceProbability |
+
+
+ |
+
+
+ | DETECTION_BASE:GetDetectedItem(Index) |
+
+ Get a detected item using a given numeric index.
+ |
+
+
+ | DETECTION_BASE:GetDetectedItems() |
+
+ Get the detected Set#SET_BASEs.
+ |
+
+
+ | DETECTION_BASE:GetDetectedItemsCount() |
+
+ Get the amount of SETs with detected objects.
|
@@ -479,19 +723,13 @@
| DETECTION_BASE:GetDetectedSet(Index) |
- Get a SET of detected objects using a given numeric index.
+Get the Set#SET_UNIT of a detecttion area using a given numeric index.
|
- | DETECTION_BASE:GetDetectedSetCount() |
+ DETECTION_BASE:GetDetectedZone(Index) |
- Get the amount of SETs with detected objects.
- |
-
-
- | DETECTION_BASE:GetDetectedSets() |
-
- Get the detected Set#SET_BASEs.
+Get the Zone#ZONE_UNIT of a detection area using a given numeric index.
|
@@ -549,9 +787,105 @@
- | DETECTION_BASE:New(DetectionSetGroup, DetectionRange) |
+ DETECTION_BASE:IsFriendliesNearBy(DetectedItem) |
+
+ Returns if there are friendlies nearby the FAC units ...
+ |
+
+
+ | DETECTION_BASE:New(DetectionSetGroup) |
DETECTION constructor.
+ |
+
+
+ | DETECTION_BASE:OnAfterDetect(From, Event, To) |
+
+ OnAfter Transition Handler for Event Detect.
+ |
+
+
+ | DETECTION_BASE:OnAfterDetected(From, Event, To) |
+
+ OnAfter Transition Handler for Event Detected.
+ |
+
+
+ | DETECTION_BASE:OnAfterStart(From, Event, To) |
+
+ OnAfter Transition Handler for Event Start.
+ |
+
+
+ | DETECTION_BASE:OnAfterStop(From, Event, To) |
+
+ OnAfter Transition Handler for Event Stop.
+ |
+
+
+ | DETECTION_BASE:OnBeforeDetect(From, Event, To) |
+
+ OnBefore Transition Handler for Event Detect.
+ |
+
+
+ | DETECTION_BASE:OnBeforeDetected(From, Event, To) |
+
+ OnBefore Transition Handler for Event Detected.
+ |
+
+
+ | DETECTION_BASE:OnBeforeStart(From, Event, To) |
+
+ OnBefore Transition Handler for Event Start.
+ |
+
+
+ | DETECTION_BASE:OnBeforeStop(From, Event, To) |
+
+ OnBefore Transition Handler for Event Stop.
+ |
+
+
+ | DETECTION_BASE:OnEnterDetecting(From, Event, To) |
+
+ OnEnter Transition Handler for State Detecting.
+ |
+
+
+ | DETECTION_BASE:OnEnterStopped(From, Event, To) |
+
+ OnEnter Transition Handler for State Stopped.
+ |
+
+
+ | DETECTION_BASE:OnLeaveDetecting(From, Event, To) |
+
+ OnLeave Transition Handler for State Detecting.
+ |
+
+
+ | DETECTION_BASE:OnLeaveStopped(From, Event, To) |
+
+ OnLeave Transition Handler for State Stopped.
+ |
+
+
+ | DETECTION_BASE.RejectZones |
+
+
+ |
+
+
+ | DETECTION_BASE:RemoveDetectedItem(DetectedItemIndex) |
+
+ Removes an existing DetectedItem from the DetectedItems list.
+ |
+
+
+ | DETECTION_BASE:ReportFriendliesNearBy(ReportGroupData) |
+
+ Background worker function to determine if there are friendlies nearby ...
|
@@ -570,6 +904,60 @@
| DETECTION_BASE.ScheduleRepeatInterval |
+ |
+
+
+ | DETECTION_BASE:SetAcceptRange(AcceptRange) |
+
+ Accept detections if within a range in meters.
+ |
+
+
+ | DETECTION_BASE:SetAcceptZones(AcceptZones) |
+
+ Accept detections if within the specified zone(s).
+ |
+
+
+ | DETECTION_BASE:SetAlphaAngleProbability(AlphaAngleProbability) |
+
+ Upon a visual detection, the higher the unit is during the detecting process, the more likely the detected unit is to be detected properly.
+ |
+
+
+ | DETECTION_BASE:SetDetectionInterval(DetectionInterval) |
+
+ Set the detection interval time in seconds.
+ |
+
+
+ | DETECTION_BASE:SetDistanceProbability(DistanceProbability) |
+
+ Upon a visual detection, the further away a detected object is, the less likely it is to be detected properly.
+ |
+
+
+ | DETECTION_BASE:SetRejectZones(RejectZones) |
+
+ Reject detections if within the specified zone(s).
+ |
+
+
+ | DETECTION_BASE:SetZoneProbability(ZoneArray) |
+
+ Upon a visual detection, the more a detected unit is within a cloudy zone, the less likely the detected unit is to be detected successfully.
+ |
+
+
+ | DETECTION_BASE:Start() |
+
+ Synchronous Event Trigger for Event Start.
+ |
+
+
+ | DETECTION_BASE:Stop() |
+
+ Synchronous Event Trigger for Event Stop.
|
@@ -585,9 +973,103 @@
- | DETECTION_BASE:_DetectionScheduler(SchedulerName) |
+ DETECTION_BASE.ZoneProbability |
- Form Sets of detected Unit#UNITs in an array of Set#SET_BASEs.
+
+ |
+
+
+ | DETECTION_BASE:__Detect(Delay) |
+
+ Asynchronous Event Trigger for Event Detect.
+ |
+
+
+ | DETECTION_BASE:__Detected(Delay) |
+
+ Asynchronous Event Trigger for Event Detected.
+ |
+
+
+ | DETECTION_BASE:__Start(Delay) |
+
+ Asynchronous Event Trigger for Event Start.
+ |
+
+
+ | DETECTION_BASE:__Stop(Delay) |
+
+ Asynchronous Event Trigger for Event Stop.
+ |
+
+
+ | DETECTION_BASE:onafterDetect(From, Event, To) |
+
+
+ |
+
+
+ | DETECTION_BASE:onafterDetectionGroup(From, Event, To, DetectionGroup) |
+
+
+ |
+
+
+ | DETECTION_BASE:onafterStart(From, Event, To) |
+
+
+ |
+
+
+
+ 
