Update docs on corr tracker, return side lobe

Added the missing documentation for the correlation tracker.
Didn't realise that the tracker returned the side lobe ratio,
so fixed the API to return it properly.

tools/python/src/correlation_tracker.cpp

@@ -42,18 +42,18 @@ void start_track_rec (
     start_track(tracker, img, dbounding_box);
 }
 
-void update (
+double update (
     correlation_tracker& tracker,
     object img
 )
 {
     if (is_gray_python_image(img))
     {
-        tracker.update(numpy_gray_image(img));
+        return tracker.update(numpy_gray_image(img));
     }
     else if (is_rgb_python_image(img))
     {
-        tracker.update(numpy_rgb_image(img));
+        return tracker.update(numpy_rgb_image(img));
     }
     else
     {
@@ -61,7 +61,7 @@ void update (
     }
 }
 
-void update_guess (
+double update_guess (
     correlation_tracker& tracker,
     object img,
     const drectangle& bounding_box
@@ -69,11 +69,11 @@ void update_guess (
 {
     if (is_gray_python_image(img))
     {
-        tracker.update(numpy_gray_image(img), bounding_box);
+        return tracker.update(numpy_gray_image(img), bounding_box);
     }
     else if (is_rgb_python_image(img))
     {
-        tracker.update(numpy_rgb_image(img), bounding_box);
+        return tracker.update(numpy_rgb_image(img), bounding_box);
     }
     else
     {
@@ -81,14 +81,14 @@ void update_guess (
     }
 }
 
-void update_guess_rec (
+double update_guess_rec (
     correlation_tracker& tracker,
     object img,
     const rectangle& bounding_box
 )
 {
     drectangle dbounding_box(bounding_box);
-    update_guess(tracker, img, dbounding_box);
+    return update_guess(tracker, img, dbounding_box);
 }
 
 drectangle get_position (const correlation_tracker& tracker) { return tracker.get_position(); }
@@ -100,12 +100,67 @@ void bind_correlation_tracker()
     using boost::python::arg;
     {
     typedef correlation_tracker type;
-    class_<type>("correlation_tracker", "")
-        .def("start_track", &::start_track, (arg("image"), arg("bounding_box")))
-        .def("start_track", &::start_track_rec, (arg("image"), arg("bounding_box")))
-        .def("update", &::update, arg("image"))
-        .def("update", &::update_guess, (arg("image"), arg("guess")))
-        .def("update", &::update_guess_rec, (arg("image"), arg("guess")))
-        .def("get_position", &::get_position);
+    class_<type>("correlation_tracker", "This is a tool for tracking moving objects in a video stream.  You give it \n\
+            the bounding box of an object in the first frame and it attempts to track the \n\
+            object in the box from frame to frame.  \n\
+            This tool is an implementation of the method described in the following paper: \n\
+                Danelljan, Martin, et al. 'Accurate scale estimation for robust visual \n\
+                tracking.' Proceedings of the British Machine Vision Conference BMVC. 2014.")
+        .def("start_track", &::start_track, (arg("image"), arg("bounding_box")), "\
+            requires \n\
+                - image is a numpy ndarray containing either an 8bit grayscale or RGB image. \n\
+                - bounding_box.is_empty() == false \n\
+            ensures \n\
+                - This object will start tracking the thing inside the bounding box in the \n\
+                  given image.  That is, if you call update() with subsequent video frames \n\
+                  then it will try to keep track of the position of the object inside bounding_box. \n\
+                - #get_position() == bounding_box")
+        .def("start_track", &::start_track_rec, (arg("image"), arg("bounding_box")), "\
+            requires \n\
+                - image is a numpy ndarray containing either an 8bit grayscale or RGB image. \n\
+                - bounding_box.is_empty() == false \n\
+            ensures \n\
+                - This object will start tracking the thing inside the bounding box in the \n\
+                  given image.  That is, if you call update() with subsequent video frames \n\
+                  then it will try to keep track of the position of the object inside bounding_box. \n\
+                - #get_position() == bounding_box")
+        .def("update", &::update, arg("image"), "\
+            requires \n\
+                - image is a numpy ndarray containing either an 8bit grayscale or RGB image. \n\
+                - get_position().is_empty() == false \n\
+                  (i.e. you must have started tracking by calling start_track()) \n\
+            ensures \n\
+                - performs: return update(img, get_position())")
+        .def("update", &::update_guess, (arg("image"), arg("guess")), "\
+            requires \n\
+                - image is a numpy ndarray containing either an 8bit grayscale or RGB image. \n\
+                - get_position().is_empty() == false \n\
+                  (i.e. you must have started tracking by calling start_track()) \n\
+            ensures \n\
+                - When searching for the object in img, we search in the area around the \n\
+                  provided guess. \n\
+                - #get_position() == the new predicted location of the object in img.  This \n\
+                  location will be a copy of guess that has been translated and scaled \n\
+                  appropriately based on the content of img so that it, hopefully, bounds \n\
+                  the object in img. \n\
+                - Returns the peak to side-lobe ratio.  This is a number that measures how \n\
+                  confident the tracker is that the object is inside #get_position(). \n\
+                  Larger values indicate higher confidence.")
+        .def("update", &::update_guess_rec, (arg("image"), arg("guess")), "\
+            requires \n\
+                - image is a numpy ndarray containing either an 8bit grayscale or RGB image. \n\
+                - get_position().is_empty() == false \n\
+                  (i.e. you must have started tracking by calling start_track()) \n\
+            ensures \n\
+                - When searching for the object in img, we search in the area around the \n\
+                  provided guess. \n\
+                - #get_position() == the new predicted location of the object in img.  This \n\
+                  location will be a copy of guess that has been translated and scaled \n\
+                  appropriately based on the content of img so that it, hopefully, bounds \n\
+                  the object in img. \n\
+                - Returns the peak to side-lobe ratio.  This is a number that measures how \n\
+                  confident the tracker is that the object is inside #get_position(). \n\
+                  Larger values indicate higher confidence.")
+        .def("get_position", &::get_position, "returns the predicted position of the object under track.");
     }
 }