Update Detection.lua (#1685)

Code formatting. Fix minor typos, errors, and references in documentation.

Moose Development/Moose/Functional/Detection.lua

@@ -19,7 +19,7 @@
 --
 -- ===
 --
--- Facilitate the detection of enemy units within the battle zone executed by FACs (Forward Air Controllers) or RECCEs (Reconnassance Units).
+-- Facilitate the detection of enemy units within the battle zone executed by FACs (Forward Air Controllers) or RECCEs (Reconnaissance Units).
 -- It uses the in-built detection capabilities of DCS World, but adds new functionalities.
 --
 -- ===
@@ -37,7 +37,6 @@
 -- @module Functional.Detection
 -- @image Detection.JPG
 
-
 do -- DETECTION_BASE
 
   --- @type DETECTION_BASE
@@ -92,7 +91,6 @@ do -- DETECTION_BASE
   --
   --     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
@@ -128,11 +126,10 @@ do -- DETECTION_BASE
   --   * 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.
+  --     The mission designer needs to define these cloudy zones within the mission, and needs to register these zones in the DETECTION_ objects adding 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.
+  -- Only when you experience unrealistic behavior in your missions, these filters could be applied.
-  -- 
   --
   -- ### Distance visual detection probability
   --
@@ -170,9 +167,9 @@ do -- DETECTION_BASE
   --
   -- Note however, that the more zones are defined to be "cloudy" within a detection, the more performance it will take
   -- from the DETECTION_BASE to calculate the presence of the detected unit within each zone.
-  -- Expecially for ZONE_POLYGON, try to limit the amount of nodes of the polygon!
+  -- Especially for ZONE_POLYGON, 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
+  -- Typically, this kind of filter would be applied for very specific areas where a detection needs to be very realistic for
   -- AI not to detect so easily targets within a forrest or village rich area.
   --
   -- ## Accept / Reject detected units
@@ -217,7 +214,7 @@ do -- DETECTION_BASE
   --      -- Start the Detection.
   --      Detection:Start()
   --
-  -- ### Detection rejectance if within zone(s).
+  -- ### Detection rejection 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 @{Functional.Detection#DETECTION_BASE.SetRejectZones}() will reject detected units if they are within the specified zones.
@@ -287,11 +284,10 @@ do -- DETECTION_BASE
   -- @field #boolean LastPos
   -- @field #number LastVelocity
 
-  
   --- @type DETECTION_BASE.DetectedItems
   -- @list <#DETECTION_BASE.DetectedItem>
 
-  --- Detected item data structrue.
+  --- Detected item data structure.
   -- @type DETECTION_BASE.DetectedItem
   -- @field #boolean IsDetected Indicates if the DetectedItem has been detected or not.
   -- @field Core.Set#SET_UNIT Set The Set of Units in the detected area.
@@ -302,7 +298,7 @@ do -- DETECTION_BASE
   -- @field #boolean FriendliesNearBy Indicates if there are friendlies within the detected area.
   -- @field Wrapper.Unit#UNIT NearestFAC The nearest FAC near the Area.
   -- @field Core.Point#COORDINATE Coordinate The last known coordinate of the DetectedItem.
-  -- @field Core.Point#COORDINATE InterceptCoord Intercept coordiante.
+  -- @field Core.Point#COORDINATE InterceptCoord Intercept coordinate.
   -- @field #number DistanceRecce Distance in meters of the Recce.
   -- @field #number Index Detected item key. Could also be a string.
   -- @field #string ItemID ItemPrefix .. "." .. self.DetectedItemMax.
@@ -310,7 +306,7 @@ do -- DETECTION_BASE
   -- @field #table PlayersNearBy Table of nearby players.
   -- @field #table FriendliesDistance Table of distances to friendly units.
   -- @field #string TypeName Type name of the detected unit.
-  -- @field #string CategoryName Catetory name of the detected unit.
+  -- @field #string CategoryName Category name of the detected unit.
   -- @field #string Name Name of the detected object.
   -- @field #boolean IsVisible If true, detected object is visible.
   -- @field #number LastTime Last time the detected item was seen.
@@ -441,7 +437,6 @@ do -- DETECTION_BASE
     -- @param #DETECTION_BASE self
     -- @param #number Delay The delay in seconds.
 
-    
     self:AddTransition( "Detecting", "Detected", "Detecting" )
 
     --- OnBefore Transition Handler for Event Detected.
@@ -566,12 +561,10 @@ do -- DETECTION_BASE
 
       local DetectionInterval = self.DetectionCount / (self.RefreshTimeInterval - 1)
 
-      self:ForEachAliveRecce(
+      self:ForEachAliveRecce( function( DetectionGroup )
-        function( DetectionGroup )
         self:__Detection( DetectDelay, DetectionGroup, DetectionTimeStamp ) -- Process each detection asynchronously.
         DetectDelay = DetectDelay + DetectionInterval
-        end
+      end )
-      )
 
       self:__Detect( -self.RefreshTimeInterval )
 
@@ -594,7 +587,6 @@ do -- DETECTION_BASE
       return self
     end
 
-    
     --- @param #DETECTION_BASE self
     -- @param #string From The From State string.
     -- @param #string Event The Event string.
@@ -675,8 +667,7 @@ do -- DETECTION_BASE
 
             local Distance = ((DetectedObjectVec3.x - DetectionGroupVec3.x) ^ 2 +
                              (DetectedObjectVec3.y - DetectionGroupVec3.y) ^ 2 +
-                ( DetectedObjectVec3.z - DetectionGroupVec3.z )^2
+                             (DetectedObjectVec3.z - DetectionGroupVec3.z) ^ 2) ^ 0.5 / 1000
-                ) ^ 0.5 / 1000
 
             local DetectedUnitCategory = DetectedObject:getDesc().category
 
