documented Recognition.FingerRecognition

bbiwarg/Recognition/FingerRecognition/Finger.cs

@@ -14,27 +14,74 @@ using Emgu.CV;
 
 namespace bbiwarg.Recognition.FingerRecognition
 {
+    /// <summary>
+    /// The Finger class represents a Finger.
+    /// </summary>
     public class Finger : TrackableObject
     {
+        /// <summary>
+        /// the position of the finger tip
+        /// </summary>
         public Vector2D TipPoint { get { return SliceTrail.StartSlice.Mid; } }
+
+        /// <summary>
+        /// the position of the finger end (hand)
+        /// </summary>
         public Vector2D HandPoint { get { return SliceTrail.EndSlice.Mid; } }
+
+        /// <summary>
+        /// a position in the middle of the finger
+        /// </summary>
         public Vector2D MidPoint { get { return SliceTrail.MidSlice.Mid; } }
+
+        /// <summary>
+        /// the direction of the finger (end to start)
+        /// </summary>
         public Vector2D Direction { get { return SliceTrail.FittedDirection; } }
+
+        /// <summary>
+        /// the line segment from start to end
+        /// </summary>
         public LineSegment2D LineSegment { get { return SliceTrail.LineSegment; } }
+
+        /// <summary>
+        /// the finger slices
+        /// </summary>
         public FingerSliceTrail SliceTrail { get; private set; }
+
+        /// <summary>
+        /// the hand the finger belongs to
+        /// </summary>
         public Hand Hand { get; set; }
+
+        /// <summary>
+        /// the touch of the current finger
+        /// </summary>
         public Touch Touch { get; set; }
 
+
+        /// <summary>
+        /// Initializes a new instance of the Finger class.
+        /// </summary>
+        /// <param name="sliceTrail">The finger slice trail.</param>
         public Finger(FingerSliceTrail sliceTrail)
             : base()
         {
             SliceTrail = sliceTrail;
         }
 
+        /// <summary>
+        /// Reverses the finger (start<->end)
+        /// </summary>
         public void reverse() {
             SliceTrail.reverse();
         }
 
+        /// <summary>
+        /// Gets a contour of the finger
+        /// </summary>
+        /// <param name="margin">the margin around the finger (distance in pixels)</param>
+        /// <returns>the contour of the finger</returns>
         public Contour<Point> getContour(float margin) {
             return SliceTrail.getContour(margin);
         }

bbiwarg/Recognition/FingerRecognition/FingerDetector.cs

@@ -13,18 +13,48 @@ using Emgu.CV;
 
 namespace bbiwarg.Recognition.FingerRecognition
 {
+    /// <summary>
+    /// Detects fingers in the given depth and edge images. The finger detection searches for edges in the edge image and tries to find an initial finger slice. For each found finger slice, the finger detector tries to move along the finger direction to extend the finger slice trail. If the trail reaches its end, the finger detector removes the first few slices and starts the trail expansion in opposite direction. If the complete slice trail is long enough, the finger slices are sorted into correct order and the edges around the finger are removed to increase performance for the next finger detection.
+    /// </summary>
     class FingerDetector
     {
+        /// <summary>
+        /// the coordinateConverter (used to calculate finger width (in milimeters))
+        /// </summary>
         private CoordinateConverter coordinateConverter;
+
+        /// <summary>
+        /// the current depthImage
+        /// </summary>
         private DepthImage depthImage;
+
+        /// <summary>
+        /// the current edge image in its original form
+        /// </summary>
         private EdgeImage edgeImageOriginal;
+
+        /// <summary>
+        /// the current edge image in its adapted form (edges around detected fingers will be removed)
+        /// </summary>
         private EdgeImage edgeImageAdapted;
+
+        /// <summary>
+        /// the detected fingers
+        /// </summary>
         private List<Finger> fingers;
 
+        /// <summary>
+        /// Initializes a new instance of the FingerDetector class.
+        /// </summary>
+        /// <param name="coordinateConverter">The coordinate converter.</param>
         public FingerDetector(CoordinateConverter coordinateConverter) {
             this.coordinateConverter = coordinateConverter;
         }
-
+        
+        /// <summary>
+        /// Detects fingers in the current frame using the depth and edge image. Afterwards the detected fingers are stored in the given frame data (detectedFingers).
+        /// </summary>
+        /// <param name="frameData">the current frame</param>
         public void detectFingers(FrameData frameData)
         {
             depthImage = frameData.DepthImage;
@@ -67,6 +97,11 @@ namespace bbiwarg.Recognition.FingerRecognition
             frameData.DetectedFingers = fingers;
         }
 
+        /// <summary>
+        /// Gets the edge direction of the given edge point. The edge direction is either horizontal, vertical, diagonal (both) or null.
+        /// </summary>
+        /// <param name="edgePoint">the edge point</param>
+        /// <returns>the edge directon at the given point</returns>
         private Vector2D getEdgeDirection(Vector2D edgePoint)
         {
             int x = edgePoint.IntX;
@@ -79,6 +114,12 @@ namespace bbiwarg.Recognition.FingerRecognition
             else return null;
         }
 
+        /// <summary>
+        /// Creates a new FingerSliceTrail and expands it along its direction.
+        /// </summary>
+        /// <param name="startSlice">the initial finger slice</param>
+        /// <param name="startDirection">the initial finger direction</param>
+        /// <returns>the found FingerSliceTrail or null</returns>
         private FingerSliceTrail findFingerSliceTrail(FingerSlice startSlice, Vector2D startDirection)
         {
             FingerSliceTrail trail = new FingerSliceTrail(startSlice);
@@ -105,6 +146,12 @@ namespace bbiwarg.Recognition.FingerRecognition
             return null;
         }
 
+        /// <summary>
+        ///  Tries to expand a trail along its direction.
+        /// </summary>
+        /// <param name="trail">the given finger slice trail</param>
+        /// <param name="reversed">indicates in which direction the trail should be expanded</param>
+        /// <returns>the expanded finger slice trail</returns>
         private FingerSliceTrail expandTrail(FingerSliceTrail trail, bool reversed = false)
         {
             if (reversed)
@@ -146,6 +193,13 @@ namespace bbiwarg.Recognition.FingerRecognition
             return trail;
         }
 
+        /// <summary>
+        /// Tries to find a finger slice from a given position by searching in both orthogonal directions for an edge.
+        /// </summary>
+        /// <param name="position">the position somewhere in the middle of the possible finger</param>
+        /// <param name="direction">the finger direction</param>
+        /// <param name="reversed">indicates wether start and end should be swapped</param>
+        /// <returns>the found finger slice or null</returns>
         private FingerSlice findFingerSliceFromMid(Vector2D position, Vector2D direction, bool reversed = false)
         {
             if (edgeImageAdapted.isRoughEdgeAt(position)) return null;
@@ -171,6 +225,12 @@ namespace bbiwarg.Recognition.FingerRecognition
             return slice;
         }
 
+        /// <summary>
+        /// Tries to find a finger slice from one point towards the given direction (searches for an edge).
+        /// </summary>
+        /// <param name="start">the start position</param>
+        /// <param name="direction">the slice direction</param>
+        /// <returns>the found finger slice or null</returns>
         private FingerSlice findFingerSliceFromStartEdge(Vector2D start, Vector2D direction)
         {
             Vector2D searchStart = start + Parameters.FingerMinWidth2D * direction;
@@ -189,6 +249,11 @@ namespace bbiwarg.Recognition.FingerRecognition
             return slice;
         }
 
+        /// <summary>
+        /// Checks if a possible finger slice is located on a finger. To pass this test, the depth value at the mid has to be lower than on the outside (start and end).
+        /// </summary>
+        /// <param name="slice">the possible finger slcie</param>
+        /// <returns>wether the slice is located on a finger</returns>
         private bool fingerSliceDepthTest(FingerSlice slice)
         {
             Int16 depthStart = depthImage.getDepthAt(slice.Start.moveWithinBound(depthImage.Size, slice.Direction.getInverse(), Parameters.FingerContourMargin));
@@ -197,6 +262,10 @@ namespace bbiwarg.Recognition.FingerRecognition
             return (depthStart > depthMid && depthMid < depthEnd);
         }
 
+        /// <summary>
+        /// Sorts the finger slices in correct order an checks if the finger is a valid finger (<see cref="isCrippleFinger(Finger)"/>). If it is valid the finger is added to the list of detected fingers. Afterwards the edges around the finger are removed to surpress a new finger search for the same finger.
+        /// </summary>
+        /// <param name="trail">the slice trail of the possible finger</param>
         private void createFingerFromTrail(FingerSliceTrail trail)
         {
             //bring finger in correct direction Tip->Hand
@@ -213,6 +282,11 @@ namespace bbiwarg.Recognition.FingerRecognition
             edgeImageAdapted.removeEdgesInsidePolygon(finger.getContour(Parameters.FingerContourMargin).ToArray());
         }
 
+        /// <summary>
+        /// Checks wether the finger has enough space around itself (fingers from a closed hand shouldn't bee detected).
+        /// </summary>
+        /// <param name="finger">the finger</param>
+        /// <returns>wether the finger has enough space around itself</returns>
         private bool isCrippleFinger(Finger finger)
         {
             FingerSlice midSlice = finger.SliceTrail.MidSlice;
@@ -227,7 +301,11 @@ namespace bbiwarg.Recognition.FingerRecognition
             return (minDepthDifference < Parameters.FingerMaxCrippleDifference);
         }
 
-
+        /// <summary>
+        /// Sorts a slice trail in the corrent order, so that the start is at the finger tip and the end is at the hand. To guess the correct order the width of the first and last slice are compared.
+        /// </summary>
+        /// <param name="trail">the slice trail of the finger</param>
+        /// <returns>the slice trail of the finger in correct order</returns>
         private FingerSliceTrail orderTrailTipToHand(FingerSliceTrail trail)
         {
             float startLength = trail.StartSlice.Length;

bbiwarg/Recognition/FingerRecognition/FingerSlice.cs

@@ -7,15 +7,47 @@ using bbiwarg.Utility;
 
 namespace bbiwarg.Recognition.FingerRecognition
 {
+    /// <summary>
+    /// A Finger consists of multiple FingerSlices, each one represented by a line preferrably orthogonal to the fingers direction.
+    /// </summary>
     public class FingerSlice
     {
+        /// <summary>
+        /// the point in the middle of the slice
+        /// </summary>
         public Vector2D Mid { get; private set; }
+
+        /// <summary>
+        /// the start point of the slice
+        /// </summary>
         public Vector2D Start { get; private set; }
+
+        /// <summary>
+        /// the end point of the slice
+        /// </summary>
         public Vector2D End { get; private set; }
+
+        /// <summary>
+        /// the line segment connecting start and end
+        /// </summary>
         public LineSegment2D LineSegment { get; private set; }
+
+        /// <summary>
+        /// the direction of the slice
+        /// </summary>
         public Vector2D Direction { get { return LineSegment.Direction; } }
+
+        /// <summary>
+        /// the length of the slice (in pixels)
+        /// </summary>
         public float Length { get { return LineSegment.Length; } }
 
+
+        /// <summary>
+        /// Initializes a new instance of the FingerSlice class.
+        /// </summary>
+        /// <param name="start">The start point</param>
+        /// <param name="end">The end point</param>
         public FingerSlice(Vector2D start, Vector2D end)
         {
             Start = start;

bbiwarg/Recognition/FingerRecognition/FingerSliceTrail.cs

@@ -9,22 +9,78 @@ using Emgu.CV;
 
 namespace bbiwarg.Recognition.FingerRecognition
 {
+    /// <summary>
+    /// Each Finger consists of multiple FingerSlices, a FingerSliceTrail is a collection of these slices.
+    /// </summary>
     public class FingerSliceTrail
     {
+        /// <summary>
+        /// the line segment connection the first slice's mid to the last slice's mid
+        /// </summary>
         private LineSegment2D lineSegment;
+
+        /// <summary>
+        /// the fitted direction through all slice's mid points [end to start]
+        /// </summary>
         private Vector2D fittedDirection;
+
+        /// <summary>
+        /// indicates wether the variable lineSegment is up to date (outdates if new start or end slices are added)
+        /// </summary>
         private bool lineSegmentUpToDate;
+
+        /// <summary>
+        /// indicates weter the variable fittedDirection is up to date (outdates if new slices are added)
+        /// </summary>
         private bool fittedDirectionUpToDate;
 
+        /// <summary>
+        /// the finger slices
+        /// </summary>
         public List<FingerSlice> Slices { get; private set; }
+
+        /// <summary>
+        /// the first slice
+        /// </summary>
         public FingerSlice StartSlice { get { return Slices[0]; } }
+
+        /// <summary>
+        /// the middle slice
+        /// </summary>
         public FingerSlice MidSlice { get { return Slices[NumSlices / 2]; } }
+
+        /// <summary>
+        /// the last slice
+        /// </summary>
         public FingerSlice EndSlice { get { return Slices[Slices.Count - 1]; } }
+
+        /// <summary>
+        /// The slice at the given index.
+        /// </summary>
+        /// <param name="index">the index</param>
+        /// <returns>the slice at the given index</returns>
         public FingerSlice this[int index] { get { return Slices[index]; } }
+
+        /// <summary>
+        /// the number of slices
+        /// </summary>
         public int NumSlices { get { return Slices.Count; } }
+
+        /// <summary>
+        /// the line segment connecting the start slice's mid to the end slice's mid
+        /// </summary>
         public LineSegment2D LineSegment { get { if (!lineSegmentUpToDate) updateLineSegment(); return lineSegment; } }
+
+        /// <summary>
+        /// the fitted direction through all slice's mid points [end to start]
+        /// </summary>
         public Vector2D FittedDirection { get { if (!fittedDirectionUpToDate) updateFittedDirection(); return fittedDirection; } }
 
+
+        /// <summary>
+        /// Initializes a new instance of the FingerSliceTrail class.
+        /// </summary>
+        /// <param name="slice">The initial slice.</param>
         public FingerSliceTrail(FingerSlice slice)
         {
             Slices = new List<FingerSlice>();
@@ -33,6 +89,10 @@ namespace bbiwarg.Recognition.FingerRecognition
             fittedDirectionUpToDate = false;
         }
 
+        /// <summary>
+        /// Adds a slice to the end of the slice trail and outdates the lineSegment and fittedDirection.
+        /// </summary>
+        /// <param name="slice">the slice that should be added</param>
         public void addSlice(FingerSlice slice)
         {
             Slices.Add(slice);
@@ -40,18 +100,30 @@ namespace bbiwarg.Recognition.FingerRecognition
             fittedDirectionUpToDate = false;
         }
 
+        /// <summary>
+        /// Calculates the direction of the first few slices
+        /// </summary>
+        /// <returns>the start direction (pointing direction)</returns>
         public Vector2D getStartDirection()
         {
             int innerStartIndex = Math.Min(NumSlices - 1, Parameters.FingerNumSlicesForRelativeDirection);
             return (StartSlice.Mid - Slices[innerStartIndex].Mid).normalize();
         }
 
+        /// <summary>
+        /// Calculates the direction of the last few slices.
+        /// </summary>
+        /// <returns>the end direction (direction towards hand)</returns>
         public Vector2D getEndDirection()
         {
             int innerEndIndex = Math.Max(0, NumSlices - Parameters.FingerNumSlicesForRelativeDirection);
             return (EndSlice.Mid - Slices[innerEndIndex].Mid).normalize();
         }
 
+        /// <summary>
+        /// Removes the first few slices.
+        /// </summary>
+        /// <param name="numSlices">the number of slices that should be removed</param>
         public void removeFirstSlices(int numSlices)
         {
             Slices.RemoveRange(0, numSlices);
@@ -59,13 +131,25 @@ namespace bbiwarg.Recognition.FingerRecognition
             fittedDirectionUpToDate = false;
         }
 
+        /// <summary>
+        /// Reverses the trail and updates the line segment and the fitted direction
+        /// </summary>
         public void reverse()
         {
             Slices.Reverse();
-            lineSegmentUpToDate = false;
-            fittedDirectionUpToDate = false;
+
+            if(lineSegmentUpToDate)
+                lineSegment = new LineSegment2D(lineSegment.P2, lineSegment.P1);
+
+            if (fittedDirectionUpToDate)
+                fittedDirection = fittedDirection.getInverse();
         }
 
+        /// <summary>
+        /// Gets the contour of the finger with a given margin
+        /// </summary>
+        /// <param name="margin">the margin around the finger (in pixels)</param>
+        /// <returns>the contour of the finger</returns>
         public Contour<Point> getContour(float margin)
         {
             List<Point> pointsA = new List<Point>();
@@ -86,12 +170,18 @@ namespace bbiwarg.Recognition.FingerRecognition
             return contour;
         }
 
+        /// <summary>
+        /// updtes the line segment (new line segment from end to start)
+        /// </summary>
         private void updateLineSegment()
         {
             lineSegment = new LineSegment2D(EndSlice.Mid, StartSlice.Mid);
             lineSegmentUpToDate = true;
         }
 
+        /// <summary>
+        /// updates the fitted direction (line fitting through all slices mid points)
+        /// </summary>
         private void updateFittedDirection()
         {
             List<PointF> midPoints = new List<PointF>();

bbiwarg/Recognition/FingerRecognition/FingerTracker.cs

@@ -9,18 +9,35 @@ using bbiwarg.Input.InputHandling;
 
 namespace bbiwarg.Recognition.FingerRecognition
 {
+    /// <summary>
+    /// Tracks fingers over  multiple frames.
+    /// </summary>
     class FingerTracker : Tracker<Finger, TrackedFinger>
     {
+        /// <summary>
+        /// Initializes a new instance of the FingerTracker class.
+        /// </summary>
+        /// <param name="imageSize">Size of the input image.</param>
         public FingerTracker(ImageSize imageSize)
             : base(imageSize)
         {
         }
 
+        /// <summary>
+        /// Updates the TrackedFingers with the detected fingers in the current frame and stores the tracked fingers.
+        /// </summary>
+        /// <param name="frameData">the current frame</param>
         public void trackFingers(FrameData frameData) {
             trackObjects(frameData.DetectedFingers);
             frameData.TrackedFingers = getCurrentObjectsWithState(TrackingState.Tracked);
         }
 
+        /// <summary>
+        /// Calculates the similarity [0-1] of a tracked Finger and a detected finger 
+        /// </summary>
+        /// <param name="trackedFinger">the tracked finger</param>
+        /// <param name="detectedFinger">the detected finger</param>
+        /// <returns>the similarity between both fingers</returns>
         public override float calculateSimilarity(TrackedFinger trackedFinger, Finger detectedFinger)
         {
             Vector2D tip, hand;
@@ -41,6 +58,11 @@ namespace bbiwarg.Recognition.FingerRecognition
             return tipPointSimilarity * handPointSimilarity;
         }
 
+        /// <summary>
+        /// Creates a TrackedFinger.
+        /// </summary>
+        /// <param name="detectedObject">The detected finger.</param>
+        /// <returns>a TrackedFinger</returns>
         protected override TrackedFinger createTrackedObject(Finger detectedObject)
         {
             return new TrackedFinger(idPool.getNextUnusedID(), detectedObject, Parameters.FingerTrackerNumFramesDetectedUntilTracked, Parameters.FingerTrackerNumFramesLostUntilDeleted);

bbiwarg/Recognition/FingerRecognition/TrackedFinger.cs

@@ -8,16 +8,49 @@ using bbiwarg.Utility;
 
 namespace bbiwarg.Recognition.FingerRecognition
 {
+    /// <summary>
+    /// Represents a finger that is tracked for several frames.
+    /// </summary>
     class TrackedFinger : TrackedObject<Finger>
     {
+        /// <summary>
+        /// the kalman filter for the tip point
+        /// </summary>
         private Kalman2DPositionFilter tipPointKalman;
+
+        /// <summary>
+        /// the kalman filter for the hand point
+        /// </summary>
         private Kalman2DPositionFilter handPointKalman;
+
+        /// <summary>
+        /// list of last directions (used to correct finger directions if they differ from average)
+        /// </summary>
         private List<Vector2D> lastRawDirections;
 
+        /// <summary>
+        /// predicted position of the tip point
+        /// </summary>
         public Vector2D TipPointPrediction { get { return tipPointKalman.getPrediction(); } }
+
+        /// <summary>
+        /// predicted position of the hand point
+        /// </summary>
         public Vector2D HandPointPrediction { get { return handPointKalman.getPrediction(); } }
+
+        /// <summary>
+        /// the average direction of the last fingers
+        /// </summary>
         public Vector2D MeanDirection { get { return Vector2D.mean(lastRawDirections); } }
 
+
+        /// <summary>
+        /// Initializes a new instance of the TrackedFinger class.
+        /// </summary>
+        /// <param name="id">The track ID.</param>
+        /// <param name="detectedFinger">The initial detected finger.</param>
+        /// <param name="numFramesDetectedUntilTracked">The number of consecutive frames detected until the finger is considered to be tracked.</param>
+        /// <param name="numFramesLostUntilDeleted">The number of consecutive frames lost until the finger is considered to be deleted.</param>
         public TrackedFinger(int id, Finger detectedFinger, int numFramesDetectedUntilTracked, int numFramesLostUntilDeleted)
             : base(id, detectedFinger, numFramesDetectedUntilTracked, numFramesLostUntilDeleted)
         {
@@ -30,6 +63,10 @@ namespace bbiwarg.Recognition.FingerRecognition
             logStateChange();
         }
 
+        /// <summary>
+        /// Updates the tracked finger with its best match in the current frame, logs the state change, corrects the finger's direction if needed and updates the position predictions (kalman filters).
+        /// </summary>
+        /// <param name="detectedFinger">The detected finger.</param>
         public override void updateFrame(Finger detectedFinger)
         {
             base.updateFrame(detectedFinger);
@@ -51,12 +88,20 @@ namespace bbiwarg.Recognition.FingerRecognition
             }
         }
 
+        /// <summary>
+        /// Indicates wether a newly detected finger should be reverse (direction differs from average direction of previous fingers).
+        /// </summary>
+        /// <param name="detectedFinger">the detected finger</param>
+        /// <returns>wether the fingers direction matches to the direction of the previous fingers</returns>
         public bool shouldFingerBeReversed(Finger detectedFinger)
         {
             Vector2D meanDirection = Vector2D.mean(lastRawDirections);
             return meanDirection.isInOppositeDirection(detectedFinger.Direction);
         }
 
+        /// <summary>
+        /// logs the state change
+        /// </summary>
         private void logStateChange()
         {
             String stateAsString = CurrentState.ToString().ToLower();

bbiwarg/Recognition/Tracking/Tracker.cs

@@ -138,7 +138,7 @@ namespace bbiwarg.Recognition.Tracking
         /// </summary>
         /// <param name="trackedObject">the tracked object</param>
         /// <param name="detectedObject">the detected trackable object</param>
-        /// <returns></returns>
+        /// <returns>the smiliarity [0-1]</returns>
         public abstract float calculateSimilarity(TrackedT trackedObject, T detectedObject);
 
         /// <summary>