--- a/c/Parameters.cpp	Mon May 05 23:17:19 2014 -0400
+++ b/c/Parameters.cpp	Mon May 05 23:17:46 2014 -0400
@@ -36,27 +36,28 @@
     ("frame1", po::value<unsigned int>(&frame1), "first frame to process")
     ("nframes", po::value<int>(&nFrames), "number of frame to process")
     // feature tracking
-    ("max-nfeatures", po::value<int>(&maxNFeatures), "maximum number of features added at each frame")
-    ("feature-quality", po::value<float>(&featureQuality), "quality level of the good features to track")
-    ("min-feature-distanceklt", po::value<float>(&minFeatureDistanceKLT), "minimum distance between features")
-    ("window-size", po::value<int>(&windowSize), "size of the search window at each pyramid level")
+    ("max-nfeatures", po::value<int>(&maxNFeatures), "maximum number of features added at each frame (1000s)")
+    ("feature-quality", po::value<float>(&featureQuality), "quality level of the good features to track (]0. 1?])")
+    ("min-feature-distanceklt", po::value<float>(&minFeatureDistanceKLT), "minimum distance between features (]0. 10?])")
+    ("block-size", po::value<int>(&blockSize), "size of the block for feature characteristics ([1 ?])")
     ("use-harris-detector", po::value<bool>(&useHarrisDetector), "use of Harris corner detector")
     ("k", po::value<float>(&k), "k parameter to detect good features to track (OpenCV)")
-    ("pyramid-level", po::value<int>(&pyramidLevel), "maximal pyramid level in the feature tracking algorithm")
-    ("ndisplacements", po::value<unsigned int>(&nDisplacements), "number of displacement to test minimum feature motion")
-    ("min-feature-displacement", po::value<float>(&minFeatureDisplacement), "minimum displacement to keep features")
-    ("acceleration-bound", po::value<float>(&accelerationBound), "maximum feature acceleration")
-    ("deviation-bound", po::value<float>(&deviationBound), "maximum feature deviation")
-    ("smoothing-halfwidth", po::value<int>(&nFramesSmoothing), "number of frames to smooth positions (half window)")
-    ("max-number-iterations", po::value<int>(&maxNumberTrackingIterations), "maximum number of iterations to stop feature tracking")
-    ("min-tracking-error", po::value<float>(&minTrackingError), "minimum error to reach to stop feature tracking")
-    ("min-feature-eig-threshold", po::value<float>(&minFeatureEigThreshold)->default_value(1e-4), "minimum eigen value of a 2x2 normal matrix of optical flow equations")
-    ("min-feature-time", po::value<unsigned int>(&minFeatureTime), "minimum length of a feature (number of frames) to consider a feature for grouping")
-    ("mm-connection-distance", po::value<float>(&mmConnectionDistance), "connection distance in feature grouping")
-    ("mm-segmentation-distance", po::value<float>(&mmSegmentationDistance), "segmentation distance in feature grouping")
-    ("max-distance", po::value<float>(&maxDistance), "maximum distance between features for grouping")
-    ("min-velocity-cosine", po::value<float>(&minVelocityCosine), "minimum cosine of the angle between the velocity vectors for grouping")
-    ("min-nfeatures-group", po::value<float>(&minNFeaturesPerGroup), "minimum average number of features per frame to create a vehicle hypothesis")
+    ("window-size", po::value<int>(&windowSize), "size of the search window at each pyramid level ([1 ?])")
+    ("pyramid-level", po::value<int>(&pyramidLevel), "maximal pyramid level in the feature tracking algorithm ([0 maxLevel=5?])")
+    ("ndisplacements", po::value<unsigned int>(&nDisplacements), "number of displacements to test minimum feature motion ([2 4])")
+    ("min-feature-displacement", po::value<float>(&minFeatureDisplacement), "minimum displacement per frame (in world space) to keep features (]0. 0.1?])")
+    ("acceleration-bound", po::value<float>(&accelerationBound), "maximum feature acceleration (]1 3+])")
+    ("deviation-bound", po::value<float>(&deviationBound), "maximum feature deviation (on cosine) (]0 1])")
+    ("smoothing-halfwidth", po::value<int>(&nFramesSmoothing), "number of frames to smooth positions (half window) ([0 inf[")
+    ("max-number-iterations", po::value<int>(&maxNumberTrackingIterations), "maximum number of iterations to stop optical flow (20-30?)")
+    ("min-tracking-error", po::value<float>(&minTrackingError), "minimum error to reach to stop optical flow (0.3-0.01)")
+    ("min-feature-eig-threshold", po::value<float>(&minFeatureEigThreshold)->default_value(1e-4), "minimum eigen value of a 2x2 normal matrix of optical flow equations (10^-4)")
+    ("min-feature-time", po::value<unsigned int>(&minFeatureTime), "minimum length of a feature (number of frames) to consider a feature for grouping [5 20+]")
+    ("mm-connection-distance", po::value<float>(&mmConnectionDistance), "connection distance in feature grouping (in world space) (ped: [0.5m 2m+], cars: [1.7m 4m+])")
+    ("mm-segmentation-distance", po::value<float>(&mmSegmentationDistance), "segmentation distance in feature grouping (in world space) (< mm-connection-distance, empirically ~ mm-connection-distance / 2.5)")
+    ("max-distance", po::value<float>(&maxDistance), "maximum distance between features for grouping (in world space) (unused)")
+    ("min-velocity-cosine", po::value<float>(&minVelocityCosine), "minimum cosine of the angle between the velocity vectors for grouping (unused)")
+    ("min-nfeatures-group", po::value<float>(&minNFeaturesPerGroup), "minimum average number of features per frame to create a vehicle hypothesis (]1 3+])")
     // ("max-uturn-cosine", po::value<float>(&maxUTurnCosine), "maximum cosine value to detect U-turn")
     // ("nframes-avoid-uturn", po::value<int>(&nFramesAvoidUTurn), "number of frames over which a feature should not make a U-turn")
     // Safety Analysis

