release 0.0.7

Author: wmuron

Makefile

@@ -21,4 +21,8 @@ clean:
 	autoflake --in-place --remove-unused-variables ./motpy/*.py ./tests/*.py
 
 check:
-	mypy --ignore-missing-imports motpy
+	mypy --ignore-missing-imports motpy
+
+demo-mot16:
+	# note it requires downloading MOT16 dataset before running
+	python examples/mot16_challange.py --dataset_root=~/Downloads/MOT16 --seq_id=11

README.md

@@ -61,13 +61,6 @@ for step in range(10):
 
 ## Things to do
 
-TODO temporary:
-- allow passing model_kwargs??
-- model_mapping enable autocompletion,
-- add example on the highway, vehicles maybe pedestrians
-
-
-
 - [x] Initial version
 - [ ] Documentation
 - [ ] Performance optimization

examples/2d_multi_object_tracking.py

@@ -2,7 +2,7 @@
 import cv2
 
 import motpy
-from motpy import MultiObjectTracker
+from motpy import MultiObjectTracker, ModelPreset
 from motpy.testing_viz import draw_rectangle, draw_text, image_generator
 
 motpy.set_log_level('DEBUG')
@@ -20,7 +20,7 @@ def demo_tracking_visualization(num_steps: int = 1000, num_objects: int = 10):
     dt = 1 / 24
     tracker = MultiObjectTracker(
         dt=dt,
-        model_spec={'order_pos': 2, 'dim_pos': 2, 'order_size': 0, 'dim_size': 2},
+        model_spec=ModelPreset.constant_acceleration_and_static_box_size_2d.value,
         active_tracks_kwargs={'min_steps_alive': 2, 'max_staleness': 6},
         tracker_kwargs={'max_staleness': 12})
 

examples/mot16_challange.py

@@ -17,9 +17,13 @@
     MOT16 tracking demo
 
     Usage:
-        python examples/mot16_challange.py --dataset_root ~/Downloads/MOT16 --seq_id 11
+        python examples/mot16_challange.py --dataset_root=~/Downloads/MOT16 --seq_id=11
 
     Note: this is just a demo, the script does not evaluate the tracking on MOT16 dataset.
+    Also, since provided by MOT16 `predictions` do not represent (IMO) the current state
+    of modern detectors, the demo utilizes ground truth + noise as input to the tracker;
+    feel free to use `sel=det` to check the 'real' MOT16 predictions, but keep in mind that
+    tracker is not optimized at all for such noisy predictions.
 
 """
 
@@ -37,6 +41,7 @@ def read_video_frame(directory, frame_idx):
 
 
 def read_detections(path, drop_detection_prob: float = 0.0, add_detection_noise: float = 0.0):
+    """ parses and converts MOT16 benchmark annotations to known [xmin, ymin, xmax, ymax] format """
     path = os.path.expanduser(path)
     logger.debug('reading detections from %s' % path)
     if not os.path.isfile(path):
@@ -70,13 +75,15 @@ def get_miliseconds():
 
 def run(
         dataset_root: str,
-        fps=30,
+        fps: float = 30.0,
         split: str = 'train',
-        seq_id='04',
-        sel='gt',
+        seq_id: str = '04',
+        sel: str = 'gt',
         drop_detection_prob: float = 0.1,
         add_detection_noise: float = 5.0):
+    """ parses detections, loads frames, runs tracking and visualizes the tracked objects """
 
+    dataset_root = os.path.expanduser(dataset_root)
     if not os.path.isdir(dataset_root):
         logger.error('%s does not exist' % dataset_root)
         exit(-1)
@@ -97,32 +104,43 @@ def run(
 
     tracker = MultiObjectTracker(
         dt=1 / fps, tracker_kwargs={'max_staleness': 15},
-        model_spec='2d_constant_acceleration+static_box_size')
-
-    # TODO cleanup
-    tracker.matching_fn.min_iou = 0.25
+        model_spec='constant_acceleration_and_static_box_size_2d',
+        matching_fn_kwargs={'min_iou': 0.25})
 
     # tracking loop
     while True:
-        frame_idx, detections = next(dets_gen)
+        # read detections for a given frame
+        try:
+            frame_idx, detections = next(dets_gen)
+        except Exception as e:
+            logger.warning('finished reading the sequence')
+            logger.trace(f'exception: {e}')
+            break
+
+        # read the frame for a given index
         frame = read_video_frame(frames_dir, frame_idx)
         if frame is None:
             continue
 
+        # provide the MOT tracker with predicted detections
         t1 = get_miliseconds()
         active_tracks = tracker.step(detections)
         ms_elapsed = get_miliseconds() - t1
         logger.debug('step duration: %dms' % ms_elapsed)
 
+        # visualize predictions and tracklets
         for det in detections:
             draw_detection(frame, det)
 
         for track in active_tracks:
             draw_track(frame, track)
 
         cv2.imshow('preview', frame)
+
+        # stop execution on q
         key = cv2.waitKey(int(1000 / fps))
         if key == ord('q'):
+            logger.info('early stopping')
             break
 
 

motpy/__init__.py

@@ -1,3 +1,3 @@
 from .tracker import MultiObjectTracker, MatchingFunction, BasicMatchingFunction
-from .model import Model, MODELS_MAPPING
+from .model import Model, ModelPreset
 from .core import Box, Detection, Track, set_log_level

motpy/model.py

@@ -1,4 +1,6 @@
 
+from enum import Enum
+
 import numpy as np
 from filterpy.common import Q_discrete_white_noise
 from filterpy.kalman import KalmanFilter
@@ -8,17 +10,17 @@
 from motpy.core import Box, Detection, Track, Vector
 from motpy.metrics import angular_similarity, calculate_iou
 
+
 """ The list of model presets below is not complete, more reasonable
 options will be added in the future """
 
-MODELS_MAPPING = {
-    '2d_constant_velocity+static_box_size':
-        {'order_pos': 1, 'dim_pos': 2,
-         'order_size': 0, 'dim_size': 2},
-    '2d_constant_acceleration+static_box_size':
-        {'order_pos': 2, 'dim_pos': 2,
-         'order_size': 0, 'dim_size': 2}
-}
+
+class ModelPreset(Enum):
+    constant_velocity_and_static_box_size_2d = {'order_pos': 1, 'dim_pos': 2,
+                                                'order_size': 0, 'dim_size': 2}
+
+    constant_acceleration_and_static_box_size_2d = {'order_pos': 2, 'dim_pos': 2,
+                                                    'order_size': 0, 'dim_size': 2}
 
 
 def _base_dim_block(dt: float, order: int = 1):

motpy/tracker.py

@@ -8,7 +8,7 @@
 
 from motpy.core import Box, Detection, Track, Vector
 from motpy.metrics import angular_similarity, calculate_iou
-from motpy.model import MODELS_MAPPING, Model
+from motpy.model import ModelPreset, Model
 
 
 def get_object_tracker(dt: float, model: Model, x0: Optional[Vector] = None):
@@ -34,7 +34,7 @@ def get_object_tracker(dt: float, model: Model, x0: Optional[Vector] = None):
     return tracker
 
 
-DEFAULT_MODEL_SPEC = MODELS_MAPPING['2d_constant_velocity+static_box_size']
+DEFAULT_MODEL_SPEC = ModelPreset.constant_velocity_and_static_box_size_2d.value
 
 
 class Tracker:
@@ -210,6 +210,7 @@ def __init__(self, dt: float,
                  model_spec: Union[str, dict] = DEFAULT_MODEL_SPEC,
                  matching_fn: Optional[MatchingFunction] = None,
                  tracker_kwargs: dict = None,
+                 matching_fn_kwargs: dict = None,
                  active_tracks_kwargs: dict = None):
         """
             model_spec specifies the dimension and order for position and size of the object
@@ -224,15 +225,16 @@ def __init__(self, dt: float,
 
         if isinstance(model_spec, dict):
             self.model_spec = model_spec
-        elif isinstance(model_spec, str) and model_spec in MODELS_MAPPING:
-            self.model_spec = MODELS_MAPPING[model_spec]
+        elif isinstance(model_spec, str) and model_spec in ModelPreset.__members__:
+            self.model_spec = ModelPreset[model_spec].value
         else:
             raise NotImplementedError('unsupported motion model %s' % str(model_spec))
         logger.trace('using model spec: %s' % str(self.model_spec))
 
         self.matching_fn = matching_fn
+        self.matching_fn_kwargs = matching_fn_kwargs if matching_fn_kwargs is not None else {}
         if self.matching_fn is None:
-            self.matching_fn = BasicMatchingFunction()
+            self.matching_fn = BasicMatchingFunction(**self.matching_fn_kwargs)
 
         # kwargs to be passed to each single object tracker
         self.tracker_kwargs = tracker_kwargs if tracker_kwargs is not None else {}

requirements.txt

@@ -9,8 +9,8 @@ autoflake
 mypy
 # for testing and demo requirements below are necessary
 pytest
+fire
 opencv-python
-
 # installation of opencv-python might be troublesome on Raspbian, hence I've left it out
 # from package requirements. If you really need demos, refer to link below for installation
 # instractions: https://blog.piwheels.org/new-opencv-builds-including-opencv-4-x/

setup.py

@@ -2,9 +2,9 @@
 
 setup(
     name='motpy',
-    version='0.0.6',
+    version='0.0.7',
     url='https://github.com/wmuron/motpy.git',
-    download_url='https://github.com/wmuron/motpy/releases/tag/v0.0.6-alpha',
+    download_url='https://github.com/wmuron/motpy/releases/tag/v0.0.7-alpha',
     author='Wiktor Muron',
     author_email='[email protected]',
     description='Library for track-by-detection multi object tracking implemented in python',