documented Input

bbiwarg/Input/InputHandling/FrameData.cs

@@ -12,32 +12,83 @@ using bbiwarg.Utility;
 
 namespace bbiwarg.Input.InputHandling
 {
+    /// <summary>
+    /// Data class which holds all data read an generated for one frame.
+    /// </summary>
     public class FrameData
     {
+        /// <summary>
+        /// the id of the frame
+        /// </summary>
         public int FrameID { get; set; }
+
+        /// <summary>
+        /// the size of all the images
+        /// </summary>
         public ImageSize ImageSize { get; set; }
+
+        /// <summary>
+        /// set iff the input source is a movie which is in the first frame again
+        /// </summary>
         public bool ResetFlag { get; set; }
 
-        // images
+        /// <summary>
+        /// the depth image read in this frame
+        /// </summary>
         public DepthImage DepthImage { get; set; }
+
+        /// <summary>
+        /// the edge image created in this frame
+        /// </summary>
         public EdgeImage EdgeImage { get; set; }
+
+        /// <summary>
+        /// the confidence image read in this frame
+        /// </summary>
         public ConfidenceImage ConfidenceImage { get; set; }
 
-        // fingers
+
+        /// <summary>
+        /// a list of fingers detected in this frame
+        /// </summary>
         public List<Finger> DetectedFingers { get; set; }
+        /// <summary>
+        /// a list of fingers which are tracked in this frame
+        /// </summary>
         public List<Finger> TrackedFingers { get; set; }
 
-        // hands
+        
+        /// <summary>
+        /// a list of hands detected in this frame
+        /// </summary>
         public List<Hand> DetectedHands { get; set; }
+        /// <summary>
+        /// a list of hands which are tracked in this frame
+        /// </summary>
         public List<Hand> TrackedHands { get; set; }
 
-        // palms
+        
+        /// <summary>
+        /// a list of plams detected in this frame
+        /// </summary>
         public List<Palm> DetectedPalms { get; set; }
+        /// <summary>
+        /// a list of plams which are tracked in this frame
+        /// </summary>
         public List<Palm> TrackedPalms { get; set; }
 
-        // touch
+        
+        /// <summary>
+        /// a list of <see cref="Touch"/> objects detected in this frame
+        /// </summary>
         public List<Touch> DetectedTouches { get; set; }
+        /// <summary>
+        /// a list of <see cref="Touch"/> objects which are tracked in this frame
+        /// </summary>
         public List<Touch> TrackedTouches { get; set; }
+        /// <summary>
+        /// a list of touch events generated in this frame
+        /// </summary>
         public List<TouchEvent> TouchEvents { get; set; }
 
     }

bbiwarg/Input/InputHandling/InputHandler.cs

@@ -9,39 +9,117 @@ using System;
 
 namespace bbiwarg.Input.InputHandling
 {
+    /// <summary>
+    /// signature for the event that a new frame is finished processing
+    /// </summary>
+    /// <param name="sender">sender of the event</param>
+    /// <param name="e">event parameters</param>
     public delegate void NewProcessedFrameEventHandler(object sender, NewProcessedFrameEventArgs e);
 
-    public class NewProcessedFrameEventArgs
+    /// <summary>
+    /// Encapsulates the arguments for the event of finishing to process a new frame.
+    /// </summary>
+    public class NewProcessedFrameEventArgs: EventArgs
     {
+        /// <summary>
+        /// the data of the processed frame
+        /// </summary>
         public FrameData FrameData { get; private set; }
 
+        /// <summary>
+        /// Creates a new NewProcessedFrameEventArgs with given frame data.
+        /// </summary>
+        /// <param name="frameData">frame data</param>
         public NewProcessedFrameEventArgs(FrameData frameData)
         {
             FrameData = frameData;
         }
     }
 
+    /// <summary>
+    /// Handles new frames by coordinating and delegating the work to the image, detector and tracker classes.
+    /// Also provides an event and the data for the tuio server and the graphical output.
+    /// </summary>
     public class InputHandler
     {
+        /// <summary>
+        /// the input provider which provides the raw data
+        /// </summary>
         private InputProvider inputProvider;
+
+        /// <summary>
+        /// set iff the source is a movie which is in the first frame again
+        /// </summary>
         private bool resetFlag;
 
+
+        /// <summary>
+        /// the finger detector
+        /// </summary>
         private FingerDetector fingerDetector;
+
+        /// <summary>
+        /// the hand detector
+        /// </summary>
         private HandDetector handDetector;
+
+        /// <summary>
+        /// the palm detector
+        /// </summary>
         private PalmDetector palmDetector;
+
+        /// <summary>
+        /// the touch detector
+        /// </summary>
         private TouchDetector touchDetector;
 
+
+        /// <summary>
+        /// the finger tracker
+        /// </summary>
         private FingerTracker fingerTracker;
+
+        /// <summary>
+        /// the hand tracker
+        /// </summary>
         private HandTracker handTracker;
+
+        /// <summary>
+        /// the palm tracker
+        /// </summary>
         private PalmTracker palmTracker;
+
+        /// <summary>
+        /// the touch tracker
+        /// </summary>
         private TouchTracker touchTracker;
 
+
+        /// <summary>
+        /// the size of all images
+        /// </summary>
         public ImageSize ImageSize { get; private set; }
+
+        /// <summary>
+        /// converts 2d and 3d coordinates into each other
+        /// </summary>
         public CoordinateConverter CoordinateConverter { get; private set; }
+
+        /// <summary>
+        /// data for the current frame
+        /// </summary>
         public FrameData FrameData { get; private set; }
 
+
+        /// <summary>
+        /// event which occures, when a new frame is finished processing
+        /// </summary>
         public event NewProcessedFrameEventHandler NewProcessedFrameEvent;
 
+        /// <summary>
+        /// Constructs an InputHandler with an <see cref="InputProvider"/>.
+        /// </summary>
+        /// <param name="inputProvider">the input provider</param>
         public InputHandler(InputProvider inputProvider)
         {
             this.inputProvider = inputProvider;
@@ -53,6 +131,9 @@ namespace bbiwarg.Input.InputHandling
                 videoInputProvider.MovieRestartedEvent += handleMovieRestart;
         }
 
+        /// <summary>
+        /// Initializes all components.
+        /// </summary>
         private void initialize()
         {
             ImageSize = new ImageSize(inputProvider.ImageWidth, inputProvider.ImageHeight);
@@ -70,6 +151,9 @@ namespace bbiwarg.Input.InputHandling
             touchTracker = new TouchTracker(ImageSize);
         }
 
+        /// <summary>
+        /// Resets the trackers.
+        /// </summary>
         public void reset()
         {
             touchTracker.reset();
@@ -78,6 +162,11 @@ namespace bbiwarg.Input.InputHandling
             fingerTracker.reset();
         }
 
+        /// <summary>
+        /// Handles a new frame event by processing the new frame using the image, detector and tracker classes.
+        /// </summary>
+        /// <param name="sender">the sender of the event</param>
+        /// <param name="e">the arguments for the new frame event</param>
         public void handleNewFrame(object sender, NewFrameEventArgs e)
         {
             Timer.start("InputHandler.handleNewFrame");
@@ -158,6 +247,11 @@ namespace bbiwarg.Input.InputHandling
                 Timer.outputAll();
         }
 
+        /// <summary>
+        /// Handles the event of a restart of the movie.
+        /// </summary>
+        /// <param name="sender">the sender of the event</param>
+        /// <param name="e">the event arguments</param>
         private void handleMovieRestart(object sender, EventArgs e)
         {
             reset();

bbiwarg/Input/InputProviding/InputProvider.cs

@@ -8,17 +8,58 @@ using Iisu;
 
 namespace bbiwarg.Input.InputProviding
 {
+    /// <summary>
+    /// signature for the event that the device started
+    /// </summary>
+    /// <param name="sender">sender of the event</param>
+    /// <param name="e">arguments of the event</param>
     public delegate void DeviceStartedEventHandler(object sender, EventArgs e);
+
+    /// <summary>
+    /// signature for the event that a new frame is available
+    /// </summary>
+    /// <param name="sender">sender of the event</param>
+    /// <param name="e">arguments of the event</param>
     public delegate void NewFrameEventHandler(object sender, NewFrameEventArgs e);
 
+    /// <summary>
+    /// Encapsulates the arguments of the event that a new frame is available.
+    /// </summary>
     public class NewFrameEventArgs : EventArgs
     {
+        /// <summary>
+        /// the id of the frame
+        /// </summary>
         public int FrameID { get; private set; }
+
+        /// <summary>
+        /// the with of all images in the frame
+        /// </summary>
         public int Width { get; private set; }
+
+        /// <summary>
+        /// the height of all images in the frame
+        /// </summary>
         public int Height { get; private set; }
+
+        /// <summary>
+        /// pointer to the raw depth data for the frame
+        /// </summary>
         public IntPtr RawDepthData { get; private set; }
+
+        /// <summary>
+        /// pointer to the raw confidence data for the frame
+        /// </summary>
         public IntPtr RawConfidenceData { get; private set; }
 
+        /// <summary>
+        /// Constructs a NewFrameEventArgs.
+        /// </summary>
+        /// <param name="frameID">frame id</param>
+        /// <param name="width">width of all images</param>
+        /// <param name="height">height of all images</param>
+        /// <param name="rawDepthData">pointer to raw depth data</param>
+        /// <param name="rawConfidenceData">pointer to raw confidence data</param>
         public NewFrameEventArgs(int frameID, int width, int height, IntPtr rawDepthData, IntPtr rawConfidenceData)
         {
             FrameID = frameID;
@@ -29,43 +70,119 @@ namespace bbiwarg.Input.InputProviding
         }
     }
 
+    /// <summary>
+    /// InputProvider provides the raw depth and confidence data through an event.
+    /// </summary>
     public class InputProvider
     {
+        /// <summary>
+        /// iisu handle 
+        /// </summary>
         protected IHandle handle;
+
+        /// <summary>
+        /// iisu device from which the data is read
+        /// </summary>
         protected IDevice device;
 
+
+        /// <summary>
+        /// paramter handle for the frame rate
+        /// </summary>
         protected IParameterHandle<float> frameRate;
+
+        /// <summary>
+        /// parameter handle for the image width
+        /// </summary>
         protected IParameterHandle<int> width;
+
+        /// <summary>
+        /// parameter handle for the image height
+        /// </summary>
         protected IParameterHandle<int> height;
+
+        /// <summary>
+        /// parameter handle for the horizontal field of view
+        /// </summary>
         protected IParameterHandle<float> hfov;
+
+        /// <summary>
+        /// parameter handle for the vertical field of view
+        /// </summary>
         protected IParameterHandle<float> vfov;
+
+        /// <summary>
+        /// data handle for the raw depth data
+        /// </summary>
         protected IDataHandle<Iisu.Data.IImageData> depthImage;
-        protected IDataHandle<Iisu.Data.IImageData> confidenceImage;
 
-        protected int lastFrameID;
+        /// <summary>
+        /// data handle for the raw confidence data
+        /// </summary>
+        protected IDataHandle<Iisu.Data.IImageData> confidenceImage;
 
+        /// <summary>
+        /// the width of all images
+        /// </summary>
         public int ImageWidth { get { return width.Value; } }
+
+        /// <summary>
+        /// the height of all images
+        /// </summary>
         public int ImageHeight { get { return height.Value; } }
+
+        /// <summary>
+        /// the horizontal field of view
+        /// </summary>
         public float HFOV { get { return hfov.Value; } }
+
+        /// <summary>
+        /// the vertical field of view
+        /// </summary>
         public float VFOV { get { return vfov.Value; } }
+
+        /// <summary>
+        /// true iff the input source provides data
+        /// </summary>
         public bool IsActive { get; private set; }
+
+        /// <summary>
+        /// the id of the current frame
+        /// </summary>
         public virtual int CurrentFrameID { get { return device.FrameId; } }
 
+
+        /// <summary>
+        /// event that the device started
+        /// </summary>
         public event DeviceStartedEventHandler DeviceStartedEvent;
+
+        /// <summary>
+        /// event that a new frame is available
+        /// </summary>
         public event NewFrameEventHandler NewFrameEvent;
 
+
+        /// <summary>
+        /// Constructs an InputProvider.
+        /// </summary>
         public InputProvider()
         {
             IsActive = false;
-            lastFrameID = -1;
         }
 
+        /// <summary>
+        /// Initializes to device and data handles.
+        /// </summary>
         public void initialize()
         {
             createDevice();
             registerHandles();
         }
 
+        /// <summary>
+        /// Starts the device.
+        /// </summary>
         public void start()
         {
             device.Start();
@@ -77,12 +194,18 @@ namespace bbiwarg.Input.InputProviding
             run();
         }
 
+        /// <summary>
+        /// Stops the device.
+        /// </summary>
         public void stop()
         {
             IsActive = false;
             device.Stop(true);
         }
 
+        /// <summary>
+        /// Creates an iisu device which provides the data.
+        /// </summary>
         protected void createDevice()
         {
             handle = Iisu.Iisu.Context.CreateHandle();
@@ -90,6 +213,10 @@ namespace bbiwarg.Input.InputProviding
             device = handle.InitializeDevice(conf);
         }
 
+        /// <summary>
+        /// Returns an iisu device configuration.
+        /// </summary>
+        /// <returns>iisu device configuration</returns>
         protected virtual IDeviceConfiguration createDeviceConfiguration()
         {
             IDeviceConfiguration conf = handle.CreateDeviceConfiguration();
@@ -97,6 +224,9 @@ namespace bbiwarg.Input.InputProviding
             return conf;
         }
 
+        /// <summary>
+        /// Registers all parameter and data handles.
+        /// </summary>
         protected virtual void registerHandles()
         {
             width = device.RegisterParameterHandle<int>("SOURCE.CAMERA.DEPTH.Width");
@@ -109,12 +239,18 @@ namespace bbiwarg.Input.InputProviding
             confidenceImage = device.RegisterDataHandle<Iisu.Data.IImageData>("SOURCE.CAMERA.CONFIDENCE.Image");
         }
 
+        /// <summary>
+        /// Provides the main loop for reading data from the device.
+        /// </summary>
         protected virtual void run()
         {
             while (IsActive)
                 nextFrame();
         }
 
+        /// <summary>
+        /// Gets the next frame from the device.
+        /// </summary>
         protected virtual void nextFrame()
         {
             device.UpdateFrame(true);
@@ -122,6 +258,9 @@ namespace bbiwarg.Input.InputProviding
             device.ReleaseFrame();
         }
 
+        /// <summary>
+        /// Triggers the new frame event.
+        /// </summary>
         protected void provideNewFrame()
         {
             if (NewFrameEvent != null)

bbiwarg/Input/InputProviding/VideoInputProvider.cs

@@ -8,25 +8,69 @@ using bbiwarg.Utility;
 
 namespace bbiwarg.Input.InputProviding
 {
+    /// <summary>
+    /// signature for the event that the movie has restarted
+    /// </summary>
+    /// <param name="sender">event sender</param>
+    /// <param name="e">event arguments</param>
     public delegate void MovieRestartedEventHandler(object sender, EventArgs e);
 
+    /// <summary>
+    /// VideoInputProvider provides the raw depth and confidence data read from a video file.
+    /// </summary>
     class VideoInputProvider : InputProvider
     {
+        /// <summary>
+        /// parameter handle for the current frame of the movie
+        /// </summary>
         private IParameterHandle<int> currentMovieFrame;
+
+        /// <summary>
+        /// parameter handle for the number of frames in the movie
+        /// </summary>
         private IParameterHandle<int> frameCount;
+
+        /// <summary>
+        /// parameter handle for the play step, which is the value that gets added to the current frame in each iteration
+        /// </summary>
         private IParameterHandle<int> playStep;
 
+
+        /// <summary>
+        /// the id of the current frame
+        /// </summary>
         public override int CurrentFrameID { get { return currentMovieFrame.Value; } }
+
+        /// <summary>
+        /// the path to the movie file
+        /// </summary>
         public String MoviePath { get; private set; }
+
+        /// <summary>
+        /// true iff the movie is paused
+        /// </summary>
         public bool IsPaused { get; private set; }
 
+
+        /// <summary>
+        /// event that the movie has restarted
+        /// </summary>
         public event MovieRestartedEventHandler MovieRestartedEvent;
 
+
+        /// <summary>
+        /// Constructs a VideoInputProvider.
+        /// </summary>
+        /// <param name="moviePath">path to the movie file</param>
         public VideoInputProvider(String moviePath)
         {
             MoviePath = moviePath;
         }
 
+        /// <summary>
+        /// Returns an iisu device configuration, which uses the movie to read the data.
+        /// </summary>
+        /// <returns>iisu device configuration</returns>
         protected override IDeviceConfiguration createDeviceConfiguration()
         {
             IDeviceConfiguration conf = base.createDeviceConfiguration();
@@ -34,6 +78,9 @@ namespace bbiwarg.Input.InputProviding
             return conf;
         }
 
+        /// <summary>
+        /// Registers all parameter and data handles.
+        /// </summary>
         protected override void registerHandles()
         {
             base.registerHandles();
@@ -44,21 +91,33 @@ namespace bbiwarg.Input.InputProviding
             playStep = device.RegisterParameterHandle<int>("SOURCE.MOVIE.PlayStep");
         }
 
+        /// <summary>
+        /// Pauses the movie. No data is read anymore.
+        /// </summary>
         public void pause()
         {
             IsPaused = true;
         }
 
+        /// <summary>
+        /// Resumes playing the movie and reading data.
+        /// </summary>
         public void play()
         {
             IsPaused = false;
         }
 
+        /// <summary>
+        /// Jumps to the next movie frame.
+        /// </summary>
         public void goToNextFrame()
         {
             nextFrame();
         }
 
+        /// <summary>
+        /// Jumps to the previous movie frame.
+        /// </summary>
         public void goToPreviousFrame()
         {
             playStep.Value = -1;
@@ -66,6 +125,9 @@ namespace bbiwarg.Input.InputProviding
             playStep.Value = 1;
         }
 
+        /// <summary>
+        /// Provides the main loop for reading data from the video file.
+        /// </summary>
         protected override void run() {
             while (IsActive) {
                 if (!IsPaused)
@@ -75,13 +137,15 @@ namespace bbiwarg.Input.InputProviding
             }
         }
 
+        /// <summary>
+        /// Gets the next frame from the device and triggers an event if the movie has restarted.
+        /// </summary>
         protected override void nextFrame()
         {
             base.nextFrame();
 
             if(CurrentFrameID == 0 && MovieRestartedEvent != null)
                 MovieRestartedEvent(this, new EventArgs());
-
         }
     }
 }