--- a/c/feature-based-tracking.cpp	Mon May 05 23:17:19 2014 -0400
+++ b/c/feature-based-tracking.cpp	Mon May 05 23:17:46 2014 -0400
@@ -2,6 +2,8 @@
 #include "Parameters.hpp"
 #include "cvutils.hpp"
 #include "utils.hpp"
+#include "InputVideoFileModule.h"
+#include "InputFrameListModule.h"
 
 #include "src/Trajectory.h"
 #include "src/TrajectoryDBAccessList.h"
@@ -18,9 +20,6 @@
 #include <boost/foreach.hpp>
 #include <boost/filesystem.hpp>
 
-#include "InputVideoFileModule.h"
-#include "InputFrameListModule.h"
-
 #include <iostream>
 #include <vector>
 #include <ctime>
@@ -133,7 +132,7 @@
   unsigned int lastFrameNum = nFrames;
   if (params.nFrames > 0)
     lastFrameNum = MIN(params.frame1+static_cast<unsigned int>(params.nFrames), nFrames);
-  
+
   capture->setFrameNumber(params.frame1);
   for (unsigned int frameNum = params.frame1; (frameNum < lastFrameNum) && !::interruptionKey(key); frameNum++) {
       bool success = capture->getNextFrame(frame);
@@ -148,7 +147,7 @@
       
       if (!prevPts.empty()) {
 	currPts.clear();
-	calcOpticalFlowPyrLK(previousFrameBW, currentFrameBW, prevPts, currPts, status, errors, window, params.pyramidLevel, TermCriteria(3 /*static_cast<int>(TermCriteria::COUNT)+static_cast<int>(TermCriteria::EPS)*/, params.maxNumberTrackingIterations, params.minTrackingError), /* int flags = */ 0, params.minFeatureEigThreshold);
+	calcOpticalFlowPyrLK(previousFrameBW, currentFrameBW, prevPts, currPts, status, errors, window, params.pyramidLevel, TermCriteria(static_cast<int>(TermCriteria::COUNT)+static_cast<int>(TermCriteria::EPS) /* = 3 */, params.maxNumberTrackingIterations, params.minTrackingError), /* int flags = */ 0, params.minFeatureEigThreshold);
 	/// \todo try calcOpticalFlowFarneback
 
 	std::vector<Point2f> trackedPts;
@@ -201,7 +200,7 @@
 	for (int j=MAX(0, currPts[n].x-params.minFeatureDistanceKLT); j<MIN(videoSize.width, currPts[n].x+params.minFeatureDistanceKLT+1); j++)
 	  for (int i=MAX(0, currPts[n].y-params.minFeatureDistanceKLT); i<MIN(videoSize.height, currPts[n].y+params.minFeatureDistanceKLT+1); i++)
 	    featureMask.at<uchar>(i,j)=0;
-      goodFeaturesToTrack(currentFrameBW, newPts, params.maxNFeatures, params.featureQuality, params.minFeatureDistanceKLT, featureMask, params.windowSize, params.useHarrisDetector, params.k);
+      goodFeaturesToTrack(currentFrameBW, newPts, params.maxNFeatures, params.featureQuality, params.minFeatureDistanceKLT, featureMask, params.blockSize, params.useHarrisDetector, params.k);
       BOOST_FOREACH(Point2f p, newPts) { //for (unsigned int i=0; i<newPts.size(); i++) {
 	FeatureTrajectoryPtr f = FeatureTrajectoryPtr(new FeatureTrajectory(frameNum, p, homography));
 	featurePointMatches.push_back(FeaturePointMatch(f, currPts.size()));

--- a/include/Parameters.hpp	Mon May 05 23:17:19 2014 -0400
+++ b/include/Parameters.hpp	Mon May 05 23:17:46 2014 -0400
@@ -27,27 +27,50 @@
   unsigned int frame1;
   int nFrames;
   // feature tracking
+  /// "Maximum number of corners to return" (OpenCV goodFeaturesToTrack) (should be large enough not to limit the potential number of features)
   int maxNFeatures;
+  /// "Parameter characterizing the minimal accepted quality of image corners" (OpenCV goodFeaturesToTrack )
   float featureQuality;
+  /// "Minimum possible Euclidean distance between the returned corners" (OpenCV goodFeaturesToTrack)
   float minFeatureDistanceKLT;
-  int windowSize;
+  /// "Size of an average block for computing a derivative covariation matrix over each pixel neighborhood" (OpenCV goodFeaturesToTrack)
+  int blockSize;
+  /// "Parameter indicating whether to use a Harris detector" (OpenCV goodFeaturesToTrack)
   bool useHarrisDetector;
+  /// "Free parameter of the Harris detector" (OpenCV goodFeaturesToTrack)
   float k;
+  /// "size of the search window at each pyramid level" (OpenCV calcOpticalFlowPyrLK)
+  int windowSize;
+  /// "0-based maximal pyramid level number" (OpenCV calcOpticalFlowPyrLK) higher is higher quality
   int pyramidLevel;
+  /// Number of displacements (number of frames-1) over which minimum motion is computed 
   unsigned int nDisplacements;
+  /// Minimum displacement per frame (in world space) to keep features
   float minFeatureDisplacement;
+  /// Maximum feature acceleration
   float accelerationBound;
+  /// Maximum feature deviation
   float deviationBound;
+  /// Number of frames to smooth positions (half window)
   int nFramesSmoothing;
   //int nFramesVelocity;
+  /// Maximum number of iterations to stop optical flow (OpenCV calcOpticalFlowPyrLK)
   int maxNumberTrackingIterations;
+  /// Minimum error to reach to stop optical flow (OpenCV calcOpticalFlowPyrLK)
   float minTrackingError;
+  /// Minimum eigen value of a 2x2 normal matrix of optical flow equations (OpenCV calcOpticalFlowPyrLK)
   float minFeatureEigThreshold;
+  /// Minimum length of a feature (number of frames) to consider a feature for grouping
   unsigned int minFeatureTime;
+  /// Connection distance in feature grouping (in world space)
   float mmConnectionDistance;
+  /// Segmentation distance in feature grouping (in world space)
   float mmSegmentationDistance;
+  /// Maximum distance between features for grouping (in world space) (unused)
   float maxDistance;
+  /// Minimum cosine of the angle between the velocity vectors for grouping (unused)
   float minVelocityCosine;
+  /// Minimum average number of features per frame to create a vehicle hypothesis
   float minNFeaturesPerGroup;
   // safety analysis
   float maxPredictedSpeed;

--- a/tracking.cfg	Mon May 05 23:17:19 2014 -0400
+++ b/tracking.cfg	Mon May 05 23:17:46 2014 -0400
@@ -25,12 +25,14 @@
 feature-quality = 0.1
 # minimum distance between features
 min-feature-distanceklt = 5
-# size of the search window at each pyramid level
-window-size = 7
+# size of the block for feature characteristics
+block-size = 7
 # use of Harris corner detector
 use-harris-detector = false
 # k parameter to detect good features to track (OpenCV)
 k = 0.4
+# size of the search window at each pyramid level
+window-size = 7
 # maximal pyramid level in the feature tracking algorithm
 pyramid-level = 5
 # number of displacement to test minimum feature motion
@@ -46,9 +48,9 @@
 # number of frames to compute velocities
 #nframes-velocity = 5
 # maximum number of iterations to stop feature tracking
-max-number-iterations = 20
+max-number-iterations = 30
 # minimum error to reach to stop feature tracking
-min-tracking-error = 0.3
+min-tracking-error = 0.01
 # minimum eigen value of a 2x2 normal matrix of optical flow equations
 min-feature-eig-threshold = 1e-4
 # minimum length of a feature (number of frames) to consider a feature for grouping