From d9dc02541a3987c58579c44a50ba1d82e378b782 Mon Sep 17 00:00:00 2001
From: Alexander Mordvintesv <zzznah@gmail.com>
Date: Sun, 5 Aug 2012 10:20:42 +0300
Subject: [PATCH] Added descriptions to PlaneTracker samples

---
 samples/python2/feature_homography.py |  9 +++++--
 samples/python2/plane_ar.py           | 22 ++++++++++++++++
 samples/python2/plane_tracker.py      | 37 ++++++++++++++++++++++++++-
 3 files changed, 65 insertions(+), 3 deletions(-)

diff --git a/samples/python2/feature_homography.py b/samples/python2/feature_homography.py
index eec36d74e..21be4c7e0 100644
--- a/samples/python2/feature_homography.py
+++ b/samples/python2/feature_homography.py
@@ -3,16 +3,21 @@ Feature homography
 ==================
 
 Example of using features2d framework for interactive video homography matching.
-ORB features and FLANN matcher are used.
+ORB features and FLANN matcher are used. The actual tracking is implemented by
+PlaneTracker class in plane_tracker.py
 
 Inspired by http://www.youtube.com/watch?v=-ZNYoL8rzPY
 
+video: http://www.youtube.com/watch?v=FirtmYcC0Vc
+
 Usage
 -----
 feature_homography.py [<video source>]
 
-Select a textured planar object to track by drawing a box with a mouse.
+Keys:
+   SPACE  -  pause video
 
+Select a textured planar object to track by drawing a box with a mouse.
 '''
 
 import numpy as np
diff --git a/samples/python2/plane_ar.py b/samples/python2/plane_ar.py
index 27667270f..8e3156a51 100644
--- a/samples/python2/plane_ar.py
+++ b/samples/python2/plane_ar.py
@@ -1,3 +1,25 @@
+'''
+Planar augmented reality
+==================
+
+This sample shows an example of augmented reality overlay over a planar object
+tracked by PlaneTracker from plane_tracker.py. solvePnP funciton is used to
+estimate the tracked object location in 3d space.
+
+video: http://www.youtube.com/watch?v=pzVbhxx6aog
+
+Usage
+-----
+plane_ar.py [<video source>]
+
+Keys:
+   SPACE  -  pause video
+   c      -  clear targets
+
+Select a textured planar object to track by drawing a box with a mouse.
+Use 'focal' slider to adjust to camera focal length for proper video augmentation.
+'''
+
 import numpy as np
 import cv2
 import video
diff --git a/samples/python2/plane_tracker.py b/samples/python2/plane_tracker.py
index 336654e9b..61695caea 100644
--- a/samples/python2/plane_tracker.py
+++ b/samples/python2/plane_tracker.py
@@ -1,3 +1,24 @@
+'''
+Multitarget planar tracking
+==================
+
+Example of using features2d framework for interactive video homography matching.
+ORB features and FLANN matcher are used. This sample provides PlaneTracker class
+and an example of its usage.
+
+video: http://www.youtube.com/watch?v=pzVbhxx6aog
+
+Usage
+-----
+plane_tracker.py [<video source>]
+
+Keys:
+   SPACE  -  pause video
+   c      -  clear targets
+
+Select a textured planar object to track by drawing a box with a mouse.
+'''
+
 import numpy as np
 import cv2
 from collections import namedtuple
@@ -14,8 +35,22 @@ flann_params= dict(algorithm = FLANN_INDEX_LSH,
 
 MIN_MATCH_COUNT = 10
 
-
+'''
+  image     - image to track
+  rect      - tracked rectangle (x1, y1, x2, y2)
+  keypoints - keypoints detected inside rect
+  descrs    - their descriptors
+  data      - some user-provided data
+'''
 PlanarTarget = namedtuple('PlaneTarget', 'image, rect, keypoints, descrs, data')
+
+'''
+  target - reference to PlanarTarget
+  p0     - matched points coords in target image
+  p1     - matched points coords in input frame
+  H      - homography matrix from p0 to p1
+  quad   - target bounary quad in input frame
+'''
 TrackedTarget = namedtuple('TrackedTarget', 'target, p0, p1, H, quad')
 
 class PlaneTracker: