Merge branch 'master' of https://git.tk.informatik.tu-darmstadt.de/etri-smartspaces

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

bbiwarg/TUIO/TUIO/TuioServer.cs

@@ -11,30 +11,85 @@ using bbiwarg.Utility;
 
 namespace TUIO
 {
+    /// <summary>
+    /// Tuio server class to send tuio cursors and objects to tuio clients.
+    /// </summary>
     class TuioServer
     {
+        /// <summary>
+        /// the maximum packet size
+        /// </summary>
         const int MAX_PACKET_SIZE = 65535 - 8;
 
+
+        /// <summary>
+        /// transmitter to send packages over udp
+        /// </summary>
         private OSCTransmitter transmitter = null;
+
+        /// <summary>
+        /// server ip address
+        /// </summary>
         private String host = "127.0.0.1";
+
+        /// <summary>
+        /// server port
+        /// </summary>
         private int port = 3333;
+
+        /// <summary>
+        /// tuio session id
+        /// </summary>
         private long sessionID = 0;
+
+        /// <summary>
+        /// current tuio time
+        /// </summary>
         private TuioTime currentFrameTime;
 
+
+        /// <summary>
+        /// list of generated cursors
+        /// </summary>
         private List<TuioCursor> cursorList;
+
+        /// <summary>
+        /// list of cursors updated in the current frame
+        /// </summary>
         private List<TuioCursor> updatedCursorList;
 
+
+        /// <summary>
+        /// list of all generated objects
+        /// </summary>
         private List<TuioObject> objectList;
+
+        /// <summary>
+        /// list of objects updated in the current frame
+        /// </summary>
         private List<TuioObject> updatedObjectList;
 
+
+        /// <summary>
+        /// Creates a tuio server with default ip and port.
+        /// </summary>
         public TuioServer() { init(); }
 
+        /// <summary>
+        /// Creates a tuio server with default ip.
+        /// </summary>
+        /// <param name="port">server port</param>
         public TuioServer(int port)
         {
             this.port = port;
             init();
         }
 
+        /// <summary>
+        /// Creates a tuio server.
+        /// </summary>
+        /// <param name="host">server ip</param>
+        /// <param name="port">server port</param>
         public TuioServer(String host, int port)
         {
             this.host = host;
@@ -42,6 +97,9 @@ namespace TUIO
             init();
         }
 
+        /// <summary>
+        /// Initializes the server, cursors and objects.
+        /// </summary>
         private void init()
         {
             TuioTime.initSession();
@@ -50,12 +108,20 @@ namespace TUIO
             transmitter = new OSCTransmitter(host, port);
         }
 
-
+        /// <summary>
+        /// Closes the transmission.
+        /// </summary>
         public void close()
         {
             transmitter.Close();
         }
 
+        /// <summary>
+        /// Adds and returns a tuio cursor.
+        /// </summary>
+        /// <param name="xp">x position of the cursor</param>
+        /// <param name="yp">y position of the cursor</param>
+        /// <returns>the added cursor</returns>
         public TuioCursor addTuioCursor(float xp, float yp)
         {
             TuioCursor tcur = new TuioCursor(sessionID, cursorList.Count, xp, yp);
@@ -66,6 +132,12 @@ namespace TUIO
             return tcur;
         }
 
+        /// <summary>
+        /// Updates a tui cursor.
+        /// </summary>
+        /// <param name="tcur">the cursor to update</param>
+        /// <param name="xp">new x position</param>
+        /// <param name="yp">new y position</param>
         public void updateTuioCursor(TuioCursor tcur, float xp, float yp)
         {
             tcur.update(currentFrameTime, xp, yp);
@@ -73,11 +145,22 @@ namespace TUIO
                 updatedCursorList.Add(tcur);
         }
 
+        /// <summary>
+        /// Removes a tuio cursor.
+        /// </summary>
+        /// <param name="tcur">the cursor to remove</param>
         public void removeTuioCursor(TuioCursor tcur)
         {
             cursorList.Remove(tcur);
         }
 
+        /// <summary>
+        /// Adds and returns tuio object.
+        /// </summary>
+        /// <param name="xp">x position of the object</param>
+        /// <param name="yp">y position of the object</param>
+        /// <param name="angle">angle of the object</param>
+        /// <returns>the added object</returns>
         public TuioObject addTuioObject(float xp, float yp, float angle)
         {
             TuioObject tobj = new TuioObject(sessionID, objectList.Count, xp, yp, angle);
@@ -88,6 +171,12 @@ namespace TUIO
             return tobj;
         }
 
+        /// <summary>
+        /// Updates a tuio object.
+        /// </summary>
+        /// <param name="tobj">the object to update</param>
+        /// <param name="xp">new x position</param>
+        /// <param name="yp">new y position</param>
         public void updateTuioObject(TuioObject tobj, float xp, float yp)
         {
             tobj.update(currentFrameTime, xp, yp);
@@ -95,11 +184,18 @@ namespace TUIO
                 updatedObjectList.Add(tobj);
         }
 
+        /// <summary>
+        /// Removes a tuio object.
+        /// </summary>
+        /// <param name="tobj">the object to remove</param>
         public void removeTuioObject(TuioObject tobj)
         {
             objectList.Remove(tobj);
         }
 
+        /// <summary>
+        /// Initializes cursor and object lists for sending information for a new frame.
+        /// </summary>
         public void initFrame()
         {
             currentFrameTime = TuioTime.getSessionTime();
@@ -107,16 +203,27 @@ namespace TUIO
             updatedObjectList = new List<TuioObject>();
         }
 
+        /// <summary>
+        /// Sends cursors and objects which were updated in the current frame.
+        /// </summary>
         public void commitFrame()
         {
             sendMessage(updatedCursorList, updatedObjectList);
         }
 
+        /// <summary>
+        /// Sends all cursors and objects.
+        /// </summary>
         public void sendFullMessages()
         {
             sendMessage(cursorList, objectList);
         }
 
+        /// <summary>
+        /// Sends cursors and objects.
+        /// </summary>
+        /// <param name="cursorList">list of cursors to send</param>
+        /// <param name="objectList">list of objects to send</param>
         private void sendMessage(List<TuioCursor> cursorList, List<TuioObject> objectList)
         {
             OSCBundle packet = new OSCBundle();
@@ -136,15 +243,6 @@ namespace TUIO
                 currentMessage.Append(tcur.getXSpeed());
                 currentMessage.Append(tcur.getYSpeed());
                 currentMessage.Append(tcur.getMotionAccel());
-
-                /*if (Marshal.SizeOf(packet) + Marshal.SizeOf(currentOscElement) >= MAX_PACKET_SIZE)
-                {
-                    packet.AddElement(new OscElement("/tuio/2Dcur", new Object[] { "fseq", -1 }));
-                    udpwriter.Send(packet);
-
-                    packet = new OscBundle();
-                    addAliveCursorMessagesToBundle(packet);
-                }*/
                 packet.Append(currentMessage);
             }
             currentMessage = new OSCMessage("/tuio/2Dcur");
@@ -185,6 +283,10 @@ namespace TUIO
             transmitter.Send(packet);
         }
 
+        /// <summary>
+        /// Adds a tuio cursor alive message to a packet.
+        /// </summary>
+        /// <param name="packet">packet to add the message to</param>
         private void addAliveCursorMessagesToBundle(OSCBundle packet)
         {
             OSCMessage mssg = new OSCMessage("/tuio/2Dcur");
@@ -196,6 +298,10 @@ namespace TUIO
             packet.Append(mssg);
         }
 
+        /// <summary>
+        /// Adds a tuio object alive message to a packet.
+        /// </summary>
+        /// <param name="packet">packet to add the message to</param>
         private void addAliveObjectMessagesToBundle(OSCBundle packet)
         {
             OSCMessage mssg = new OSCMessage("/tuio/2Dobj");

bbiwarg/TUIO/TuioCommunicator.cs

@@ -13,12 +13,32 @@ using TUIO;
 
 namespace bbiwarg.TUIO
 {
+    /// <summary>
+    /// TuioCommunicator sends generated touch events and palm grid coordinates to tuio clients using a <see cref="TuioServer"/>.
+    /// </summary>
     class TuioCommunicator
     {
+        /// <summary>
+        /// the tuio server
+        /// </summary>
         private TuioServer server;
+
+        /// <summary>
+        /// dictionary of lists of tuio cursors indexed by touch id
+        /// </summary>
         private Dictionary<int, TuioCursor> tcursors;
+
+        /// <summary>
+        /// dictionary of lists of tuio objects indexed by palm id
+        /// </summary>
         private Dictionary<int, List<TuioObject>> tobjects;
 
+
+        /// <summary>
+        /// Constructs a TuioCommunicator.
+        /// </summary>
+        /// <param name="host">server ip</param>
+        /// <param name="port">server port</param>
         public TuioCommunicator(string host, int port)
         {
             server = new TuioServer(host, port);
@@ -26,6 +46,11 @@ namespace bbiwarg.TUIO
             tobjects = new Dictionary<int, List<TuioObject>>();
         }
 
+        /// <summary>
+        /// Handles the event that a new frame is finished processing by updating the cursors and objects and sending them.
+        /// </summary>
+        /// <param name="sender">event sender</param>
+        /// <param name="e">event arguments</param>
         public void handleNewFrameData(object sender, NewProcessedFrameEventArgs e)
         {
             server.initFrame();
@@ -93,11 +118,17 @@ namespace bbiwarg.TUIO
             server.commitFrame();
         }
 
+        /// <summary>
+        /// Closes the server.
+        /// </summary>
         public void close()
         {
             server.close();
         }
 
+        /// <summary>
+        /// Resets the server by removing all cursors and objects.
+        /// </summary>
         public void reset()
         {
             foreach (int id in tcursors.Keys)
@@ -112,6 +143,12 @@ namespace bbiwarg.TUIO
             tobjects.Clear();
         }
 
+        /// <summary>
+        /// Tries to parse an ip address string.
+        /// </summary>
+        /// <param name="ipIn">the ip address string to parse</param>
+        /// <param name="ipOut">out parameter for the ip address in *.*.*.* format if ipIn is valid and null otherwise</param>
+        /// <returns>true iff ipIn is a valid ip address</returns>
         public static bool tryParseIPAddress(String ipIn, out String ipOut)
         {
             IPAddress ipAddress;
@@ -123,6 +160,12 @@ namespace bbiwarg.TUIO
             return result;
         }
 
+        /// <summary>
+        /// Tries to parse a port string.
+        /// </summary>
+        /// <param name="portIn">the port string to parse</param>
+        /// <param name="portOut">out parameter for the port as an Int16 if portIn is valid and undefined otherwise</param>
+        /// <returns>true iff portIn is a valid port</returns>
         public static bool tryParsePort(String portIn, out Int16 portOut)
         {
             return Int16.TryParse(portIn, out portOut);