motrack 0.1.0__tar.gz

motrack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Momir Adžemović
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

motrack-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.1
+Name: motrack
+Version: 0.1.0
+Summary: Tracking-by-detection (MOT) package
+Home-page: https://github.com/Robotmurlock/Motrack
+Author: Momir Adzemovic
+Author-email: momir.adzemovic@gmail.com
+Keywords: tracking-by-detection,multi-object-tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8, <4
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hydra-core
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: omegaconf
+Requires-Dist: opencv_python
+Requires-Dist: pandas
+Requires-Dist: PyYAML
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Provides-Extra: yolov8
+Requires-Dist: ultralytics; extra == "yolov8"
+
+# Motrack: Multi-Object Tracking Library
+
+## Introduction
+
+Motrack is a versatile multi-object tracking library designed to 
+leverage the tracking-by-detection paradigm. 
+It supports a range of tracker algorithms and object detections, 
+making it ideal for applications in various domains.
+
+## Usage
+
+Pseudocode for tracker utilization:
+
+```python
+from motrack.object_detection import YOLOv8Inference
+from motrack.tracker import ByteTracker, TrackletState
+
+tracker = ByteTracker()  # Default parameters
+tracklets = []
+yolo = YOLOv8Inference(...)
+
+video_frames = read_video(video_path)
+
+for i, image in enumerate(video_frames):
+  detections = yolo.predict_bboxes(image)
+  tracklets = tracker.track(tracklets, detections, i)
+  active_tracklets = [t for t in tracklets if t.state == TrackletState.ACTIVE]
+
+  foo_bar(active_tracklets)
+```
+
+This library offers flexibility to use any custom object detector.
+
+Implementation of custom tracker:
+
+```python
+from typing import List, Tuple
+
+from motrack.library.cv.bbox import PredBBox
+from motrack.tracker import Tracker, Tracklet
+
+
+class MyTracker(Tracker):
+  def track(
+    self,
+    tracklets: List[Tracklet],
+    detections: List[PredBBox],
+    frame_index: int,
+    inplace: bool = True
+  ) -> List[Tracklet]:
+    ... Tracker logic ...
+
+    return tracklets
+```
+
+Similarly, custom object detection inference, filter, association method
+or dataset can also be implemented and seamlessly combined
+with other components.
+
+## Features
+- **Tracker Algorithms Support**: 
+  - SORT
+  - ByteTrack
+  - SparseTrack
+- **Object Detection Inference**:
+  - YOLOX
+  - YOLOv8
+- **Kalman Filter**:
+  - Bot-Sort Kalman filter implementation
+- **Association Methods**:
+  - IoU (SORT)
+  - Move
+  - CBIoU
+  - DCM
+  - And more...
+- **Dataset Format Support**:
+  - MOT: MOT17, MOT20, DanceTrack 
+- **Tools**:
+  - Inference: Perform any tracker inference that can directly evaluated with TrackEval framework.
+  - Postprocess: Perform offline postprocessing (linear interpolation, etc...) for more accuracy tracklets.
+  - Visualize: Visualize tracker inference.
+
+## Installation
+
+Run these commands to install package within your virtual environment or docker container.
+
+```bash
+git clone https://github.com/Robotmurlock/Motrack
+cd Motrack
+pip install -e .
+```

motrack-0.1.0/README.md

