FlightControl-Master/MOOSE
1
0
Fork 0
mirror of https://github.com/FlightControl-Master/MOOSE.git synced 2025-10-29 16:58:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Implemented :FilterCategories() method for DETECTION_ classes fixing issue #415

Browse Source 
--  Added:FilterCategories() method to DETECTION_BASE.
-- Reviewed documentation
-- Added documentation for FilterCategories method
-- Default detection methods are all ON. (They were only set to visual).
-- Created test missions. DET-30x
This commit is contained in:
FlightControl 2017-04-12 09:00:00 +02:00
parent 86fd99f356
commit d7f1a74caf
4 changed files with 492 additions and 271 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Moose Development/Moose/Core/Base.lua
View File

@ -219,9 +219,9 @@ local _ClassID = 0
BASE = {
ClassName = "BASE",
ClassID = 0,
_Private = {},
Events = {},
States = {}
States = {},
_ = {},
}
--- The Formation Class
@ -360,7 +360,7 @@ do -- Event Handling
-- @param #BASE self
-- @return #number The @{Event} processing Priority.
function BASE:GetEventPriority()
return self._Private.EventPriority or 5
return self._.EventPriority or 5
end
--- Set the Class @{Event} processing Priority.
@ -370,7 +370,7 @@ do -- Event Handling
-- @param #number EventPriority The @{Event} processing Priority.
-- @return self
function BASE:SetEventPriority( EventPriority )
self._Private.EventPriority = EventPriority
self._.EventPriority = EventPriority
end
--- Remove all subscribed events

175
Moose Development/Moose/Functional/Detection.lua
View File

