documented Recognition.Tracking

bbiwarg/Parameters.cs

@@ -23,7 +23,7 @@ namespace bbiwarg
         public static readonly int ConsoleHeight = 30;
 
         // input
-        public static readonly InputType InputSource = InputType.Camera;
+        public static readonly InputType InputSource = InputType.Movie;
         public static readonly String InputMoviePath = "..\\..\\videos\\touch\\4.skv";
 
         // Logger

bbiwarg/Recognition/Tracking/Similarity.cs

@@ -6,14 +6,37 @@ using System.Threading.Tasks;
 
 namespace bbiwarg.Recognition.Tracking
 {
+    /// <summary>
+    /// Encapsulates the similarity between a TrackedObject and a TrackableObject.
+    /// </summary>
+    /// <typeparam name="T">Type of the TrackableObject</typeparam>
+    /// <typeparam name="TrackedT">Type of the TrackedObject</typeparam>
     public class Similarity<T, TrackedT> 
         where T :TrackableObject
         where TrackedT : TrackedObject<T>
     {
+        /// <summary>
+        /// the tracked object
+        /// </summary>
         public TrackedT TrackedObject { get; private set; }
+
+        /// <summary>
+        /// the detected object
+        /// </summary>
         public T DetectedObject { get; private set; }
+
+        /// <summary>
+        /// the similarity value [0-1]
+        /// </summary>
         public float Value { get; private set; }
 
+
+        /// <summary>
+        /// Initializes a new instance of the Similarity class.
+        /// </summary>
+        /// <param name="trackedObject">The tracked object.</param>
+        /// <param name="detectedObject">The detected object.</param>
+        /// <param name="value">The value.</param>
         public Similarity(TrackedT trackedObject, T detectedObject, float value) {
             TrackedObject = trackedObject;
             DetectedObject = detectedObject;

bbiwarg/Recognition/Tracking/TrackIDPool.cs

@@ -6,14 +6,27 @@ using System.Threading.Tasks;
 
 namespace bbiwarg.Recognition.Tracking
 {
-    class TrackIDPool
+    /// <summary>
+    /// Generates unique IDs and keeps track of the currently used IDs.
+    /// </summary>
+    public class TrackIDPool
     {
+        /// <summary>
+        /// the currently used IDs
+        /// </summary>
         private List<int> usedIDs;
 
+        /// <summary>
+        /// Initializes a new instance of the TrackIDPool class.
+        /// </summary>
         public TrackIDPool() {
             usedIDs = new List<int>();
         }
 
+        /// <summary>
+        /// Returns the next unused (lowest) ID.
+        /// </summary>
+        /// <returns>the next unused ID</returns>
         public int getNextUnusedID()
         {
             int id = 1;
@@ -23,6 +36,10 @@ namespace bbiwarg.Recognition.Tracking
             return id;
         }
 
+        /// <summary>
+        /// Removes the given ID from the used IDs.
+        /// </summary>
+        /// <param name="id">the unused ID</param>
         public void setIDUnused(int id)
         {
             usedIDs.Remove(id);

bbiwarg/Recognition/Tracking/TrackableObject.cs

@@ -6,10 +6,20 @@ using System.Threading.Tasks;
 
 namespace bbiwarg.Recognition.Tracking
 {
+    /// <summary>
+    /// A object that can be identified via a unique ID.
+    /// </summary>
     public class TrackableObject
     {
+        /// <summary>
+        /// the track id
+        /// </summary>
         public int TrackID { get; private set; }
 
+        /// <summary>
+        /// Sets the object's track id.
+        /// </summary>
+        /// <param name="id">the track id</param>
         public void setTracked(int id)
         {
             TrackID = id;

bbiwarg/Recognition/Tracking/TrackedObject.cs

@@ -7,6 +7,9 @@ using bbiwarg.Utility;
 
 namespace bbiwarg.Recognition.Tracking
 {
+    /// <summary>
+    /// The possible tracking state values
+    /// </summary>
     public enum TrackingState
     {
         Undefined = 0,
@@ -16,19 +19,65 @@ namespace bbiwarg.Recognition.Tracking
         Deleted = 4
     }
 
+    /// <summary>
+    /// A tracked object is identified by severall TrackableObjects in different frames that have a high similiarity value and are considered to represent the same object over time.
+    /// </summary>
+    /// <typeparam name="T">The type of the trackable object</typeparam>
     public abstract class TrackedObject<T> where T : TrackableObject
     {
+        /// <summary>
+        /// the number of consecutive frames the object has to be detected until its state changes to tracked
+        /// </summary>
         private int numFramesDetectedUntilTracked;
+
+        /// <summary>
+        /// the number of consecutive frames the object has to be lost until its state changes to delete
+        /// </summary>
         private int numFramesLostUntilDeleted;
+
+        /// <summary>
+        /// indicates wether the object has been tracked before
+        /// </summary>
         private bool wasTrackedBefore;
 
+        /// <summary>
+        /// the objects track id
+        /// </summary>
         public int ID { get; private set; }
+
+        /// <summary>
+        /// a reference to the current TrackableObject
+        /// </summary>
         public T CurrentObject { get; private set; }
+
+        /// <summary>
+        /// a reference to the last TrackableObject
+        /// </summary>
         public T LastObject { get; private set; }
+
+        /// <summary>
+        /// the current tracking state
+        /// </summary>
         public TrackingState CurrentState { get; private set; }
+
+        /// <summary>
+        /// the previous tracking state
+        /// </summary>
         public TrackingState PreviousState { get; private set; }
+
+        /// <summary>
+        /// the number of consecutive frames in the current state
+        /// </summary>
         public int NumFramesInCurrentState { get; private set; }
 
+
+        /// <summary>
+        /// Initializes a new instance of the TrackedObject class.
+        /// </summary>
+        /// <param name="id">The track id.</param>
+        /// <param name="detectedObject">The detected object.</param>
+        /// <param name="numFramesDetectedUntilTracked">The number of consecutive frames detected until it is considered to be tracked.</param>
+        /// <param name="numFramesLostUntilDeleted">The number of consecutive frames lost until the object will be deleted.</param>
         public TrackedObject(int id, T detectedObject, int numFramesDetectedUntilTracked, int numFramesLostUntilDeleted)
         {
             ID = id;
@@ -43,6 +92,10 @@ namespace bbiwarg.Recognition.Tracking
             NumFramesInCurrentState = 1;
         }
 
+        /// <summary>
+        /// Adds the detectedObject to the tracking history and updates the current state.
+        /// </summary>
+        /// <param name="detectedObject">the best fitting trackableObject in the current frame</param>
         public virtual void updateFrame(T detectedObject)
         {
             if (detectedObject != null)
@@ -66,6 +119,11 @@ namespace bbiwarg.Recognition.Tracking
                 NumFramesInCurrentState = 1;
         }
 
+        /// <summary>
+        /// Calculates the new tracking state given the new trackableObject.
+        /// </summary>
+        /// <param name="detectedObject">the best fitting trackableObject in the current frame</param>
+        /// <returns>the new TrackingState</returns>
         private TrackingState getNewState(T detectedObject)
         {
             TrackingState newState = TrackingState.Undefined;

bbiwarg/Recognition/Tracking/Tracker.cs

@@ -4,28 +4,59 @@ using bbiwarg.Utility;
 
 namespace bbiwarg.Recognition.Tracking
 {
-    internal abstract class Tracker<T, TrackedT>
+    /// <summary>
+    /// Tracks multiple trackableObjects
+    /// </summary>
+    /// <typeparam name="T">The type of the TrackableObjects</typeparam>
+    /// <typeparam name="TrackedT">The type of the TrackedObject</typeparam>
+    public abstract class Tracker<T, TrackedT>
         where T : TrackableObject
         where TrackedT : TrackedObject<T>
     {
+        /// <summary>
+        /// the size of the input image (used to calculate position similarities)
+        /// </summary>
         private ImageSize imageSize;
+
+        /// <summary>
+        /// list of similarities between trackableObjects and trackedObjects
+        /// </summary>
         private List<Similarity<T, TrackedT>> similarities;
+
+        /// <summary>
+        /// the unique ID generator
+        /// </summary>
         protected TrackIDPool idPool;
 
+        /// <summary>
+        /// the trackedObjects
+        /// </summary>
         public List<TrackedT> TrackedObjects;
 
+
+        /// <summary>
+        /// Initializes a new instance of the Tracker class.
+        /// </summary>
+        /// <param name="imageSize">Size of the input image.</param>
         public Tracker(ImageSize imageSize)
         {
             this.imageSize = imageSize;
             reset();
         }
 
+        /// <summary>
+        /// Resets the idPool and the trackedObjects.
+        /// </summary>
         public void reset()
         {
             idPool = new TrackIDPool();
             TrackedObjects = new List<TrackedT>();
         }
 
+        /// <summary>
+        /// adds new TrackedObjects or updates and removes TrackedObjects with the new trackableObjects
+        /// </summary>
+        /// <param name="detectedObjects">the trackableObjects in the current frame</param>
         protected void trackObjects(List<T> detectedObjects)
         {
             if (TrackedObjects.Count == 0)
@@ -39,6 +70,10 @@ namespace bbiwarg.Recognition.Tracking
             }
         }
 
+        /// <summary>
+        /// Updates the trackedObjects with the detectedObjects in the current frame. Each TrackedObject is assigned the best fitting detectedObject. Each unassigned detectedObject gets a new instance of a TrackedObject, each unassigned TrackedObject gets updated with null.
+        /// </summary>
+        /// <param name="detectedObjects">the trackableObjects in the current frame</param>
         protected void updateTrackedObjects(List<T> detectedObjects)
         {
             List<TrackedT> unassignedTrackedObjects = new List<TrackedT>(TrackedObjects);
@@ -63,6 +98,10 @@ namespace bbiwarg.Recognition.Tracking
             }
         }
 
+        /// <summary>
+        /// creates a new TrackedObject for each trackableObject
+        /// </summary>
+        /// <param name="detectedObjects">the unassigned trackableObjects</param>
         private void addNewTrackedObjects(List<T> detectedObjects)
         {
             foreach (T detectedObject in detectedObjects)
@@ -72,6 +111,10 @@ namespace bbiwarg.Recognition.Tracking
             }
         }
 
+        /// <summary>
+        /// Creates the list of similarities by creating a similarity for each TrackedObject with each detected TrackableObject.
+        /// </summary>
+        /// <param name="detectedObjects">the trackableObjects in the current frame</param>
         private void createSimilarities(List<T> detectedObjects)
         {
             similarities = new List<Similarity<T, TrackedT>>();
@@ -81,19 +124,27 @@ namespace bbiwarg.Recognition.Tracking
                 foreach (T detectedObject in detectedObjects)
                 {
                     float similarityValue = calculateSimilarity(trackedObject, detectedObject);
-                    Similarity<T, TrackedT> similarity = new Similarity<T, TrackedT>(trackedObject, detectedObject, similarityValue);
-                    if (similarity.Value > 0)
-                        similarities.Add(similarity);
-                }
+                    if (similarityValue > 0)
+                        similarities.Add(new Similarity<T, TrackedT>(trackedObject, detectedObject, similarityValue));
+                 }
             }
 
             // sort depending on similarity-value
             similarities.Sort((s1, s2) => s2.Value.CompareTo(s1.Value));
         }
 
+        /// <summary>
+        /// Calculates the similarity [0-1] between a TrackedObject and a TrackableObject.
+        /// </summary>
+        /// <param name="trackedObject">the tracked object</param>
+        /// <param name="detectedObject">the detected trackable object</param>
+        /// <returns></returns>
         public abstract float calculateSimilarity(TrackedT trackedObject, T detectedObject);
 
-
+        /// <summary>
+        /// Removes all similarities with the trackedObject or the same trackableObject as the given similarity.
+        /// </summary>
+        /// <param name="similarity">the similarity of two assigned objects</param>
         private void removeConcurringSimilarities(Similarity<T, TrackedT> similarity)
         {
             for (int i = similarities.Count - 1; i >= 0; i--)
@@ -104,6 +155,9 @@ namespace bbiwarg.Recognition.Tracking
             }
         }
 
+        /// <summary>
+        /// Removes all TrackedObjects, which current state is "delete".
+        /// </summary>
         private void removeDeletableTrackedObjects()
         {
             for (int i = TrackedObjects.Count - 1; i >= 0; i--)
@@ -117,6 +171,11 @@ namespace bbiwarg.Recognition.Tracking
             }
         }
 
+        /// <summary>
+        /// Gets a list of TrackableObjects from all TrackedObjects with the given state.
+        /// </summary>
+        /// <param name="state">the desired tracking state</param>
+        /// <returns>the list of trackableObjects with the given state</returns>
         protected List<T> getCurrentObjectsWithState(TrackingState state)
         {
             List<T> objects = new List<T>();
@@ -128,8 +187,20 @@ namespace bbiwarg.Recognition.Tracking
             return objects;
         }
 
+        /// <summary>
+        /// Creates a new TrackedObject with the given TrackableObject as initial object.
+        /// </summary>
+        /// <param name="detectedObject">the initial trackableObject</param>
+        /// <returns>the TrackedObject</returns>
         protected abstract TrackedT createTrackedObject(T detectedObject);
 
+        /// <summary>
+        /// Calculates a similarity [0-1] between two positions with the given maximum relative distance.
+        /// </summary>
+        /// <param name="p1">the first position</param>
+        /// <param name="p2">the second position</param>
+        /// <param name="maxRelativeDistance">the maximum distance [0-1] relative to the image size (maxAbsoluteDistance = maxRelativeDistance*imageSize.DiagonalLenght)</param>
+        /// <returns>the calculated similarity between the two positions</returns>
         protected float getPositionSimilarity(Vector2D p1, Vector2D p2, float maxRelativeDistance)
         {
             float distance = p1.getDistanceTo(p2);