@@ -0,0 +1,91 @@
+# Motrack: Multi-Object Tracking Library
+
+## Introduction
+
+Motrack is a versatile multi-object tracking library designed to 
+leverage the tracking-by-detection paradigm. 
+It supports a range of tracker algorithms and object detections, 
+making it ideal for applications in various domains.
+
+## Usage
+
+Pseudocode for tracker utilization:
+
+```python
+from motrack.object_detection import YOLOv8Inference
+from motrack.tracker import ByteTracker, TrackletState
+
+tracker = ByteTracker()  # Default parameters
+tracklets = []
+yolo = YOLOv8Inference(...)
+
+video_frames = read_video(video_path)
+
+for i, image in enumerate(video_frames):
+  detections = yolo.predict_bboxes(image)
+  tracklets = tracker.track(tracklets, detections, i)
+  active_tracklets = [t for t in tracklets if t.state == TrackletState.ACTIVE]
+
+  foo_bar(active_tracklets)
+```
+
+This library offers flexibility to use any custom object detector.
+
+Implementation of custom tracker:
+
+```python
+from typing import List, Tuple
+
+from motrack.library.cv.bbox import PredBBox
+from motrack.tracker import Tracker, Tracklet
+
+
+class MyTracker(Tracker):
+  def track(
+    self,
+    tracklets: List[Tracklet],
+    detections: List[PredBBox],
+    frame_index: int,
+    inplace: bool = True
+  ) -> List[Tracklet]:
+    ... Tracker logic ...
+
+    return tracklets
+```
+
+Similarly, custom object detection inference, filter, association method
+or dataset can also be implemented and seamlessly combined
+with other components.
+
+## Features
+- **Tracker Algorithms Support**: 
+  - SORT
+  - ByteTrack
+  - SparseTrack
+- **Object Detection Inference**:
+  - YOLOX
+  - YOLOv8
+- **Kalman Filter**:
+  - Bot-Sort Kalman filter implementation
+- **Association Methods**:
+  - IoU (SORT)
+  - Move
+  - CBIoU
+  - DCM
+  - And more...
+- **Dataset Format Support**:
+  - MOT: MOT17, MOT20, DanceTrack 
+- **Tools**:
+  - Inference: Perform any tracker inference that can directly evaluated with TrackEval framework.
+  - Postprocess: Perform offline postprocessing (linear interpolation, etc...) for more accuracy tracklets.
+  - Visualize: Visualize tracker inference.
+
+## Installation
+
+Run these commands to install package within your virtual environment or docker container.
+
+```bash
+git clone https://github.com/Robotmurlock/Motrack
+cd Motrack
+pip install -e .
+```

motrack-0.1.0/motrack/cmc/__init__.py

@@ -0,0 +1,5 @@
+"""
+Camera motion compensation interface.
+"""
+from motrack.cmc.factory import cmc_factory
+from motrack.cmc.algorithms.gmc_from_file import GMCFromFile

motrack-0.1.0/motrack/cmc/algorithms/base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+import numpy as np
+from typing import Optional
+
+
+class CameraMotionCompensation(ABC):
+    @abstractmethod
+    def apply(self, frame: np.ndarray, frame_index: int, scene: Optional[str] = None) -> np.ndarray:
+        """
+        Calculates approximated affine transformations applied
+        to the image between current and last frame.
+
+        Args:
+            frame: Current video frame
+            frame_index: Frame index
+            scene: Scene name (optional)
+
+        Returns:
+            Affine 2x3 matrix (includes translation)
+        """

motrack-0.1.0/motrack/cmc/algorithms/gmc_from_file.py

@@ -0,0 +1,81 @@
+import os
+from typing import Optional, Dict
+
+import numpy as np
+
+from motrack.cmc.algorithms.base import CameraMotionCompensation
+from motrack.cmc.catalog import CMC_CATALOG
+
+
+@CMC_CATALOG.register('gmc-from-file')
+class GMCFromFile(CameraMotionCompensation):
+    """
+    Loads precalculated GMC warps from a directory for each scene.
+    """
+    LINE_SEP = '\t'
+
+    def __init__(self, dirpath: str):
+        """
+        Args:
+            dirpath: Path to directory where precalculated GMC warps are stored.
+        """
+        self._gmc_lookup = self._parse_gmc_directory(dirpath)
+
+    @staticmethod
+    def _get_gmc_filename(scene: str) -> str:
+        """
+        Gets GMC filename based on the scene name.
+
+        Args:
+            scene: Scene name
+
+        Returns:
+
+        """
+        filename = f'GMC-{scene}.txt'
+
+        # DanceTrack naming (special case)
+        if scene.startswith('dancetrack'):
+            filename = filename.replace('dancetrack', 'dancetrack-')
+
+        return filename
+
+    @staticmethod
+    def _parse_gmc_directory(path: str) -> Dict[str, np.ndarray]:
+        """
+        Parses all files in GMC directory.
+
+        Args:
+            path: Path to GMC files.
+
+        Returns:
+            GMC warp lookup
+        """
+        gmc_lookup = {}
+
+        files = os.listdir(path)
+        for file in files:
+            filepath = os.path.join(path, file)
+            with open(filepath, 'r', encoding='utf-8') as f:
+                lines = [line for line in f.readlines() if len(line) > 0]
+
+            n_lines = len(lines)
+            warps = np.zeros(shape=(n_lines, 2, 3), dtype=np.float32)
+            for line_i, line in enumerate(lines):
+                tokens = line.strip().split(GMCFromFile.LINE_SEP)[1:]
+                for token_i, token in enumerate(tokens):
+                    r, c = token_i // 3, token_i % 3
+                    warps[line_i, r, c] = float(tokens[token_i])
+
+            gmc_lookup[file] = warps
+
+        return gmc_lookup
+
+
+    def apply(self, frame: np.ndarray, frame_index: int, scene: Optional[str] = None) -> np.ndarray:
+        assert scene is not None, f'Scene name is required in order to load GMC warps from a file!'
+        scene_file = self._get_gmc_filename(scene)
+        warp = self._gmc_lookup[scene_file][frame_index, :, :]
+        warp[0, 2] /= frame.shape[1]
+        warp[1, 2] /= frame.shape[0]
+        return warp