@ -7,8 +7,25 @@
-- DETECTION classes facilitate the detection of enemy units within the battle zone executed by FACs (Forward Air Controllers) or RECCEs (Reconnassance Units).
-- DETECTION uses the in-built detection capabilities of DCS World, but adds new functionalities.
--
-- Please watch this [youtube video](https://youtu.be/C7p81dUwP-E) that explains the detection concepts.
-- Find the DETECTION classes documentation further in this document in the globals section.
--
-- ====
--
-- # Demo Missions
--
-- ### [DETECTION Demo Missions and Source Code](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master-release/DET%20-%20Detection)
--
-- ### [DETECTION Demo Missions, only for Beta Testers](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/DET%20-%20Detection)
--
-- ### [ALL Demo Missions pack of the Latest Release](https://github.com/FlightControl-Master/MOOSE_MISSIONS/releases)
--
-- ====
--
-- # YouTube Channel
--
-- ### [DETECTION YouTube Channel](https://www.youtube.com/playlist?list=PL7ZUrU4zZUl3Cf5jpI6BS0sBOVWK__tji)
--
-- ====
--
-- ### Contributions:
--
@ -23,16 +40,24 @@
do -- DETECTION_BASE
--- # 1) DETECTION_BASE class, extends @{Fsm#FSM}
--- @type DETECTION_BASE
-- @field Core.Set#SET_GROUP DetectionSetGroup The @{Set} of GROUPs in the Forward Air Controller role.
-- @field Dcs.DCSTypes#Distance DetectionRange The range till which targets are accepted to be detected.
-- @field #DETECTION_BASE.DetectedObjects DetectedObjects The list of detected objects.
-- @field #table DetectedObjectsIdentified Map of the DetectedObjects identified.
-- @field #number DetectionRun
-- @extends Core.Fsm#FSM
--- DETECTION_BASE class, extends @{Fsm#FSM}
--
-- 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 @{Group}s detecting targets following (a) detection method(s).
--
-- ## 1.1) DETECTION_BASE constructor
-- ## DETECTION_BASE constructor
--
-- Construct a new DETECTION_BASE instance using the @{#DETECTION_BASE.New}() method.
--
-- ## 1.2) DETECTION_BASE initialization
-- ## 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.
@ -48,7 +73,29 @@ do -- DETECTION_BASE
-- * @{#DETECTION_BASE.InitDetectRWR}(): Detected using RWR.
-- * @{#DETECTION_BASE.InitDetectDLINK}(): Detected using DLINK.
--
-- ## 1.3) DETECTION_BASE derived classes group the detected units into a DetectedItems[] list
-- ## **Filter** detected units based on **category of the unit**
--
-- Filter the detected units based on Unit.Category using the method @{#DETECTION_BASE.FilterCategories}().
-- The different values of Unit.Category can be:
--
-- * Unit.Category.AIRPLANE
-- * Unit.Category.GROUND_UNIT
-- * Unit.Category.HELICOPTER
-- * Unit.Category.SHIP
-- * Unit.Category.STRUCTURE
--
-- Multiple Unit.Category entries can be given as a table and then these will be evaluated as an OR expression.
--
-- Example to filter a single category (Unit.Category.AIRPLANE).
--
-- DetectionObject:FilterCategories( Unit.Category.AIRPLANE )
--
-- Example to filter multiple categories (Unit.Category.AIRPLANE, Unit.Category.HELICOPTER). Note the {}.
--
-- DetectionObject:FilterCategories( { Unit.Category.AIRPLANE, Unit.Category.HELICOPTER } )
--
--
-- ## **DETECTION_ derived classes** group the detected units into a **DetectedItems[]** list
--
-- DETECTION_BASE 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
@ -67,7 +114,7 @@ do -- DETECTION_BASE
-- * 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
-- ## **Visual filters** to fine-tune the probability of 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.
@ -88,7 +135,8 @@ do -- DETECTION_BASE
-- 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
--
-- ### 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.
@ -102,7 +150,7 @@ do -- DETECTION_BASE
--
-- 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
-- ### 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.
@ -114,7 +162,7 @@ do -- DETECTION_BASE
--
-- Use the method @{Detection#DETECTION_BASE.SetAlphaAngleProbability}() to set the probability factor if 0°.
--
-- ### 1.4.3 ) Cloudy Zones detection probability
-- ### 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
@ -129,12 +177,12 @@ do -- DETECTION_BASE
-- 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
-- ## 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
-- ### 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.
@ -151,7 +199,7 @@ do -- DETECTION_BASE
-- Detection:Start()
--
--
-- ### 1.5.2 ) Detection acceptance if within zone(s).
-- ### Detection acceptance if within zone(s).
--
-- Specific ZONE_BASE object(s) can be given as a parameter, which will only accept a detection if the unit is within the specified ZONE_BASE object(s).
-- Use the method @{Detection#DETECTION_BASE.SetAcceptZones}() will accept detected units if they are within the specified zones.
@ -171,7 +219,7 @@ do -- DETECTION_BASE
-- -- Start the Detection.
-- Detection:Start()
--
-- ### 1.5.3 ) Detection rejectance if within zone(s).
-- ### Detection rejectance if within zone(s).
--
-- Specific ZONE_BASE object(s) can be given as a parameter, which will reject detection if the unit is within the specified ZONE_BASE object(s).
-- Use the method @{Detection#DETECTION_BASE.SetRejectZones}() will reject detected units if they are within the specified zones.
@ -192,29 +240,24 @@ do -- DETECTION_BASE
-- -- Start the Detection.
-- Detection:Start()
--
-- ## 1.6) DETECTION_BASE is a Finite State Machine
-- ## DETECTION_BASE is a Finite State Machine
--
-- Various Events and State Transitions can be tailored using DETECTION_BASE.
--
-- ### 1.6.1) DETECTION_BASE States
-- ### DETECTION_BASE States
--
-- * **Detecting**: The detection is running.
-- * **Stopped**: The detection is stopped.
--
-- ### 1.6.2) DETECTION_BASE Events
-- ### DETECTION_BASE Events
--
-- * **Start**: Start the detection process.
-- * **Detect**: Detect new units.
-- * **Detected**: New units have been detected.
-- * **Stop**: Stop the detection process.
--
-- @field #DETECTION_BASE DETECTION_BASE
--
-- @type DETECTION_BASE
-- @field Core.Set#SET_GROUP DetectionSetGroup The @{Set} of GROUPs in the Forward Air Controller role.
-- @field Dcs.DCSTypes#Distance DetectionRange The range till which targets are accepted to be detected.
-- @field #DETECTION_BASE.DetectedObjects DetectedObjects The list of detected objects.
-- @field #table DetectedObjectsIdentified Map of the DetectedObjects identified.
-- @field #number DetectionRun
-- @extends Core.Fsm#FSM
DETECTION_BASE = {
ClassName = "DETECTION_BASE",
DetectionSetGroup = nil,
@ -267,11 +310,19 @@ do -- DETECTION_BASE
self.DetectionInterval = 30
self:InitDetectVisual( true )
self:InitDetectOptical( false )
self:InitDetectRadar( false )
self:InitDetectRWR( false )
self:InitDetectIRST( false )
self:InitDetectDLINK( false )
self:InitDetectOptical( true )
self:InitDetectRadar( true )
self:InitDetectRWR( true )
self:InitDetectIRST( true )
self:InitDetectDLINK( true )
self:FilterCategories( {
Unit.Category.AIRPLANE,
Unit.Category.GROUND_UNIT,
Unit.Category.HELICOPTER,
Unit.Category.SHIP,
Unit.Category.STRUCTURE
} )
-- Create FSM transitions.
@ -498,9 +549,8 @@ do -- DETECTION_BASE
for DetectionObjectID, Detection in pairs( DetectedTargets ) do
local DetectedObject = Detection.object -- Dcs.DCSWrapper.Object#Object
self:T2( DetectedObject )
if DetectedObject and DetectedObject:isExist() and DetectedObject.id_ < 50000000 then
if DetectedObject and DetectedObject:isExist() and DetectedObject.id_ < 50000000 then -- and ( DetectedObject:getCategory() == Object.Category.UNIT or DetectedObject:getCategory() == Object.Category.STATIC ) then
local DetectionAccepted = true
@ -515,10 +565,14 @@ do -- DETECTION_BASE
( DetectedObjectVec3.y - DetectionGroupVec3.y )^2 +
( DetectedObjectVec3.z - DetectionGroupVec3.z )^2
) ^ 0.5 / 1000
local DetectedUnitCategory = DetectedObject:getDesc().category
self:T( { "Detected Target", DetectionGroupName, DetectedObjectName, Distance } )
self:T( { "Detected Target:", DetectionGroupName, DetectedObjectName, Distance, DetectedUnitCategory, DetectedCategory } )
-- Calculate Acceptance
DetectionAccepted = self._.FilterCategories[DetectedUnitCategory] ~= nil and DetectionAccepted or false
if self.AcceptRange and Distance > self.AcceptRange then
DetectionAccepted = false
@ -625,10 +679,10 @@ do -- DETECTION_BASE
end
if self.DetectionCount > 0 and self.DetectionRun == self.DetectionCount then
self:__Detect( self.DetectionInterval )
self:T( "--> Create Detection Sets" )
self:CreateDetectionSets()
self:__Detect( self.DetectionInterval )
end
end
@ -645,6 +699,8 @@ do -- DETECTION_BASE
function DETECTION_BASE:InitDetectVisual( DetectVisual )
self.DetectVisual = DetectVisual
return self
end
--- Detect Optical.
@ -655,6 +711,8 @@ do -- DETECTION_BASE
self:F2()
self.DetectOptical = DetectOptical
return self
end
--- Detect Radar.
@ -665,6 +723,8 @@ do -- DETECTION_BASE
self:F2()
self.DetectRadar = DetectRadar
return self
end
--- Detect IRST.
@ -675,6 +735,8 @@ do -- DETECTION_BASE
self:F2()
self.DetectIRST = DetectIRST
return self
end
--- Detect RWR.
@ -685,6 +747,8 @@ do -- DETECTION_BASE
self:F2()
self.DetectRWR = DetectRWR
return self
end
--- Detect DLINK.
@ -695,9 +759,52 @@ do -- DETECTION_BASE
self:F2()
self.DetectDLINK = DetectDLINK
return self
end
end
do -- Filter methods
--- Filter the detected units based on Unit.Category
-- The different values of Unit.Category can be:
--
-- * Unit.Category.AIRPLANE
-- * Unit.Category.GROUND_UNIT
-- * Unit.Category.HELICOPTER
-- * Unit.Category.SHIP
-- * Unit.Category.STRUCTURE
--
-- Multiple Unit.Category entries can be given as a table and then these will be evaluated as an OR expression.
--
-- Example to filter a single category (Unit.Category.AIRPLANE).
--
-- DetectionObject:FilterCategories( Unit.Category.AIRPLANE )
--
-- Example to filter multiple categories (Unit.Category.AIRPLANE, Unit.Category.HELICOPTER). Note the {}.
--
-- DetectionObject:FilterCategories( { Unit.Category.AIRPLANE, Unit.Category.HELICOPTER } )
--
-- @param #DETECTION_BASE self
-- @param #list<Dcs.DCSUnit#Unit> FilterCategories The Categories entries
-- @return #DETECTION_BASE self
function DETECTION_BASE:FilterCategories( FilterCategories )
self:F2()
self._.FilterCategories = {}
if type( FilterCategories ) == "table" then
for CategoryID, Category in pairs( FilterCategories ) do
self._.FilterCategories[Category] = Category
end
else
self._.FilterCategories[FilterCategories] = FilterCategories
end
return self
end
end
do

547
docs/Documentation/Detection.html
View File

@ -103,8 +103,25 @@
<p>DETECTION classes facilitate the detection of enemy units within the battle zone executed by FACs (Forward Air Controllers) or RECCEs (Reconnassance Units).
DETECTION uses the in-built detection capabilities of DCS World, but adds new functionalities.</p>
<p>Please watch this <a href="https://youtu.be/C7p81dUwP-E">youtube video</a> that explains the detection concepts.</p>
<p>Find the DETECTION classes documentation further in this document in the globals section.</p>
<hr/>
<h1>Demo Missions</h1>
<h3><a href="https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master-release/DET%20-%20Detection">DETECTION Demo Missions and Source Code</a></h3>
<h3><a href="https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/DET%20-%20Detection">DETECTION Demo Missions, only for Beta Testers</a></h3>
<h3><a href="https://github.com/FlightControl-Master/MOOSE_MISSIONS/releases">ALL Demo Missions pack of the Latest Release</a></h3>
<hr/>
<h1>YouTube Channel</h1>
<h3><a href="https://www.youtube.com/playlist?list=PL7ZUrU4zZUl3Cf5jpI6BS0sBOVWK__tji">DETECTION YouTube Channel</a></h3>
<hr/>
<h3>Contributions:</h3>
@ -130,7 +147,9 @@ DETECTION uses the in-built detection capabilities of DCS World, but adds new fu
<tr>
<td class="name" nowrap="nowrap"><a href="#DETECTION_BASE">DETECTION_BASE</a></td>
<td class="summary">
<p>DETECTION_BASE class, extends <a href="Fsm.html##(FSM)">Fsm#FSM</a></p>
<p>The DETECTION_BASE class defines the core functions to administer detected objects.</p>
</td>
</tr>
<tr>
@ -324,12 +343,6 @@ DETECTION uses the in-built detection capabilities of DCS World, but adds new fu
<td class="name" nowrap="nowrap"><a href="##(DETECTION_BASE).AlphaAngleProbability">DETECTION_BASE.AlphaAngleProbability</a></td>
<td class="summary">
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(DETECTION_BASE).ClassName">DETECTION_BASE.ClassName</a></td>
<td class="summary">
</td>
</tr>
<tr>
@ -474,6 +487,23 @@ DETECTION uses the in-built detection capabilities of DCS World, but adds new fu
<td class="name" nowrap="nowrap"><a href="##(DETECTION_BASE).DistanceProbability">DETECTION_BASE.DistanceProbability</a></td>
<td class="summary">
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(DETECTION_BASE).FilterCategories">DETECTION_BASE:FilterCategories(<, FilterCategories)</a></td>
<td class="summary">
<p>Filter the detected units based on Unit.Category <br/>
The different values of Unit.Category can be:</p>
<ul>
<li>Unit.Category.AIRPLANE</li>
<li>Unit.Category.GROUND_UNIT</li>
<li>Unit.Category.HELICOPTER</li>
<li>Unit.Category.SHIP</li>
<li>Unit.Category.STRUCTURE</li>
</ul>
<p>Multiple Unit.Category entries can be given as a table and then these will be evaluated as an OR expression.</p>
</td>
</tr>
<tr>
@ -1065,7 +1095,233 @@ DETECTION uses the in-built detection capabilities of DCS World, but adds new fu
</dt>
<dd>
<p>DETECTION_BASE class, extends <a href="Fsm.html##(FSM)">Fsm#FSM</a></p>
<p>The DETECTION_BASE class defines the core functions to administer detected objects.</p>
<p>The DETECTION_BASE class will detect objects within the battle zone for a list of <a href="Group.html">Group</a>s detecting targets following (a) detection method(s).</p>
<h2>DETECTION_BASE constructor</h2>
<p>Construct a new DETECTION_BASE instance using the <a href="##(DETECTION_BASE).New">DETECTION_BASE.New</a>() method.</p>
<h2>Initialization</h2>
<p>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.
You can specify to apply multiple detection methods.</p>
<p>Use the following functions to report the objects it detected using the methods Visual, Optical, Radar, IRST, RWR, DLINK:</p>
<ul>
<li><a href="##(DETECTION_BASE).InitDetectVisual">DETECTION_BASE.InitDetectVisual</a>(): Detected using Visual.</li>
<li><a href="##(DETECTION_BASE).InitDetectOptical">DETECTION_BASE.InitDetectOptical</a>(): Detected using Optical.</li>
<li><a href="##(DETECTION_BASE).InitDetectRadar">DETECTION_BASE.InitDetectRadar</a>(): Detected using Radar.</li>
<li><a href="##(DETECTION_BASE).InitDetectIRST">DETECTION_BASE.InitDetectIRST</a>(): Detected using IRST.</li>
<li><a href="##(DETECTION_BASE).InitDetectRWR">DETECTION_BASE.InitDetectRWR</a>(): Detected using RWR.</li>
<li><a href="##(DETECTION_BASE).InitDetectDLINK">DETECTION_BASE.InitDetectDLINK</a>(): Detected using DLINK.</li>
</ul>
<h2><strong>DETECTION_ derived classes</strong> group the detected units into a <strong>DetectedItems[]</strong> list</h2>
<p>DETECTION<em>BASE 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 SET</em>UNIT object that contains the detected units that belong to that group.</p>
<p>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. </p>
<p>Various methods exist how to retrieve the grouped items from a DETECTION_BASE derived class:</p>
<ul>
<li>The method <a href="Detection.html##(DETECTION_BASE).GetDetectedItems">Detection#DETECTION_BASE.GetDetectedItems</a>() retrieves the DetectedItems[] list.</li>
<li>A DetectedItem from the DetectedItems[] list can be retrieved using the method <a href="Detection.html##(DETECTION_BASE).GetDetectedItem">Detection#DETECTION_BASE.GetDetectedItem</a>( 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.</li>
<li>A DetectedSet from the DetectedItems[] list can be retrieved using the method <a href="Detection.html##(DETECTION_BASE).GetDetectedSet">Detection#DETECTION_BASE.GetDetectedSet</a>( DetectedItemIndex ).
This method retrieves the Set from a DetectedItem element from the DetectedItem list (DetectedItems[ DetectedItemIndex ].Set ).</li>
</ul>
<h2><strong>Filter</strong> detected units based on <strong>category of the unit</strong></h2>
<p>Filter the detected units based on Unit.Category using the method <a href="##(DETECTION_BASE).FilterCategories">DETECTION_BASE.FilterCategories</a>(). <br/>
The different values of Unit.Category can be:</p>
<ul>
<li>Unit.Category.AIRPLANE</li>
<li>Unit.Category.GROUND_UNIT</li>
<li>Unit.Category.HELICOPTER</li>
<li>Unit.Category.SHIP</li>
<li>Unit.Category.STRUCTURE</li>
</ul>
<p>Multiple Unit.Category entries can be given as a table and then these will be evaluated as an OR expression.</p>
<p>Example to filter a single category (Unit.Category.AIRPLANE).</p>
<pre><code>DetectionObject:FilterCategories( Unit.Category.AIRPLANE )
</code></pre>
<p>Example to filter multiple categories (Unit.Category.AIRPLANE, Unit.Category.HELICOPTER). Note the {}.</p>
<pre><code>DetectionObject:FilterCategories( { Unit.Category.AIRPLANE, Unit.Category.HELICOPTER } )
</code></pre>
<h2><strong>Visual filters</strong> to fine-tune the probability of the detected objects</h2>
<p>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.</p>
<p>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.</p>
<p>The following additional filtering can be applied for visual filtering:</p>
<ul>
<li>A probability factor per kilometer distance.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>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.</p>
<h3>Distance visual detection probability</h3>
<p>Upon a <strong>visual</strong> 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.</p>
<p>A distance probability factor between 0 and 1 can be given, that will model a linear extrapolated probability over 10 km distance.</p>
<p>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%.</p>
<p>Note that based on this probability factor, not only the detection but also the <strong>type</strong> of the unit will be applied!</p>
<p>Use the method <a href="Detection.html##(DETECTION_BASE).SetDistanceProbability">Detection#DETECTION_BASE.SetDistanceProbability</a>() to set the probability factor upon a 10 km distance.</p>
<h3>Alpha Angle visual detection probability</h3>
<p>Upon a <strong>visual</strong> 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.</p>
<p>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.</p>
<p>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%</p>
<p>Use the method <a href="Detection.html##(DETECTION_BASE).SetAlphaAngleProbability">Detection#DETECTION_BASE.SetAlphaAngleProbability</a>() to set the probability factor if 0°.</p>
<h3>Cloudy Zones detection probability</h3>
<p>Upon a <strong>visual</strong> 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.</p>
<p>Use the method <a href="Detection.html##(DETECTION_BASE).SetZoneProbability">Detection#DETECTION_BASE.SetZoneProbability</a>() to set for a defined number of zones, the probability factors.</p>
<p>Note however, that the more zones are defined to be "cloudy" within a detection, the more performance it will take
from the DETECTION<em>BASE to calculate the presence of the detected unit within each zone.
Expecially for ZONE</em>POLYGON, try to limit the amount of nodes of the polygon!</p>
<p>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.</p>
<h2>Accept / Reject detected units</h2>
<p>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.</p>
<h3>Detection acceptance of within range limit</h3>
<p>A range can be set that will limit a successful detection for a unit.
Use the method <a href="Detection.html##(DETECTION_BASE).SetAcceptRange">Detection#DETECTION_BASE.SetAcceptRange</a>() to apply a range in meters till where detected units will be accepted.</p>
<pre><code> 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()
</code></pre>
<h3>Detection acceptance if within zone(s).</h3>
<p>Specific ZONE<em>BASE object(s) can be given as a parameter, which will only accept a detection if the unit is within the specified ZONE</em>BASE object(s).
Use the method <a href="Detection.html##(DETECTION_BASE).SetAcceptZones">Detection#DETECTION_BASE.SetAcceptZones</a>() will accept detected units if they are within the specified zones.</p>
<pre><code> 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()
</code></pre>
<h3>Detection rejectance if within zone(s).</h3>
<p>Specific ZONE<em>BASE object(s) can be given as a parameter, which will reject detection if the unit is within the specified ZONE</em>BASE object(s).
Use the method <a href="Detection.html##(DETECTION_BASE).SetRejectZones">Detection#DETECTION_BASE.SetRejectZones</a>() will reject detected units if they are within the specified zones.
An example of how to use the method is shown below.</p>
<pre><code> 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()
</code></pre>
<h2>DETECTION_BASE is a Finite State Machine</h2>
<p>Various Events and State Transitions can be tailored using DETECTION_BASE.</p>
<h3>DETECTION_BASE States</h3>
<ul>
<li><strong>Detecting</strong>: The detection is running.</li>
<li><strong>Stopped</strong>: The detection is stopped.</li>
</ul>
<h3>DETECTION_BASE Events</h3>
<ul>
<li><strong>Start</strong>: Start the detection process.</li>
<li><strong>Detect</strong>: Detect new units.</li>
<li><strong>Detected</strong>: New units have been detected.</li>
<li><strong>Stop</strong>: Stop the detection process.
</li>
</ul>
</dd>
</dl>
@ -1548,209 +1804,7 @@ self</p>
</dl>
<h2><a id="#(DETECTION_BASE)" >Type <code>DETECTION_BASE</code></a></h2>
<h1>1) DETECTION_BASE class, extends <a href="Fsm.html##(FSM)">Fsm#FSM</a></h1>
<p>The DETECTION_BASE class defines the core functions to administer detected objects.</p>
<p>The DETECTION_BASE class will detect objects within the battle zone for a list of <a href="Group.html">Group</a>s detecting targets following (a) detection method(s).</p>
<h2>1.1) DETECTION_BASE constructor</h2>
<p>Construct a new DETECTION_BASE instance using the <a href="##(DETECTION_BASE).New">DETECTION_BASE.New</a>() method.</p>
<h2>1.2) DETECTION_BASE initialization</h2>
<p>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.
You can specify to apply multiple detection methods.</p>
<p>Use the following functions to report the objects it detected using the methods Visual, Optical, Radar, IRST, RWR, DLINK:</p>
<ul>
<li><a href="##(DETECTION_BASE).InitDetectVisual">DETECTION_BASE.InitDetectVisual</a>(): Detected using Visual.</li>
<li><a href="##(DETECTION_BASE).InitDetectOptical">DETECTION_BASE.InitDetectOptical</a>(): Detected using Optical.</li>
<li><a href="##(DETECTION_BASE).InitDetectRadar">DETECTION_BASE.InitDetectRadar</a>(): Detected using Radar.</li>
<li><a href="##(DETECTION_BASE).InitDetectIRST">DETECTION_BASE.InitDetectIRST</a>(): Detected using IRST.</li>
<li><a href="##(DETECTION_BASE).InitDetectRWR">DETECTION_BASE.InitDetectRWR</a>(): Detected using RWR.</li>
<li><a href="##(DETECTION_BASE).InitDetectDLINK">DETECTION_BASE.InitDetectDLINK</a>(): Detected using DLINK.</li>
</ul>
<h2>1.3) DETECTION_BASE derived classes group the detected units into a DetectedItems[] list</h2>
<p>DETECTION<em>BASE 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 SET</em>UNIT object that contains the detected units that belong to that group.</p>
<p>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. </p>
<p>Various methods exist how to retrieve the grouped items from a DETECTION_BASE derived class:</p>
<ul>
<li>The method <a href="Detection.html##(DETECTION_BASE).GetDetectedItems">Detection#DETECTION_BASE.GetDetectedItems</a>() retrieves the DetectedItems[] list.</li>
<li>A DetectedItem from the DetectedItems[] list can be retrieved using the method <a href="Detection.html##(DETECTION_BASE).GetDetectedItem">Detection#DETECTION_BASE.GetDetectedItem</a>( 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.</li>
<li>A DetectedSet from the DetectedItems[] list can be retrieved using the method <a href="Detection.html##(DETECTION_BASE).GetDetectedSet">Detection#DETECTION_BASE.GetDetectedSet</a>( DetectedItemIndex ).
This method retrieves the Set from a DetectedItem element from the DetectedItem list (DetectedItems[ DetectedItemIndex ].Set ).</li>
</ul>
<h2>1.4) Apply additional Filters to fine-tune the detected objects</h2>
<p>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.</p>
<p>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.</p>
<p>The following additional filtering can be applied for visual filtering:</p>
<ul>
<li>A probability factor per kilometer distance.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>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.</p>
<h3>1.4.1 ) Distance visual detection probability</h3>
<p>Upon a <strong>visual</strong> 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.</p>
<p>A distance probability factor between 0 and 1 can be given, that will model a linear extrapolated probability over 10 km distance.</p>
<p>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%.</p>
<p>Note that based on this probability factor, not only the detection but also the <strong>type</strong> of the unit will be applied!</p>
<p>Use the method <a href="Detection.html##(DETECTION_BASE).SetDistanceProbability">Detection#DETECTION_BASE.SetDistanceProbability</a>() to set the probability factor upon a 10 km distance.</p>
<h3>1.4.2 ) Alpha Angle visual detection probability</h3>
<p>Upon a <strong>visual</strong> 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.</p>
<p>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.</p>
<p>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%</p>
<p>Use the method <a href="Detection.html##(DETECTION_BASE).SetAlphaAngleProbability">Detection#DETECTION_BASE.SetAlphaAngleProbability</a>() to set the probability factor if 0°.</p>
<h3>1.4.3 ) Cloudy Zones detection probability</h3>
<p>Upon a <strong>visual</strong> 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.</p>
<p>Use the method <a href="Detection.html##(DETECTION_BASE).SetZoneProbability">Detection#DETECTION_BASE.SetZoneProbability</a>() to set for a defined number of zones, the probability factors.</p>
<p>Note however, that the more zones are defined to be "cloudy" within a detection, the more performance it will take
from the DETECTION<em>BASE to calculate the presence of the detected unit within each zone.
Expecially for ZONE</em>POLYGON, try to limit the amount of nodes of the polygon!</p>
<p>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.</p>
<h2>1.5 ) Accept / Reject detected units</h2>
<p>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.</p>
<h3>1.5.1 ) Detection acceptance of within range limit</h3>
<p>A range can be set that will limit a successful detection for a unit.
Use the method <a href="Detection.html##(DETECTION_BASE).SetAcceptRange">Detection#DETECTION_BASE.SetAcceptRange</a>() to apply a range in meters till where detected units will be accepted.</p>
<pre><code> 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()
</code></pre>
<h3>1.5.2 ) Detection acceptance if within zone(s).</h3>
<p>Specific ZONE<em>BASE object(s) can be given as a parameter, which will only accept a detection if the unit is within the specified ZONE</em>BASE object(s).
Use the method <a href="Detection.html##(DETECTION_BASE).SetAcceptZones">Detection#DETECTION_BASE.SetAcceptZones</a>() will accept detected units if they are within the specified zones.</p>
<pre><code> 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()
</code></pre>
<h3>1.5.3 ) Detection rejectance if within zone(s).</h3>
<p>Specific ZONE<em>BASE object(s) can be given as a parameter, which will reject detection if the unit is within the specified ZONE</em>BASE object(s).
Use the method <a href="Detection.html##(DETECTION_BASE).SetRejectZones">Detection#DETECTION_BASE.SetRejectZones</a>() will reject detected units if they are within the specified zones.
An example of how to use the method is shown below.</p>
<pre><code> 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()
</code></pre>
<h2>1.6) DETECTION_BASE is a Finite State Machine</h2>
<p>Various Events and State Transitions can be tailored using DETECTION_BASE.</p>
<h3>1.6.1) DETECTION_BASE States</h3>
<ul>
<li><strong>Detecting</strong>: The detection is running.</li>
<li><strong>Stopped</strong>: The detection is stopped.</li>
</ul>
<h3>1.6.2) DETECTION_BASE Events</h3>
<ul>
<li><strong>Start</strong>: Start the detection process.</li>
<li><strong>Detect</strong>: Detect new units.</li>
<li><strong>Detected</strong>: New units have been detected.</li>
<li><strong>Stop</strong>: Stop the detection process.</li>
</ul>
<h3>Field(s)</h3>
<h3>Field(s)</h3>
<dl class="function">
<dt>
@ -1967,20 +2021,6 @@ The index of the DetectedItem.</p>
</dd>
</dl>
<dl class="function">
<dt>
<em>#string</em>
<a id="#(DETECTION_BASE).ClassName" >
<strong>DETECTION_BASE.ClassName</strong>
</a>
</dt>
<dd>
</dd>
</dl>
<dl class="function">
@ -2144,7 +2184,6 @@ self</p>
<dl class="function">
<dt>
<em>#number</em>
<a id="#(DETECTION_BASE).DetectedItemMax" >
<strong>DETECTION_BASE.DetectedItemMax</strong>
</a>
@ -2337,6 +2376,62 @@ self</p>
</dd>
</dl>
<dl class="function">
<dt>
<a id="#(DETECTION_BASE).FilterCategories" >
<strong>DETECTION_BASE:FilterCategories(<, FilterCategories)</strong>
</a>
</dt>
<dd>
<p>Filter the detected units based on Unit.Category <br/>
The different values of Unit.Category can be:</p>
<ul>
<li>Unit.Category.AIRPLANE</li>
<li>Unit.Category.GROUND_UNIT</li>
<li>Unit.Category.HELICOPTER</li>
<li>Unit.Category.SHIP</li>
<li>Unit.Category.STRUCTURE</li>
</ul>
<p>Multiple Unit.Category entries can be given as a table and then these will be evaluated as an OR expression.</p>
<p>Example to filter a single category (Unit.Category.AIRPLANE).</p>
<pre><code>DetectionObject:FilterCategories( Unit.Category.AIRPLANE )
</code></pre>
<p>Example to filter multiple categories (Unit.Category.AIRPLANE, Unit.Category.HELICOPTER). Note the {}.</p>
<pre><code>DetectionObject:FilterCategories( { Unit.Category.AIRPLANE, Unit.Category.HELICOPTER } )
</code></pre>
<h3>Parameters</h3>
<ul>
<li>
<p><code><em><a href="##(list)">#list</a> &lt; </em></code>:
cs.DCSUnit#Unit> FilterCategories The Categories entries</p>
</li>
<li>
<p><code><em> FilterCategories </em></code>: </p>
</li>
</ul>
<h3>Return value</h3>
<p><em><a href="##(DETECTION_BASE)">#DETECTION_BASE</a>:</em>
self</p>
</dd>
</dl>
<dl class="function">
@ -4449,6 +4544,8 @@ self</p>
<h2><a id="#(DETECTION_UNITS.DetectedItem)" >Type <code>DETECTION_UNITS.DetectedItem</code></a></h2>
<h2><a id="#(list)" >Type <code>list</code></a></h2>
</div>
</div>

