documented part of Utility

bbiwarg/Input/InputProviding/InputProvider.cs

@@ -102,12 +102,12 @@ namespace bbiwarg.Input.InputProviding
         protected IParameterHandle<int> height;
 
         /// <summary>
-        /// parameter handle for the horizontal field of view
+        /// parameter handle for the horizontal field of view angle
         /// </summary>
         protected IParameterHandle<float> hfov;
 
         /// <summary>
-        /// parameter handle for the vertical field of view
+        /// parameter handle for the vertical field of view angle
         /// </summary>
         protected IParameterHandle<float> vfov;
 
@@ -132,12 +132,12 @@ namespace bbiwarg.Input.InputProviding
         public int ImageHeight { get { return height.Value; } }
 
         /// <summary>
-        /// the horizontal field of view
+        /// the horizontal field of view angle
         /// </summary>
         public float HFOV { get { return hfov.Value; } }
 
         /// <summary>
-        /// the vertical field of view
+        /// the vertical field of view angle
         /// </summary>
         public float VFOV { get { return vfov.Value; } }
 

bbiwarg/Utility/ConvexityDefect.cs

@@ -8,20 +8,55 @@ using Emgu.CV.Structure;
 
 namespace bbiwarg.Utility
 {
+    /// <summary>
+    /// Stores data about and provides functions to work with convexity defects.
+    /// </summary>
     public class ConvexityDefect
     {
+        /// <summary>
+        /// the point of start and end point which is nearer to the depth point
+        /// </summary>
         public Vector2D OuterShort { get; private set; }
+        
+        /// <summary>
+        /// the point of start and end point which is farther away from the depth point
+        /// </summary>
         public Vector2D OuterLong { get; private set; }
+        
+        /// <summary>
+        /// the depth point
+        /// </summary>
         public Vector2D Inner { get; private set; }
+
+        /// <summary>
+        /// vector from Inner to OuterShort
+        /// </summary>
         public Vector2D VectorShort { get; private set; }
+
+        /// <summary>
+        /// vector from Inner to OuterLong
+        /// </summary>
         public Vector2D VectorLong { get; private set; }
+
+        /// <summary>
+        /// line segment from start to end point
+        /// </summary>
         public LineSegment2D OuterLineSegment { get; private set; }
+
+        /// <summary>
+        /// distance from OuterLineSegment to Inner
+        /// </summary>
         public float Depth { get; private set; }
 
-        public ConvexityDefect(MCvConvexityDefect mcvCOnvexityDefect) {
-            Inner = new Vector2D(mcvCOnvexityDefect.DepthPoint);
-            Vector2D p1 = new Vector2D(mcvCOnvexityDefect.StartPoint);
-            Vector2D p2 = new Vector2D(mcvCOnvexityDefect.EndPoint);
+
+        /// <summary>
+        /// Constructs a ConvexityDefect.
+        /// </summary>
+        /// <param name="mcvConvexityDefect">the emgu convexity defect which has start, end and depth point</param>
+        public ConvexityDefect(MCvConvexityDefect mcvConvexityDefect) {
+            Inner = new Vector2D(mcvConvexityDefect.DepthPoint);
+            Vector2D p1 = new Vector2D(mcvConvexityDefect.StartPoint);
+            Vector2D p2 = new Vector2D(mcvConvexityDefect.EndPoint);
 
             if ((p1 - Inner).Length > (p2 - Inner).Length)
             {
@@ -39,6 +74,11 @@ namespace bbiwarg.Utility
             Depth = OuterLineSegment.getDistanceTo(Inner);
         }
 
+        /// <summary>
+        /// Tests if this defect could be the defect near the thumb.
+        /// </summary>
+        /// <param name="thumb">finger representing the thumb</param>
+        /// <returns>true iff this defect is a possible thumb defect</returns>
         public bool isPossibleThumbDefect(Finger thumb) {
             float tipDistance = thumb.TipPoint.getDistanceTo(OuterShort);
             float handDistance = thumb.HandPoint.getDistanceTo(Inner);
@@ -51,6 +91,11 @@ namespace bbiwarg.Utility
                     shortLongLengthRatio <= Parameters.HandThumbDefectMaxShortLongLengthRatio && shortLongLengthRatio >= Parameters.HandThumbDefectMinShortLongLengthRatio);
         }
 
+        /// <summary>
+        /// Tests if this defect is caused by a finger.
+        /// </summary>
+        /// <param name="finger">the finger maybe causing the defect</param>
+        /// <returns>true iff this defect is caused by finger</returns>
         public bool isCausedByFinger(Finger finger) {
             return (OuterLineSegment.intersectsWith(finger.LineSegment));
         }

bbiwarg/Utility/CoordinateConverter.cs

@@ -6,14 +6,43 @@ using System.Threading.Tasks;
 
 namespace bbiwarg.Utility
 {
+    /// <summary>
+    /// Converts between 2d and 3d coordinates.
+    /// </summary>
     public class CoordinateConverter
     {
+        /// <summary>
+        /// size of the image the coordinates are from
+        /// </summary>
         private ImageSize imageSize;
+
+        /// <summary>
+        /// the horizontal field of view angle
+        /// </summary>
         private float hfov;
+
+        /// <summary>
+        /// the vertical field of view angle
+        /// </summary>
         private float vfov;
+
+        /// <summary>
+        /// tangens of hfov / 2
+        /// </summary>
         private float hRatio;
+
+        /// <summary>
+        /// tanges of vfov / 2
+        /// </summary>
         private float vRatio;
 
+
+        /// <summary>
+        /// Constructs a CoordinateConverter.
+        /// </summary>
+        /// <param name="imageSize">size of the image the coordinates are from</param>
+        /// <param name="hfov">horizontal field of view angle</param>
+        /// <param name="vfov">vertical field of view angle</param>
         public CoordinateConverter(ImageSize imageSize, float hfov, float vfov)
         {
             this.imageSize = imageSize;
@@ -24,10 +53,23 @@ namespace bbiwarg.Utility
             vRatio = (float)Math.Tan(vfov / 2);
         }
 
+        /// <summary>
+        /// Converts a point with a depth to a 3d position.
+        /// </summary>
+        /// <param name="p">the point</param>
+        /// <param name="depth">the depth</param>
+        /// <returns>the 3d position</returns>
         public Vector3D convertCoordinate2Dto3D(Vector2D p, float depth) {
             return convertCoordinate2Dto3D(p.X, p.Y, depth);
         }
 
+        /// <summary>
+        /// Converts a position with a depth to a 3d position.
+        /// </summary>
+        /// <param name="x">x coordinate of the position</param>
+        /// <param name="y">y cooridnate of the position</param>
+        /// <param name="depth">the depth</param>
+        /// <returns>the 3d position</returns>
         public Vector3D convertCoordinate2Dto3D(float x, float y, float depth)
         {
             float deltaX = 2 * ((x / imageSize.Width) - 0.5f);
@@ -46,6 +88,12 @@ namespace bbiwarg.Utility
             return new Vector3D(x3, y3, z3);
         }
 
+        /// <summary>
+        /// Converts the length of a 3d linesegment parallel to the camera at the given depth to the length of the linesegment in 2d.
+        /// </summary>
+        /// <param name="length">3d length of the linesegment</param>
+        /// <param name="depth">depth of the linesegment</param>
+        /// <returns>2d length of the linesegment</returns>
         public float convertLength3Dto2D(float length, float depth) {
             float fullLengthX = (float)(2 * Math.Cos(hfov / 2) * depth);
             float fullLengthY = (float)(2 * Math.Cos(vfov / 2) * depth);

bbiwarg/Utility/ImageSize.cs

@@ -7,24 +7,62 @@ using System.Threading.Tasks;
 
 namespace bbiwarg.Utility
 {
+    /// <summary>
+    /// Manages the size of a image.
+    /// </summary>
     public class ImageSize
     {
+        /// <summary>
+        /// image width
+        /// </summary>
         public int Width {get; private set;}
+
+        /// <summary>
+        /// image height
+        /// </summary>
         public int Height {get; private set;}
+
+        /// <summary>
+        /// position in the image with maximum x and y values
+        /// </summary>
         public Vector2D MaxPixel {get; private set;}
+
+        /// <summary>
+        /// the length of the longer image diagonal
+        /// </summary>
         public float DiagonalLength { get { return MaxPixel.Length; } }
+
+        /// <summary>
+        /// number of pixels in the image
+        /// </summary>
         public int NumPixels { get { return Width * Height; } }
 
+
+        /// <summary>
+        /// Constructs a ImageSize.
+        /// </summary>
+        /// <param name="width">image width</param>
+        /// <param name="height">image height</param>
         public ImageSize(int width, int height) {
             Width = width;
             Height = height;
             MaxPixel = new Vector2D(width - 1, height - 1);
         }
 
+        /// <summary>
+        /// Computes an absolute point in the image.
+        /// </summary>
+        /// <param name="relativePoint">realtive point (x and y in [0,1])</param>
+        /// <returns>absolute point</returns>
         public Vector2D getAbsolutePoint(Vector2D relativePoint) {
             return relativePoint.scale(MaxPixel);
         }
 
+        /// <summary>
+        /// Computes a relative point in the image.
+        /// </summary>
+        /// <param name="absolutePoint">absolute point in the image</param>
+        /// <returns>realtive point (x and y in [0,1])</returns>
         public Vector2D getRelativePoint(Vector2D absolutePoint) {
             return new Vector2D(absolutePoint.X / Width, absolutePoint.Y / Height);
         }

bbiwarg/Utility/Kalman2DPositionFilter.cs

@@ -9,14 +9,49 @@ using Emgu.CV.Structure;
 
 namespace bbiwarg.Utility
 {
+    /// <summary>
+    /// Filter used to smooth a series of 2d positions.
+    /// </summary>
     class Kalman2DPositionFilter
     {
+        /// <summary>
+        /// the emgu kalman filter
+        /// </summary>
         private Kalman kalman;
-        private float mXX, mXY, mYY, processNoiseFactor;
+
+        /// <summary>
+        /// xx entry for the measurement noise covariance matrix
+        /// </summary>
+        private float mXX;
+
+        /// <summary>
+        /// xy and yx entry for the measurement noise covariance matrix
+        /// </summary>
+        private float mXY;
+
+        /// <summary>
+        /// yy entry for the measurement noise covariance matrix
+        /// </summary> 
+        private float mYY;
+        
+        /// <summary>
+        /// value used for all entries in the process noise covariance matrix
+        /// </summary>
+        private float processNoiseFactor;
+        
+
+        /// <summary>
+        /// number of measurements per second
+        /// </summary>
         private float fps;
 
+
+        /// <summary>
+        /// true iff the kalman filter is initialized
+        /// </summary>
         public bool Initialized { get; private set; }
 
+
         // state: x, y, v_x, v_y
         //   x: current x position
         //   y: current y position
@@ -24,6 +59,14 @@ namespace bbiwarg.Utility
         // v_y: velocity in y direction
         // a_x: acceleration in x direction
         // a_y: acceleration in y direction
+        /// <summary>
+        /// Creates a Kalman2DPositionFilter.
+        /// </summary>
+        /// <param name="mXX">xx entry for the measurement noise covariance matrix</param>
+        /// <param name="mXY">xy and yx entry for the measurement noise covariance matrix</param>
+        /// <param name="mYY">yy entry for the measurement noise covariance matrix</param>
+        /// <param name="processNoiseFactor">value used for all entries in the process noise covariance matrix</param>
+        /// <param name="fps">number of measurements per second</param>
         public Kalman2DPositionFilter(float mXX, float mXY, float mYY, float processNoiseFactor = 1.0e-4f, int fps = 30)
         {
             this.mXX = mXX;
@@ -34,6 +77,9 @@ namespace bbiwarg.Utility
             reset();
         }
 
+        /// <summary>
+        /// Resets the kalman filter.
+        /// </summary>
         public void reset()
         {
             // 6 state variables and 2 measurements (0 controls)
@@ -77,6 +123,10 @@ namespace bbiwarg.Utility
             Initialized = false;
         }
 
+        /// <summary>
+        /// Sets the initial position.
+        /// </summary>
+        /// <param name="initialPosition">initial position</param>
         public void setInitialPosition(Vector2D initialPosition)
         {
             // initial state (x, y, v_x, v_y)
@@ -86,13 +136,21 @@ namespace bbiwarg.Utility
             Initialized = true;
         }
 
+        /// <summary>
+        /// Computes a prediction for the next position based on the previous positions.
+        /// </summary>
+        /// <returns>prediction for the next position</returns>
         public Vector2D getPrediction()
         {
             Matrix<float> predicton = kalman.Predict();
             return new Vector2D(predicton[0, 0], predicton[1, 0]);
         }
 
-        // updates the filter and returns the corrected position
+        /// <summary>
+        /// Computes a smoothed position for a measurement and updates the filter.
+        /// </summary>
+        /// <param name="rawPosition">the measurement</param>
+        /// <returns>the smoothed position</returns>
         public Vector2D getCorrectedPosition(Vector2D rawPosition)
         {
             Matrix<float> rawPositionMatrix = new Matrix<float>(new float[,]