@@ -854,10 +845,8 @@ do -- DETECTION_BASE
         end
       end
 
-
     end
 
-  
   end
 
   do -- DetectionItems Creation
@@ -906,7 +895,6 @@ do -- DETECTION_BASE
       return self
     end
 
-
   end
 
   do -- Initialization methods
@@ -1151,7 +1139,6 @@ do -- DETECTION_BASE
       return self
     end
 
-  
     --- 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.
     -- 
@@ -1184,7 +1171,6 @@ do -- DETECTION_BASE
       return self
     end
 
-  
   end
 
   do -- Change processing
@@ -1221,7 +1207,6 @@ do -- DETECTION_BASE
       return self
     end
 
-    
     --- Add a change to the detected zone.
     -- @param #DETECTION_BASE self
     -- @param #DETECTION_BASE.DetectedItem DetectedItem
@@ -1315,7 +1300,7 @@ do -- DETECTION_BASE
       return DetectedItem.FriendliesNearIntercept
     end
 
-    --- Returns the distance used to identify friendlies near the deteted item ...
+    --- Returns the distance used to identify friendlies near the detected item ...
     -- @param #DETECTION_BASE self
     -- @param #DETECTION_BASE.DetectedItem DetectedItem The detected item.
     -- @return #table A table of distances to friendlies. 
@@ -1327,7 +1312,7 @@ do -- DETECTION_BASE
     --- Returns if there are friendlies nearby the FAC units ...
     -- @param #DETECTION_BASE self
     -- @param #DETECTION_BASE.DetectedItem DetectedItem
-    -- @return #boolean trhe if there are friendlies nearby 
+    -- @return #boolean true if there are friendlies nearby
     function DETECTION_BASE:IsPlayersNearBy( DetectedItem )
 
       return DetectedItem.PlayersNearBy ~= nil
@@ -1366,7 +1351,6 @@ do -- DETECTION_BASE
             point = InterceptCoord:GetVec3(),
             radius = self.FriendliesRange,
           }
-          
         }
 
         --- @param DCS#Unit FoundDCSUnit
@@ -1465,8 +1449,7 @@ do -- DETECTION_BASE
               end
             end
           end