33
docs/Documentation/Spawn.html
View File

@ -809,6 +809,12 @@ and any spaces before and after the resulting name are removed.</p>
<td class="name" nowrap="nowrap"><a href="##(SPAWN)._TranslateRotate">SPAWN:_TranslateRotate(SpawnIndex, SpawnRootX, SpawnRootY, SpawnX, SpawnY, SpawnAngle)</a></td>
<td class="summary">
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(SPAWN).uncontrolled">SPAWN.uncontrolled</a></td>
<td class="summary">
</td>
</tr>
</table>
@ -2110,9 +2116,6 @@ The group that was spawned. You can use this group for further actions.</p>
<p> Don't repeat the group from Take-Off till Landing and back Take-Off by ReSpawning.</p>
</dd>
</dl>
<dl class="function">
@ -2566,6 +2569,9 @@ when nothing was spawned.</p>
<p> Overwrite unit names by default with group name.</p>
</dd>
</dl>
<dl class="function">
@ -2580,9 +2586,6 @@ when nothing was spawned.</p>
<p> By default, no InitLimit</p>
</dd>
</dl>
<dl class="function">
@ -2618,7 +2621,7 @@ when nothing was spawned.</p>
<dl class="function">
<dt>
<em>#number</em>
<em></em>
<a id="#(SPAWN).SpawnMaxGroups" >
<strong>SPAWN.SpawnMaxGroups</strong>
</a>
@ -2635,7 +2638,7 @@ when nothing was spawned.</p>
<dl class="function">
<dt>
<em>#number</em>
<em></em>
<a id="#(SPAWN).SpawnMaxUnitsAlive" >
<strong>SPAWN.SpawnMaxUnitsAlive</strong>
</a>
@ -3543,6 +3546,20 @@ True = Continue Scheduler</p>
</li>
</ul>
</dd>
</dl>
<dl class="function">
<dt>
<em></em>
<a id="#(SPAWN).uncontrolled" >
<strong>SPAWN.uncontrolled</strong>
</a>
</dt>
<dd>
</dd>
</dl>