motrack-0.1.0/motrack/cmc/catalog.py

@@ -0,0 +1,7 @@
+"""
+Dynamic CMC catalog.
+"""
+from motrack.utils.patterns import DynamicCatalog
+
+
+CMC_CATALOG = DynamicCatalog()

motrack-0.1.0/motrack/cmc/factory.py

@@ -0,0 +1,22 @@
+"""
+CMC factory method.
+Use `CMC_CATALOG.register` to extend supported CMC algorithms.
+"""
+from motrack.cmc.algorithms.base import CameraMotionCompensation
+# noinspection PyUnresolvedReferences
+from motrack.cmc.algorithms.gmc_from_file import GMCFromFile  # pylint: disable=unused-import
+from motrack.cmc.catalog import CMC_CATALOG
+
+
+def cmc_factory(name: str, params: dict) -> CameraMotionCompensation:
+    """
+    CMC factory.
+
+    Args:
+        name: Algorithm name
+        params: Dataset creation parameters
+
+    Returns:
+        Created CMC object
+    """
+    return CMC_CATALOG[name](**params)

motrack-0.1.0/motrack/common/formats.py

@@ -0,0 +1,6 @@
+"""
+Conventions formats.
+"""
+DATE_FORMAT = '%Y-%m-%d'
+TIME_FORMAT = '%H-%M-%S.%f'
+DATETIME_FORMAT = f'{DATE_FORMAT}_{TIME_FORMAT}'

motrack-0.1.0/motrack/common/project.py

@@ -0,0 +1,14 @@
+"""
+Set of path constants relative to project source (independent of project location on system).
+"""
+import os
+
+
+ROOT_PATH = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+SRC_PATH = os.path.join(ROOT_PATH, 'motrack')
+CONFIGS_PATH = os.path.join(ROOT_PATH, 'configs')
+OUTPUTS_PATH = os.path.join(ROOT_PATH, 'outputs')
+PLAYGROUND_PATH = os.path.join(ROOT_PATH, 'playground')
+
+ASSETS_PATH = '/media/home/motrack-outputs/'
+MASTER_PATH = '/media/home/'

motrack-0.1.0/motrack/config_parser/__init__.py

@@ -0,0 +1,4 @@
+"""
+Config interface.
+"""
+from motrack.config_parser.core import GlobalConfig, TrackerPostprocessConfig, TrackerVisualizeConfig

motrack-0.1.0/motrack/config_parser/core.py

