Add documentation

Author: adipandas

DOWNLOAD_WEIGHTS.md

@@ -1,9 +1,9 @@
-## Instructions to download pretrained neural-network weights.
-
+## Download pretrained neural-network weights.
 [[Webpage](https://adipandas.github.io/multi-object-tracker/)]
 [[GitHub](https://github.com/adipandas/multi-object-tracker)]
 
 ##### YOLOv3
+
 ```
 cd multi-object-tracker
 cd ./examples/pretrained_models/yolo_weights

README.md

@@ -12,7 +12,6 @@ Easy to use implementation of various multi-object tracking algorithms.
 ![Cars with YOLO][cars-yolo-output]  |  ![Cows with tf-SSD][cows-tf-ssd-output]
 Video source: [link](https://flic.kr/p/L6qyxj) | Video source: [link](https://flic.kr/p/26WeEWy)
 
-
 ## Available Multi Object Trackers
 
 ```
@@ -53,24 +52,19 @@ The interface for each tracker is simple and similar. Please refer the example t
 
 ```
 from motrackers import CentroidTracker # or IOUTracker, CentroidKF_Tracker, SORT
-
 input_data = ...
 detector = ...
 tracker = CentroidTracker(...) # or IOUTracker(...), CentroidKF_Tracker(...), SORT(...)
-
 while True:
     done, image = <read(input_data)>
     if done:
         break
-
     detection_bboxes, detection_confidences, detection_class_ids = detector.detect(image)
     # NOTE: 
     # * `detection_bboxes` are numpy.ndarray of shape (n, 4) with each row containing (bb_left, bb_top, bb_width, bb_height)
     # * `detection_confidences` are numpy.ndarray of shape (n,);
     # * `detection_class_ids` are numpy.ndarray of shape (n,).
-
     output_tracks = tracker.track(detection_bboxes, detection_confidences, detection_class_ids)
-    
     # `output_tracks` is a list with each element containing tuple of
     # (<frame>, <id>, <bb_left>, <bb_top>, <bb_width>, <bb_height>, <conf>, <x>, <y>, <z>)
     for track in output_tracks:
@@ -79,21 +73,19 @@ while True:
         print(track)
 ```
 
-Please refer [examples](https://github.com/adipandas/multi-object-tracker/tree/master/examples) folder of this repository for more details.
-You can clone and run the examples as shown [here](examples/readme.md).
+Please refer [examples](https://github.com/adipandas/multi-object-tracker/tree/master/examples) folder of this repository for more details. You can clone and run the examples.
 
 ## Pretrained object detection models
 
 You will have to download the pretrained weights for the neural-network models. 
 The shell scripts for downloading these are provided [here](https://github.com/adipandas/multi-object-tracker/tree/master/examples/pretrained_models) below respective folders.
-Please refer [DOWNLOAD_WEIGHTS.md](DOWNLOAD_WEIGHTS.md) for more details.
+Please refer [DOWNLOAD_WEIGHTS.md](https://github.com/adipandas/multi-object-tracker/blob/master/DOWNLOAD_WEIGHTS.md) for more details.
 
 ### Notes
 * There are some variations in implementations as compared to what appeared in papers of `SORT` and `IoU Tracker`.
 * In case you find any bugs in the algorithm, I will be happy to accept your pull request or you can create an issue to point it out.
 
 ## References, Credits and Contributions
-
 Please see [REFERENCES.md](docs/readme/REFERENCES.md) and [CONTRIBUTING.md](docs/readme/CONTRIBUTING.md).
 
 ## Citation

motrackers/track.py

@@ -4,7 +4,7 @@
 
 class Track:
     """
-    Track
+    Track containing attributes to track various objects.
 
     Parameters
     ----------
@@ -22,6 +22,8 @@ class Track:
         Number of times the object or track was not tracked by tracker in consecutive frames.
     iou_score : float
         Intersection over union score.
+    data_output_format: str
+        Output format for data in tracker. Options ``['mot_challenge', 'visdrone_challenge']``. Default is ``mot_challenge``.
     kwargs : dict
         Additional key word arguments.
 
@@ -163,6 +165,9 @@ def get_vis_drone_format(self):
         return mot_tuple
 
     def predict(self):
+        """
+        Implement to prediction the next estimate of track.
+        """
         raise NotImplemented
 
     @staticmethod
@@ -173,6 +178,31 @@ def print_all_track_output_formats():
 class KFTrackSORT(Track):
     """
     Track based on Kalman filter tracker used for SORT MOT-Algorithm.
+
+    Parameters
+    ----------
+    track_id : int
+        Track Id
+    frame_id : int
+        Camera frame id.
+    bbox : numpy.ndarray
+        Bounding box pixel coordinates as (xmin, ymin, width, height) of the track.
+    detection_confidence : float
+        Detection confidence of the object (probability).
+    class_id : Object
+        Class label id.
+    lost : int
+        Number of times the object or track was not tracked by tracker in consecutive frames.
+    iou_score : float
+        Intersection over union score.
+    data_output_format: str
+        Output format for data in tracker. Options ``['mot_challenge', 'visdrone_challenge']``. Default is ``mot_challenge``.
+    process_noise_scale: float
+        Process noise covariance scale or covariance magnitude as scalar value.
+    measurement_noise_scale: float
+        Measurement noise covariance scale or covariance magnitude as scalar value.
+    kwargs : dict
+        Additional key word arguments.
     """
     def __init__(self, track_id, frame_id, bbox, detection_confidence, class_id=None, lost=0, iou_score=0.,
                  data_output_format='mot_challenge', process_noise_scale=1.0, measurement_noise_scale=1.0, **kwargs):
@@ -183,6 +213,13 @@ def __init__(self, track_id, frame_id, bbox, detection_confidence, class_id=None
                          iou_score=iou_score, data_output_format=data_output_format, **kwargs)
 
     def predict(self):
+        """
+        Predicts the next estimate of the bounding box of the track.
+
+        Returns:
+            numpy.ndarray: Bounding box pixel coordinates as (xmin, ymin, width, height) of the track.
+
+        """
         if (self.kf.x[6] + self.kf.x[2]) <= 0:
             self.kf.x[6] *= 0.0
 
@@ -206,6 +243,31 @@ def update(self, frame_id, bbox, detection_confidence, class_id=None, lost=0, io
 class KFTrack4DSORT(Track):
     """
     Track based on Kalman filter tracker used for SORT MOT-Algorithm.
+
+    Parameters
+    ----------
+    track_id : int
+        Track Id
+    frame_id : int
+        Camera frame id.
+    bbox : numpy.ndarray
+        Bounding box pixel coordinates as (xmin, ymin, width, height) of the track.
+    detection_confidence : float
+        Detection confidence of the object (probability).
+    class_id : Object
+        Class label id.
+    lost : int
+        Number of times the object or track was not tracked by tracker in consecutive frames.
+    iou_score : float
+        Intersection over union score.
+    data_output_format: str
+        Output format for data in tracker. Options ``['mot_challenge', 'visdrone_challenge']``. Default is ``mot_challenge``.
+    process_noise_scale: float
+        Process noise covariance scale or covariance magnitude as scalar value.
+    measurement_noise_scale: float
+        Measurement noise covariance scale or covariance magnitude as scalar value.
+    kwargs : dict
+        Additional key word arguments.
     """
     def __init__(self, track_id, frame_id, bbox, detection_confidence, class_id=None, lost=0, iou_score=0.,
                  data_output_format='mot_challenge', process_noise_scale=1.0, measurement_noise_scale=1.0,
@@ -230,6 +292,31 @@ def update(self, frame_id, bbox, detection_confidence, class_id=None, lost=0, io
 class KFTrackCentroid(Track):
     """
     Track based on Kalman filter used for Centroid Tracking of bounding box in MOT.
+
+    Parameters
+    ----------
+    track_id : int
+        Track Id
+    frame_id : int
+        Camera frame id.
+    bbox : numpy.ndarray
+        Bounding box pixel coordinates as (xmin, ymin, width, height) of the track.
+    detection_confidence : float
+        Detection confidence of the object (probability).
+    class_id : Object
+        Class label id.
+    lost : int
+        Number of times the object or track was not tracked by tracker in consecutive frames.
+    iou_score : float
+        Intersection over union score.
+    data_output_format: str
+        Output format for data in tracker. Options ``['mot_challenge', 'visdrone_challenge']``. Default is ``mot_challenge``.
+    process_noise_scale: float
+        Process noise covariance scale or covariance magnitude as scalar value.
+    measurement_noise_scale: float
+        Measurement noise covariance scale or covariance magnitude as scalar value.
+    kwargs : dict
+        Additional key word arguments.
     """
     def __init__(self, track_id, frame_id, bbox, detection_confidence, class_id=None, lost=0, iou_score=0.,
                  data_output_format='mot_challenge', process_noise_scale=1.0, measurement_noise_scale=1.0, **kwargs):
@@ -239,6 +326,13 @@ def __init__(self, track_id, frame_id, bbox, detection_confidence, class_id=None
                          iou_score=iou_score, data_output_format=data_output_format, **kwargs)
 
     def predict(self):
+        """
+        Predicts the next estimate of the bounding box of the track.
+
+        Returns:
+            numpy.ndarray: Bounding box pixel coordinates as (xmin, ymin, width, height) of the track.
+
+        """
         s = self.kf.predict()
         xmid, ymid = s[0], s[3]
         w, h = self.bbox[2], self.bbox[3]

motrackers/tracker_img.py

@@ -0,0 +1,63 @@
+import argparse
+import time
+import cv2
+
+
+ap = argparse.ArgumentParser()
+ap.add_argument("-v", "--video", type=str, default='../examples/video_data/cars.mp4', help="path to input video file")
+ap.add_argument("-t", "--tracker", type=str, default="kcf", help="OpenCV object tracker type")
+args = vars(ap.parse_args())
+
+OPENCV_OBJECT_TRACKERS = {
+    "csrt": cv2.TrackerCSRT_create,
+    "kcf": cv2.TrackerKCF_create,
+    "boosting": cv2.TrackerBoosting_create,
+    "mil": cv2.TrackerMIL_create,
+    "tld": cv2.TrackerTLD_create,
+    "medianflow": cv2.TrackerMedianFlow_create,
+    "mosse": cv2.TrackerMOSSE_create
+}
+
+trackers = cv2.MultiTracker_create()
+
+vs = cv2.VideoCapture(args["video"])
+
+while True:
+    ok, frame = vs.read()
+    if not ok:
+        break
+
+    # resize the frame (so we can process it faster)
+    frame = cv2.resize(frame, (600, 400))
+
+    (success, boxes) = trackers.update(frame)
+    print(success)
+
+    for box in boxes:
+        (x, y, w, h) = [int(v) for v in box]
+        cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2)
+
+    cv2.imshow("Frame", frame)
+    key = cv2.waitKey(1) & 0xFF
+
+    # if the 's' key is selected, we are going to "select" a bounding
+    # box to tracks
+    if key == ord("s"):
+        # select the bounding box of the object we want to track (make
+        # sure you press ENTER or SPACE after selecting the ROI)
+        box = cv2.selectROI("Frame", frame, fromCenter=False, showCrosshair=True)
+
+        # create a new object tracker for the bounding box and add it to our multi-object tracker
+        tracker = OPENCV_OBJECT_TRACKERS[args["tracker"]]()
+        trackers.add(tracker, frame, box)
+
+    elif key == ord("q"):  # if the `q` key was pressed, break from the loop
+        break
+
+    time.sleep(0.1)
+
+# if we are using a webcam, release the pointer
+vs.release()
+
+# close all windows
+cv2.destroyAllWindows()