-          end
+        end )
-        )
       end
 
       self:F( { Friendlies = DetectedItem.FriendliesNearBy, Players = DetectedItem.PlayersNearBy } )
@@ -1542,7 +1525,6 @@ do -- DETECTION_BASE
     return nil
   end
 
-
   --- Gets a detected unit type name, taking into account the detection results.
   -- @param #DETECTION_BASE self
   -- @param Wrapper.Unit#UNIT DetectedUnit
@@ -1570,7 +1552,6 @@ do -- DETECTION_BASE
     return "Undetected:" .. DetectedUnit:GetName()
   end
 
-  
   --- Adds a new DetectedItem to the DetectedItems list.
   -- The DetectedItem is a table and contains a SET_UNIT in the field Set.
   -- @param #DETECTION_BASE self
@@ -1584,7 +1565,6 @@ do -- DETECTION_BASE
     self.DetectedItemCount = self.DetectedItemCount + 1
     self.DetectedItemMax = self.DetectedItemMax + 1
 
-    
     DetectedItemKey = DetectedItemKey or self.DetectedItemMax
     self.DetectedItems[DetectedItemKey] = DetectedItem
     self.DetectedItemsByIndex[DetectedItemKey] = DetectedItem
@@ -1636,7 +1616,6 @@ do -- DETECTION_BASE
     end
   end
 
-  
   --- Get the DetectedItems by Key.
   -- This will return the DetectedItems collection, indexed by the Key, which can be any object that acts as the key of the detection.
   -- @param #DETECTION_BASE self
@@ -1657,7 +1636,7 @@ do -- DETECTION_BASE
 
   --- Get the amount of SETs with detected objects.
   -- @param #DETECTION_BASE self
-  -- @return #number The amount of detected items. Note that the amount of detected items can differ with the reality, because detections are not real-time but doen in intervals!
+  -- @return #number The amount of detected items. Note that the amount of detected items can differ with the reality, because detections are not real-time but done in intervals!
   function DETECTION_BASE:GetDetectedItemsCount()
 
     local DetectedCount = self.DetectedItemCount
@@ -1719,7 +1698,7 @@ do -- DETECTION_BASE
     return ""
   end
 
-  --- Get the @{Core.Set#SET_UNIT} of a detecttion area using a given numeric index.
+  --- Get the @{Core.Set#SET_UNIT} of a detection area using a given numeric index.
   -- @param #DETECTION_BASE self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem
   -- @return Core.Set#SET_UNIT DetectedSet
@@ -1766,7 +1745,6 @@ do -- DETECTION_BASE
     return DetectedItem.IsDetected
   end
 
-
   do -- Zones
 
     --- Get the @{Core.Zone#ZONE_UNIT} of a detection area using a given numeric index.
@@ -1800,7 +1778,6 @@ do -- DETECTION_BASE
     return self
   end
 
-
   --- Unlock the detected items when created and unlock all existing detected items.
   -- @param #DETECTION_BASE self
   -- @return #DETECTION_BASE
@@ -1824,7 +1801,6 @@ do -- DETECTION_BASE
 
   end
 
-
   --- Lock a detected item.
   -- @param #DETECTION_BASE self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem The DetectedItem.
@@ -1847,9 +1823,6 @@ do -- DETECTION_BASE
     return self
   end
 
-
-
-
   --- Set the detected item coordinate.
   -- @param #DETECTION_BASE self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem The DetectedItem to set the coordinate at.
@@ -1869,7 +1842,6 @@ do -- DETECTION_BASE
     end
   end
 
-
   --- Get the detected item coordinate.
   -- @param #DETECTION_BASE self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem The DetectedItem to set the coordinate at.
@@ -1911,8 +1883,6 @@ do -- DETECTION_BASE
     end
   end
 
-
-
   --- Get the detected item coordinate.
   -- @param #DETECTION_BASE self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem The DetectedItem.
@@ -1928,7 +1898,6 @@ do -- DETECTION_BASE
     return nil, ""
   end
 
-
   --- Report summary of a detected item using a given numeric index.
   -- @param #DETECTION_BASE self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem The DetectedItem.
@@ -1940,7 +1909,7 @@ do -- DETECTION_BASE
     return nil
   end
 
-  --- Report detailed of a detectedion result.
+  --- Report detailed of a detection result.
   -- @param #DETECTION_BASE self
   -- @param Wrapper.Group#GROUP AttackGroup The group to generate the report for.
   -- @return #string
@@ -1987,8 +1956,6 @@ do -- DETECTION_BASE
 
   end
 
-  
-  
   --- Schedule the DETECTION construction.
   -- @param #DETECTION_BASE self
   -- @param #number DelayTime The delay in seconds to wait the reporting.
@@ -2078,7 +2045,6 @@ do -- DETECTION_UNITS
 
   end
 
-  
   --- Create the DetectedItems list from the DetectedObjects table.
   -- For each DetectedItem, a one field array is created containing the Unit detected.
   -- @param #DETECTION_UNITS self
@@ -2130,7 +2096,6 @@ do -- DETECTION_UNITS
       end
     end
 
-
     -- Now we need to loop through the unidentified detected units and add these... These are all new items.
     for DetectedUnitName, DetectedObjectData in pairs( self.DetectedObjects ) do
 
@@ -2181,7 +2146,6 @@ do -- DETECTION_UNITS
 
   end
 
-  
   --- Report summary of a DetectedItem using a given numeric index.
   -- @param #DETECTION_UNITS self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem The DetectedItem.
@@ -2238,7 +2202,6 @@ do -- DETECTION_UNITS
     return nil
   end
 
-  
   --- Report detailed of a detection result.
   -- @param #DETECTION_UNITS self
   -- @param Wrapper.Group#GROUP AttackGroup The group to generate the report for.
@@ -2332,7 +2295,6 @@ do -- DETECTION_TYPES
 
   end
 
-  
   --- Create the DetectedItems list from the DetectedObjects table.
   -- For each DetectedItem, a one field array is created containing the Unit detected.
   -- @param #DETECTION_TYPES self
@@ -2371,7 +2333,6 @@ do -- DETECTION_TYPES
       end
     end
 
-
     -- Now we need to loop through the unidentified detected units and add these... These are all new items.
     for DetectedUnitName, DetectedObjectData in pairs( self.DetectedObjects ) do
 
@@ -2395,8 +2356,6 @@ do -- DETECTION_TYPES
       end
     end
 
-    
-
     -- Check if there are any friendlies nearby.    
     for DetectedItemID, DetectedItemData in pairs( self.DetectedItems ) do
 
@@ -2413,8 +2372,6 @@ do -- DETECTION_TYPES
       self:NearestRecce( DetectedItem )
     end
 
-    
-
   end
 
   --- Report summary of a DetectedItem using a given numeric index.
@@ -2469,7 +2426,6 @@ do -- DETECTION_TYPES
 
 end
 
-
 do -- DETECTION_AREAS
 
   --- @type DETECTION_AREAS
@@ -2484,7 +2440,7 @@ do -- DETECTION_AREAS
   --
   -- ## 4.1) Retrieve the Detected Unit Sets and Detected Zones
   --
-  -- The methods to manage the DetectedItems[].Set(s) are implemented in @{Functional.Detection#DECTECTION_BASE} and 
+  -- The methods to manage the DetectedItems[].Set(s) are implemented in @{Functional.Detection#DETECTION_BASE} and
   -- the methods to manage the DetectedItems[].Zone(s) is implemented in @{Functional.Detection#DETECTION_AREAS}.
   --
   -- Retrieve the DetectedItems[].Set with the method @{Functional.Detection#DETECTION_BASE.GetDetectedSet}(). A @{Core.Set#SET_UNIT} object will be returned.
@@ -2513,7 +2469,6 @@ do -- DETECTION_AREAS
     DetectionZoneRange = nil,
   }
 
-  
   --- DETECTION_AREAS constructor.
   -- @param #DETECTION_AREAS self
   -- @param Core.Set#SET_GROUP DetectionSetGroup The @{Set} of GROUPs in the Forward Air Controller role.
@@ -2535,7 +2490,6 @@ do -- DETECTION_AREAS
     return self
   end
 
-
   --- Report summary of a detected item using a given numeric index.
   -- @param #DETECTION_AREAS self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem The DetectedItem.
@@ -2593,7 +2547,6 @@ do -- DETECTION_AREAS
         DetectedItemCoordText = DetectedItemCoordinate:ToStringA2G( AttackGroup, Settings )
       end
 
-
       local ThreatLevelA2G = self:GetDetectedItemThreatLevel( DetectedItem )
       local DetectedItemsCount = DetectedSet:Count()
       local DetectedItemsTypes = DetectedSet:GetTypeNames()
@@ -2630,7 +2583,6 @@ do -- DETECTION_AREAS
     return ReportText
   end
 
-  
   --- Calculate the optimal intercept point of the DetectedItem.
   -- @param #DETECTION_AREAS self
   -- @param #DETECTION_BASE.DetectedItem DetectedItem
@@ -2655,8 +2607,6 @@ do -- DETECTION_AREAS
 
   end
 
-  
-
   --- Smoke the detected units
   -- @param #DETECTION_AREAS self
   -- @return #DETECTION_AREAS self
@@ -2760,13 +2710,11 @@ do -- DETECTION_AREAS
 
   end
 
-  
+  --- Make a DetectionSet table. This function will be overridden in the derived classes.
-  --- Make a DetectionSet table. This function will be overridden in the derived clsses.
   -- @param #DETECTION_AREAS self
   -- @return #DETECTION_AREAS self
   function DETECTION_AREAS:CreateDetectionItems()
 
-  
     self:F( "Checking Detected Items for new Detected Units ..." )
     -- self:F( { DetectedObjects = self.DetectedObjects } )
 
@@ -2794,8 +2742,6 @@ do -- DETECTION_AREAS
           -- self:IdentifyDetectedObject( DetectedZoneObject )
           AreaExists = true
 
-  
-        
         else
           -- The center object of the detected area has not been detected. Find an other unit of the set to become the center of the area.
           -- First remove the center unit from the set.
@@ -2882,11 +2828,9 @@ do -- DETECTION_AREAS
       end
     end
 
-    
-    
     -- We iterated through the existing detection areas and:
     --  - We checked which units are still detected in each detection area. Those units were flagged as Identified.
-    --  - We recentered the detection area to new center units where it was needed.
+    --  - We re-centered the detection area to new center units where it was needed.
     --
     -- Now we need to loop through the unidentified detected units and see where they belong:
     --  - They can be added to a new detection area and become the new center unit.
@@ -2961,15 +2905,13 @@ do -- DETECTION_AREAS
       self:SetDetectedItemThreatLevel( DetectedItem ) -- Calculate A2G threat level
       self:NearestRecce( DetectedItem )
 
-      
       if DETECTION_AREAS._SmokeDetectedUnits or self._SmokeDetectedUnits then
         DetectedZone.ZoneUNIT:SmokeRed()
       end
 
       -- DetectedSet:Flush( self )
 
-      DetectedSet:ForEachUnit(
+      DetectedSet:ForEachUnit(  --- @param Wrapper.Unit#UNIT DetectedUnit
-        --- @param Wrapper.Unit#UNIT DetectedUnit
       function( DetectedUnit )
         if DetectedUnit:IsAlive() then
           -- self:T( "Detected Set #" .. DetectedItem.ID .. ":" .. DetectedUnit:GetName() )
@@ -2980,8 +2922,7 @@ do -- DETECTION_AREAS
             DetectedUnit:SmokeGreen()
           end
         end
-        end
+      end )
-      )
       if DETECTION_AREAS._FlareDetectedZones or self._FlareDetectedZones then
         DetectedZone:FlareZone( SMOKECOLOR.White, 30, math.random( 0, 90 ) )
       end
@@ -2999,4 +2940,3 @@ do -- DETECTION_AREAS
 
 end
 
-