@@ -0,0 +1,161 @@
+"""
+Tracker config for tools scripts.
+"""
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+from hydra.core.config_store import ConfigStore
+
+from motrack.common import project
+from motrack.utils.lookup import LookupTable
+
+
+@dataclass
+class PathConfig:
+    """
+    Path configs
+    - master: location where all final and intermediate results are stored
+    - assets: location where datasets can be found
+    """
+    master: str = project.MASTER_PATH
+    assets: str = project.ASSETS_PATH
+
+    @classmethod
+    def default(cls) -> 'PathConfig':
+        """
+        Default path configuration is used if it is not defined in configs.
+
+        Returns: Path configuration.
+        """
+        return cls(
+            master=project.OUTPUTS_PATH,
+            assets=project.ASSETS_PATH
+        )
+
+
+@dataclass
+class DatasetConfig:
+    """
+    Dataset config.
+    - name: Dataset name
+    - path: Path to the dataset
+    - params: Ctor parameters
+    """
+    type: str
+    path: str
+    params: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        """
+        Fullpath is resolved from global config (path is required)
+        """
+        self.fullpath = None
+
+
+@dataclass
+class FilterConfig:
+    """
+    Filter (motion model) config.
+    """
+    type: str
+    params: dict
+
+
+@dataclass
+class ObjectDetectionInferenceConfig:
+    """
+    Object detection config.
+    - type: Architecture
+    - params: Ctor params
+    - lookup_path: Class mappings saved as a json file (in LookupTable format)
+    - cache_path: Use cache for faster inference
+    - oracle: Use GT detections instead running inference
+    """
+    type: str
+    params: dict
+    lookup_path: Optional[str] = None
+    cache_path: Optional[str] = None
+    oracle: bool = False
+
+    def load_lookup(self) -> LookupTable:
+        """
+        Loads lookup file.
+
+        Returns:
+            Loaded lookup
+        """
+        with open(self.lookup_path, 'r', encoding='utf-8') as f:
+            return LookupTable.deserialize(json.load(f))
+
+
+@dataclass
+class TrackerAlgorithmConfig:
+    name: str
+    params: dict
+    requires_image: bool = False
+
+
+@dataclass
+class TrackerVisualizeConfig:
+    fps: int = 20
+    new_object_length: int = 5
+    option: str = 'all'
+
+    def __post_init__(self) -> None:
+        """
+        Validation.
+        """
+        options = ['active', 'all', 'postprocess']
+        assert self.option in options, f'Invalid option "{self.option}". Available: {options}.'
+
+
+@dataclass
+class TrackerPostprocessConfig:
+    init_threshold: int = 2  # Activate `init_threshold` starting bboxes
+    linear_interpolation_threshold: int = 3  # Maximum distance to perform linear interpolation
+    min_tracklet_length: int = 20  # Remove all tracklets that are shorter than this
+
+
+@dataclass
+class TrackerEvalConfig:
+    split: str
+
+
+@dataclass
+class DatasetFilterConfig:
+    scene_pattern: str = '(.*?)'  # All
+
+
+@dataclass
+class GlobalConfig:
+    experiment: str
+    dataset: DatasetConfig
+    eval: TrackerEvalConfig
+    object_detection: ObjectDetectionInferenceConfig
+    algorithm: TrackerAlgorithmConfig
+    dataset_filter: DatasetFilterConfig = field(default_factory=DatasetFilterConfig)
+    path: PathConfig = field(default_factory=PathConfig)
+    postprocess: TrackerPostprocessConfig = field(default_factory=TrackerPostprocessConfig)
+    visualize: TrackerVisualizeConfig = field(default_factory=TrackerVisualizeConfig)
+
+    @property
+    def experiment_path(self) -> str:
+        """
+        Path where tracker results can be found.
+        """
+        return os.path.join(self.path.master, self.dataset.type, self.algorithm.name, self.experiment, self.eval.split)
+
+    def __post_init__(self):
+        """
+        Postprocess.
+        """
+        self.dataset.fullpath = os.path.join(self.path.assets, self.dataset.path, self.eval.split)
+
+
+# Configuring hydra config store
+# If config has `- global_config` in defaults then
+# full config is recursively instantiated
+cs = ConfigStore.instance()
+cs.store(name='global_config', node=GlobalConfig)

motrack-0.1.0/motrack/datasets/__init__.py

@@ -0,0 +1,6 @@
+"""
+Dataset interface.
+"""
+from motrack.datasets.base import BaseDataset
+from motrack.datasets.mot import MOTDataset
+from motrack.datasets.factory import dataset_factory