From d7f1a74caf3a68ec251ef0e8b81faf70e605ff8a Mon Sep 17 00:00:00 2001 From: FlightControl Date: Wed, 12 Apr 2017 09:00:00 +0200 Subject: [PATCH] Implemented :FilterCategories() method for DETECTION_ classes fixing issue #415 -- 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 --- Moose Development/Moose/Core/Base.lua | 8 +- .../Moose/Functional/Detection.lua | 175 ++++-- docs/Documentation/Detection.html | 547 +++++++++++------- docs/Documentation/Spawn.html | 33 +- 4 files changed, 492 insertions(+), 271 deletions(-) diff --git a/Moose Development/Moose/Core/Base.lua b/Moose Development/Moose/Core/Base.lua index e047c76d1..018f2eb02 100644 --- a/Moose Development/Moose/Core/Base.lua +++ b/Moose Development/Moose/Core/Base.lua @@ -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 diff --git a/Moose Development/Moose/Functional/Detection.lua b/Moose Development/Moose/Functional/Detection.lua index 15d3efd4c..004d93c59 100644 --- a/Moose Development/Moose/Functional/Detection.lua +++ b/Moose Development/Moose/Functional/Detection.lua @@ -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 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 diff --git a/docs/Documentation/Detection.html b/docs/Documentation/Detection.html index ce5ce382d..f7502a58f 100644 --- a/docs/Documentation/Detection.html +++ b/docs/Documentation/Detection.html @@ -103,8 +103,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 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

+ +

DETECTION Demo Missions, only for Beta Testers

+ +

ALL Demo Missions pack of the Latest Release

+ +
+ +

YouTube Channel

+ +

DETECTION YouTube Channel

+ +

Contributions:

@@ -130,7 +147,9 @@ DETECTION uses the in-built detection capabilities of DCS World, but adds new fu DETECTION_BASE +

DETECTION_BASE class, extends Fsm#FSM

+

The DETECTION_BASE class defines the core functions to administer detected objects.

@@ -324,12 +343,6 @@ DETECTION uses the in-built detection capabilities of DCS World, but adds new fu DETECTION_BASE.AlphaAngleProbability - - - - DETECTION_BASE.ClassName - - @@ -474,6 +487,23 @@ DETECTION uses the in-built detection capabilities of DCS World, but adds new fu DETECTION_BASE.DistanceProbability + + + + DETECTION_BASE:FilterCategories(<, FilterCategories) + +

Filter the detected units based on Unit.Category
+The different values of Unit.Category can be:

+ + + +

Multiple Unit.Category entries can be given as a table and then these will be evaluated as an OR expression.

@@ -1065,7 +1095,233 @@ DETECTION uses the in-built detection capabilities of DCS World, but adds new fu
+

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 Groups detecting targets following (a) detection method(s).

+ +

DETECTION_BASE constructor

+ +

Construct a new DETECTION_BASE instance using the DETECTION_BASE.New() method.

+ +

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. +You can specify to apply multiple detection methods.

+ +

Use the following functions to report the objects it detected using the methods Visual, Optical, Radar, IRST, RWR, DLINK:

+ + + + +

DETECTION_ 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 ).
    • +
+ +

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 } )
+
+ +

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. +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.

+ + +

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.

+ +

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°.

+ +

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.

+ +

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.

+ +

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()
+
+ + +

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()
+
+ +

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()
+
+ +

DETECTION_BASE is a Finite State Machine

+ +

Various Events and State Transitions can be tailored using DETECTION_BASE.

+ +

DETECTION_BASE States

+ +
    +
  • Detecting: The detection is running.
    • +
  • Stopped: The detection is stopped.
    • +
+ +

DETECTION_BASE Events

+ +
    +
  • Start: Start the detection process.
    • +
  • Detect: Detect new units.
    • +
  • Detected: New units have been detected.
    • +
  • Stop: Stop the detection process. +
    • +
@@ -1548,209 +1804,7 @@ self

Type DETECTION_BASE

- -

1) 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 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

- -

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.

- -

Use the following functions to report the objects it detected using the methods Visual, Optical, Radar, IRST, RWR, DLINK:

- - - -

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:

- - - -

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:

- - - -

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

- - - -

1.6.2) DETECTION_BASE Events

- - - - -

Field(s)

+

Field(s)

@@ -1967,20 +2021,6 @@ The index of the DetectedItem.

- -
-
-
- - #string - -DETECTION_BASE.ClassName - -
-
- - -
@@ -2144,7 +2184,6 @@ self

- #number DETECTION_BASE.DetectedItemMax @@ -2337,6 +2376,62 @@ self

+ +
+
+
+ + +DETECTION_BASE:FilterCategories(<, FilterCategories) + +
+
+ +

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 } )
+
+ + +

Parameters

+
    +
  • + +

    #list < : +cs.DCSUnit#Unit> FilterCategories The Categories entries

    + +
    • +
  • + +

    FilterCategories :

    + +
    • +
+

Return value

+ +

#DETECTION_BASE: +self

+
@@ -4449,6 +4544,8 @@ self

Type DETECTION_UNITS.DetectedItem

+

Type list

+ diff --git a/docs/Documentation/Spawn.html b/docs/Documentation/Spawn.html index 6193f9f69..5627c6528 100644 --- a/docs/Documentation/Spawn.html +++ b/docs/Documentation/Spawn.html @@ -809,6 +809,12 @@ and any spaces before and after the resulting name are removed.

SPAWN:_TranslateRotate(SpawnIndex, SpawnRootX, SpawnRootY, SpawnX, SpawnY, SpawnAngle) + + + + SPAWN.uncontrolled + + @@ -2110,9 +2116,6 @@ The group that was spawned. You can use this group for further actions.

- -

Don't repeat the group from Take-Off till Landing and back Take-Off by ReSpawning.

-
@@ -2566,6 +2569,9 @@ when nothing was spawned.

+ +

Overwrite unit names by default with group name.

+
@@ -2580,9 +2586,6 @@ when nothing was spawned.

- -

By default, no InitLimit

-
@@ -2618,7 +2621,7 @@ when nothing was spawned.

- #number + SPAWN.SpawnMaxGroups @@ -2635,7 +2638,7 @@ when nothing was spawned.

- #number + SPAWN.SpawnMaxUnitsAlive @@ -3543,6 +3546,20 @@ True = Continue Scheduler

+ +
+
+
+ + + +SPAWN.uncontrolled + +
+
+ + +