eye-cv 1.0.0__py3-none-any.whl

eye/core/trackers/__init__.py

@@ -0,0 +1 @@
+"""Tracker implementations."""

eye/core/trackers/botsort_tracker.py

@@ -0,0 +1,336 @@
+"""BoT-SORT: Robust Associations Multi-Pedestrian Tracking
+Based on: https://arxiv.org/abs/2206.14651
+Combines SORT with appearance features and camera motion compensation.
+"""
+
+import numpy as np
+from typing import List, Optional
+try:
+    import lap
+    LAP_AVAILABLE = True
+except ImportError:
+    LAP_AVAILABLE = False
+
+
+class KalmanBoxTracker:
+    """Kalman Filter for tracking bounding boxes with camera motion compensation."""
+    count = 0
+    
+    def __init__(self, bbox):
+        """Initialize tracker with bounding box [x1, y1, x2, y2]."""
+        # State: [x_center, y_center, area, aspect_ratio, vx, vy, va]
+        self.kf_x = np.zeros(7)
+        self.kf_x[:4] = self._convert_bbox_to_z(bbox)
+        
+        # Covariance matrix
+        self.kf_P = np.eye(7) * 10.
+        self.kf_P[4:, 4:] *= 1000.
+        
+        # State transition matrix
+        self.kf_F = np.eye(7)
+        for i in range(3):
+            self.kf_F[i, i+4] = 1.0
+        
+        # Measurement matrix
+        self.kf_H = np.eye(4, 7)
+        
+        # Process noise
+        self.kf_Q = np.eye(7)
+        self.kf_Q[4:, 4:] *= 0.01
+        
+        # Measurement noise
+        self.kf_R = np.eye(4) * 10.
+        
+        self.time_since_update = 0
+        self.id = KalmanBoxTracker.count
+        KalmanBoxTracker.count += 1
+        self.history = []
+        self.hits = 0
+        self.hit_streak = 0
+        self.age = 0
+        self.last_observation = bbox
+        
+        # For appearance features (placeholder)
+        self.smooth_feat = None
+        self.curr_feat = None
+        self.features = []
+        self.alpha = 0.9  # EMA coefficient
+        
+    def _convert_bbox_to_z(self, bbox):
+        """Convert [x1,y1,x2,y2] to [x,y,s,r]."""
+        w = bbox[2] - bbox[0]
+        h = bbox[3] - bbox[1]
+        x = bbox[0] + w/2.
+        y = bbox[1] + h/2.
+        s = w * h
+        r = w / float(h) if h != 0 else 1.0
+        return np.array([x, y, s, r])
+    
+    def _convert_x_to_bbox(self, x):
+        """Convert [x,y,s,r] to [x1,y1,x2,y2]."""
+        w = np.sqrt(x[2] * x[3])
+        h = x[2] / w if w != 0 else 1.0
+        return np.array([
+            x[0] - w/2.,
+            x[1] - h/2.,
+            x[0] + w/2.,
+            x[1] + h/2.
+        ])
+    
+    def update(self, bbox, feature=None):
+        """Update state with observed bbox and optional appearance feature."""
+        self.time_since_update = 0
+        self.history = []
+        self.hits += 1
+        self.hit_streak += 1
+        self.last_observation = bbox
+        
+        z = self._convert_bbox_to_z(bbox)
+        
+        # Kalman update
+        y = z - np.dot(self.kf_H, self.kf_x[:4])
+        S = np.dot(np.dot(self.kf_H, self.kf_P[:4, :4]), self.kf_H.T) + self.kf_R
+        K = np.dot(np.dot(self.kf_P[:4, :], self.kf_H.T), np.linalg.inv(S))
+        self.kf_x[:4] = self.kf_x[:4] + np.dot(K, y)
+        self.kf_P[:4, :4] = self.kf_P[:4, :4] - np.dot(np.dot(K, self.kf_H), self.kf_P[:4, :4])
+        
+        # Update appearance feature with EMA
+        if feature is not None:
+            self.curr_feat = feature
+            if self.smooth_feat is None:
+                self.smooth_feat = feature
+            else:
+                self.smooth_feat = self.alpha * self.smooth_feat + (1 - self.alpha) * feature
+            self.features.append(feature)
+    
+    def predict(self):
+        """Predict next state."""
+        self.kf_x = np.dot(self.kf_F, self.kf_x)
+        self.kf_P = np.dot(np.dot(self.kf_F, self.kf_P), self.kf_F.T) + self.kf_Q
+        
+        self.age += 1
+        if self.time_since_update > 0:
+            self.hit_streak = 0
+        self.time_since_update += 1
+        self.history.append(self._convert_x_to_bbox(self.kf_x))
+        return self.history[-1]
+    
+    def get_state(self):
+        """Return current bounding box estimate."""
+        return self._convert_x_to_bbox(self.kf_x)
+    
+    def apply_camera_motion(self, warp_matrix):
+        """Apply camera motion compensation using warp matrix."""
+        x1, y1, x2, y2 = self.get_state()
+        x1_, y1_, _ = warp_matrix @ np.array([x1, y1, 1.])
+        x2_, y2_, _ = warp_matrix @ np.array([x2, y2, 1.])
+        
+        # Update state
+        self.kf_x[:4] = self._convert_bbox_to_z([x1_, y1_, x2_, y2_])
+
+
+def iou_batch(bb_test, bb_gt):
+    """Compute IoU between two sets of boxes."""
+    bb_gt = np.expand_dims(bb_gt, 0)
+    bb_test = np.expand_dims(bb_test, 1)
+    
+    xx1 = np.maximum(bb_test[..., 0], bb_gt[..., 0])
+    yy1 = np.maximum(bb_test[..., 1], bb_gt[..., 1])
+    xx2 = np.minimum(bb_test[..., 2], bb_gt[..., 2])
+    yy2 = np.minimum(bb_test[..., 3], bb_gt[..., 3])
+    w = np.maximum(0., xx2 - xx1)
+    h = np.maximum(0., yy2 - yy1)
+    wh = w * h
+    
+    area_test = (bb_test[..., 2] - bb_test[..., 0]) * (bb_test[..., 3] - bb_test[..., 1])
+    area_gt = (bb_gt[..., 2] - bb_gt[..., 0]) * (bb_gt[..., 3] - bb_gt[..., 1])
+    
+    iou = wh / (area_test + area_gt - wh)
+    return iou
+
+
+def embedding_distance(tracks, detections, metric='cosine'):
+    """Compute appearance feature distance."""
+    track_features = np.array([trk.smooth_feat for trk in tracks if trk.smooth_feat is not None])
+    det_features = detections  # Assume detections are features
+    
+    if len(track_features) == 0 or len(det_features) == 0:
+        return np.ones((len(tracks), len(detections))) * 1e9
+    
+    if metric == 'cosine':
+        # Cosine distance
+        track_features = track_features / np.linalg.norm(track_features, axis=1, keepdims=True)
+        det_features = det_features / np.linalg.norm(det_features, axis=1, keepdims=True)
+        cost_matrix = 1 - np.dot(track_features, det_features.T)
+    else:
+        # Euclidean distance
+        cost_matrix = np.linalg.norm(track_features[:, None] - det_features[None, :], axis=2)
+    
+    return cost_matrix
+
+
+def linear_assignment(cost_matrix):
+    """Solve linear assignment problem."""
+    if not LAP_AVAILABLE:
+        # Fallback: greedy assignment
+        matches = []
+        cost = cost_matrix.copy()
+        for _ in range(min(cost.shape)):
+            i, j = np.unravel_index(cost.argmin(), cost.shape)
+            if cost[i, j] < 1e9:
+                matches.append([i, j])
+                cost[i, :] = 1e9
+                cost[:, j] = 1e9
+        
+        matches = np.array(matches) if matches else np.empty((0, 2), dtype=int)
+        unmatched_a = list(set(range(cost_matrix.shape[0])) - set(matches[:, 0]))
+        unmatched_b = list(set(range(cost_matrix.shape[1])) - set(matches[:, 1]))
+        return matches, unmatched_a, unmatched_b
+    
+    _, x, y = lap.lapjv(cost_matrix, extend_cost=True)
+    matches = [[i, x[i]] for i in range(len(x)) if x[i] >= 0]
+    unmatched_a = [i for i in range(len(x)) if x[i] < 0]
+    unmatched_b = [j for j in range(len(y)) if y[j] < 0]
+    return np.array(matches), unmatched_a, unmatched_b
+
+
+class BoTSORTTracker:
+    """BoT-SORT tracker with appearance features and camera motion compensation."""
+    
+    def __init__(
+        self,
+        max_age: int = 30,
+        min_hits: int = 3,
+        iou_threshold: float = 0.3,
+        proximity_thresh: float = 0.5,
+        appearance_thresh: float = 0.25
+    ):
+        """
+        Args:
+            max_age: Maximum frames to keep lost tracks
+            min_hits: Minimum hits to confirm track
+            iou_threshold: IoU threshold for matching
+            proximity_thresh: Proximity threshold for second matching
+            appearance_thresh: Appearance feature threshold
+        """
+        self.max_age = max_age
+        self.min_hits = min_hits
+        self.iou_threshold = iou_threshold
+        self.proximity_thresh = proximity_thresh
+        self.appearance_thresh = appearance_thresh
+        self.trackers = []
+        self.frame_count = 0
+        self.camera_update = np.eye(3)  # Camera motion warp matrix
+    
+    def update(self, detections, features=None):
+        """
+        Args:
+            detections: nx5 array [x1, y1, x2, y2, score]
+            features: Optional appearance features (n x feature_dim)
+        
+        Returns:
+            nx5 array [x1, y1, x2, y2, track_id]
+        """
+        self.frame_count += 1
+        
+        # Apply camera motion compensation
+        for trk in self.trackers:
+            trk.apply_camera_motion(self.camera_update)
+        
+        # Get predictions
+        trks = np.zeros((len(self.trackers), 5))
+        to_del = []
+        for t, trk in enumerate(trks):
+            pos = self.trackers[t].predict()
+            trk[:] = [pos[0], pos[1], pos[2], pos[3], 0]
+            if np.any(np.isnan(pos)):
+                to_del.append(t)
+        
+        trks = np.ma.compress_rows(np.ma.masked_invalid(trks))
+        for t in reversed(to_del):
+            self.trackers.pop(t)
+        
+        # First association: IoU matching
+        matched, unmatched_dets, unmatched_trks = self._associate_detections_to_trackers(
+            detections, trks, self.iou_threshold
+        )
+        
+        # Update matched trackers
+        for m in matched:
+            feat = features[m[0]] if features is not None else None
+            self.trackers[m[1]].update(detections[m[0], :4], feat)
+        
+        # Second association: Appearance + proximity for unmatched
+        if len(unmatched_dets) > 0 and len(unmatched_trks) > 0 and features is not None:
+            unmatched_trks_features = [self.trackers[i] for i in unmatched_trks]
+            unmatched_dets_features = features[unmatched_dets]
+            
+            # Combine IoU and appearance costs
+            iou_cost = 1 - iou_batch(detections[unmatched_dets, :4], trks[unmatched_trks, :4])
+            app_cost = embedding_distance(unmatched_trks_features, unmatched_dets_features)
+            
+            # Fuse costs
+            cost_matrix = 0.5 * iou_cost + 0.5 * app_cost
+            
+            matched2, unmatched_dets2, unmatched_trks2 = linear_assignment(cost_matrix)
+            
+            for m in matched2:
+                if cost_matrix[m[0], m[1]] < self.appearance_thresh:
+                    feat = features[unmatched_dets[m[0]]]
+                    self.trackers[unmatched_trks[m[1]]].update(detections[unmatched_dets[m[0]], :4], feat)
+            
+            unmatched_dets = [unmatched_dets[i] for i in unmatched_dets2]
+            unmatched_trks = [unmatched_trks[i] for i in unmatched_trks2]
+        
+        # Create new trackers
+        for i in unmatched_dets:
+            trk = KalmanBoxTracker(detections[i, :4])
+            if features is not None:
+                trk.curr_feat = features[i]
+                trk.smooth_feat = features[i]
+            self.trackers.append(trk)
+        
+        # Remove dead trackers
+        i = len(self.trackers)
+        ret = []
+        for trk in reversed(self.trackers):
+            d = trk.get_state()
+            if (trk.time_since_update < 1) and (trk.hit_streak >= self.min_hits or self.frame_count <= self.min_hits):
+                ret.append(np.concatenate((d, [trk.id])).reshape(1, -1))
+            i -= 1
+            if trk.time_since_update > self.max_age:
+                self.trackers.pop(i)
+        
+        if len(ret) > 0:
+            return np.concatenate(ret)
+        return np.empty((0, 5))
+    
+    def _associate_detections_to_trackers(self, detections, trackers, iou_threshold):
+        """Associate detections to tracked objects."""
+        if len(trackers) == 0:
+            return np.empty((0, 2), dtype=int), list(range(len(detections))), []
+        
+        iou_matrix = iou_batch(detections[:, :4], trackers[:, :4])
+        
+        if min(iou_matrix.shape) > 0:
+            matched_indices, unmatched_a, unmatched_b = linear_assignment(-iou_matrix)
+        else:
+            matched_indices = np.empty((0, 2), dtype=int)
+            unmatched_a = list(range(len(detections)))
+            unmatched_b = list(range(len(trackers)))
+        
+        # Filter out matched with low IoU
+        matches = []
+        for m in matched_indices:
+            if iou_matrix[m[0], m[1]] < iou_threshold:
+                unmatched_a.append(m[0])
+                unmatched_b.append(m[1])
+            else:
+                matches.append(m.reshape(1, 2))
+        
+        if len(matches) == 0:
+            matches = np.empty((0, 2), dtype=int)
+        else:
+            matches = np.concatenate(matches, axis=0)
+        
+        return matches, unmatched_a, unmatched_b

eye/core/trackers/bytetrack_tracker.py

@@ -0,0 +1,284 @@
+"""ByteTrack: Multi-Object Tracking by Associating Every Detection Box
+Based on: https://arxiv.org/abs/2110.06864
+"""
+
+import numpy as np
+from typing import List, Tuple
+try:
+    import lap
+    LAP_AVAILABLE = True
+except ImportError:
+    LAP_AVAILABLE = False
+
+
+class KalmanBoxTracker:
+    """Kalman Filter for tracking bounding boxes."""
+    count = 0
+    
+    def __init__(self, bbox):
+        """Initialize tracker with bounding box [x1, y1, x2, y2]."""
+        # State: [x_center, y_center, area, aspect_ratio, vx, vy, va, vr]
+        self.kf_x = np.zeros(8)
+        self.kf_x[:4] = self._convert_bbox_to_z(bbox)
+        
+        # Covariance matrix
+        self.kf_P = np.eye(8) * 10.
+        self.kf_P[4:, 4:] *= 1000.  # High uncertainty for velocities
+        
+        # State transition matrix
+        self.kf_F = np.eye(8)
+        for i in range(4):
+            self.kf_F[i, i+4] = 1.0  # Position += velocity
+        
+        # Measurement matrix
+        self.kf_H = np.eye(4, 8)
+        
+        # Process noise
+        self.kf_Q = np.eye(8)
+        self.kf_Q[4:, 4:] *= 0.01
+        
+        # Measurement noise
+        self.kf_R = np.eye(4)
+        
+        self.time_since_update = 0
+        self.id = KalmanBoxTracker.count
+        KalmanBoxTracker.count += 1
+        self.history = []
+        self.hits = 0
+        self.hit_streak = 0
+        self.age = 0
+        
+    def _convert_bbox_to_z(self, bbox):
+        """Convert [x1,y1,x2,y2] to [x,y,s,r] where s=area, r=aspect_ratio."""
+        w = bbox[2] - bbox[0]
+        h = bbox[3] - bbox[1]
+        x = bbox[0] + w/2.
+        y = bbox[1] + h/2.
+        s = w * h
+        r = w / float(h) if h != 0 else 1.0
+        return np.array([x, y, s, r])
+    
+    def _convert_x_to_bbox(self, x):
+        """Convert [x,y,s,r] to [x1,y1,x2,y2]."""
+        w = np.sqrt(x[2] * x[3])
+        h = x[2] / w if w != 0 else 1.0
+        return np.array([
+            x[0] - w/2.,
+            x[1] - h/2.,
+            x[0] + w/2.,
+            x[1] + h/2.
+        ])
+    
+    def update(self, bbox):
+        """Update state with observed bbox."""
+        self.time_since_update = 0
+        self.history = []
+        self.hits += 1
+        self.hit_streak += 1
+        
+        z = self._convert_bbox_to_z(bbox)
+        
+        # Kalman update
+        y = z - np.dot(self.kf_H, self.kf_x[:4])
+        S = np.dot(np.dot(self.kf_H, self.kf_P[:4, :4]), self.kf_H.T) + self.kf_R
+        K = np.dot(np.dot(self.kf_P[:4, :], self.kf_H.T), np.linalg.inv(S))
+        self.kf_x[:4] = self.kf_x[:4] + np.dot(K, y)
+        self.kf_P[:4, :4] = self.kf_P[:4, :4] - np.dot(np.dot(K, self.kf_H), self.kf_P[:4, :4])
+        
+    def predict(self):
+        """Predict next state."""
+        # Kalman predict
+        self.kf_x = np.dot(self.kf_F, self.kf_x)
+        self.kf_P = np.dot(np.dot(self.kf_F, self.kf_P), self.kf_F.T) + self.kf_Q
+        
+        self.age += 1
+        if self.time_since_update > 0:
+            self.hit_streak = 0
+        self.time_since_update += 1
+        self.history.append(self._convert_x_to_bbox(self.kf_x))
+        return self.history[-1]
+    
+    def get_state(self):
+        """Return current bounding box estimate."""
+        return self._convert_x_to_bbox(self.kf_x)
+
+
+def iou_batch(bb_test, bb_gt):
+    """Compute IoU between two sets of boxes."""
+    bb_gt = np.expand_dims(bb_gt, 0)
+    bb_test = np.expand_dims(bb_test, 1)
+    
+    xx1 = np.maximum(bb_test[..., 0], bb_gt[..., 0])
+    yy1 = np.maximum(bb_test[..., 1], bb_gt[..., 1])
+    xx2 = np.minimum(bb_test[..., 2], bb_gt[..., 2])
+    yy2 = np.minimum(bb_test[..., 3], bb_gt[..., 3])
+    w = np.maximum(0., xx2 - xx1)
+    h = np.maximum(0., yy2 - yy1)
+    wh = w * h
+    
+    area_test = (bb_test[..., 2] - bb_test[..., 0]) * (bb_test[..., 3] - bb_test[..., 1])
+    area_gt = (bb_gt[..., 2] - bb_gt[..., 0]) * (bb_gt[..., 3] - bb_gt[..., 1])
+    
+    iou = wh / (area_test + area_gt - wh)
+    return iou
+
+
+def linear_assignment(cost_matrix):
+    """Solve linear assignment problem."""
+    if not LAP_AVAILABLE:
+        # Fallback: greedy assignment
+        matches = []
+        cost = cost_matrix.copy()
+        for _ in range(min(cost.shape)):
+            i, j = np.unravel_index(cost.argmin(), cost.shape)
+            if cost[i, j] < 1e9:
+                matches.append([i, j])
+                cost[i, :] = 1e9
+                cost[:, j] = 1e9
+        
+        matches = np.array(matches) if matches else np.empty((0, 2), dtype=int)
+        unmatched_a = list(set(range(cost_matrix.shape[0])) - set(matches[:, 0]))
+        unmatched_b = list(set(range(cost_matrix.shape[1])) - set(matches[:, 1]))
+        return matches, unmatched_a, unmatched_b
+    
+    # Use lap for optimal assignment
+    _, x, y = lap.lapjv(cost_matrix, extend_cost=True)
+    matches = [[i, x[i]] for i in range(len(x)) if x[i] >= 0]
+    unmatched_a = [i for i in range(len(x)) if x[i] < 0]
+    unmatched_b = [j for j in range(len(y)) if y[j] < 0]
+    return np.array(matches), unmatched_a, unmatched_b
+
+
+class ByteTrackTracker:
+    """ByteTrack tracker with high/low confidence detection association."""
+    
+    def __init__(
+        self,
+        max_age: int = 30,
+        min_hits: int = 3,
+        iou_threshold: float = 0.3,
+        high_threshold: float = 0.5,
+        low_threshold: float = 0.1
+    ):
+        """
+        Args:
+            max_age: Maximum frames to keep lost tracks
+            min_hits: Minimum hits to confirm track
+            iou_threshold: IoU threshold for matching
+            high_threshold: High confidence threshold
+            low_threshold: Low confidence threshold
+        """
+        self.max_age = max_age
+        self.min_hits = min_hits
+        self.iou_threshold = iou_threshold
+        self.high_threshold = high_threshold
+        self.low_threshold = low_threshold
+        self.trackers = []
+        self.frame_count = 0
+    
+    def update(self, detections):
+        """
+        Args:
+            detections: nx5 array [x1, y1, x2, y2, score]
+        
+        Returns:
+            nx5 array [x1, y1, x2, y2, track_id]
+        """
+        self.frame_count += 1
+        
+        # Get predictions from existing trackers
+        trks = np.zeros((len(self.trackers), 5))
+        to_del = []
+        for t, trk in enumerate(trks):
+            pos = self.trackers[t].predict()
+            trk[:] = [pos[0], pos[1], pos[2], pos[3], 0]
+            if np.any(np.isnan(pos)):
+                to_del.append(t)
+        
+        trks = np.ma.compress_rows(np.ma.masked_invalid(trks))
+        for t in reversed(to_del):
+            self.trackers.pop(t)
+        
+        # Split detections by confidence
+        if len(detections) > 0:
+            high_dets = detections[detections[:, 4] >= self.high_threshold]
+            low_dets = detections[(detections[:, 4] >= self.low_threshold) & 
+                                 (detections[:, 4] < self.high_threshold)]
+        else:
+            high_dets = np.empty((0, 5))
+            low_dets = np.empty((0, 5))
+        
+        # First association: high confidence detections
+        matched, unmatched_dets, unmatched_trks = self._associate_detections_to_trackers(
+            high_dets, trks, self.iou_threshold
+        )
+        
+        # Update matched trackers
+        for m in matched:
+            self.trackers[m[1]].update(high_dets[m[0], :4])
+        
+        # Second association: low confidence detections with unmatched tracks
+        if len(low_dets) > 0 and len(unmatched_trks) > 0:
+            unmatched_trks_boxes = trks[unmatched_trks]
+            matched_low, unmatched_dets_low, unmatched_trks_low = self._associate_detections_to_trackers(
+                low_dets, unmatched_trks_boxes, self.iou_threshold
+            )
+            
+            for m in matched_low:
+                self.trackers[unmatched_trks[m[1]]].update(low_dets[m[0], :4])
+            
+            unmatched_trks = [unmatched_trks[i] for i in unmatched_trks_low]
+        
+        # Create new trackers for unmatched high confidence detections
+        for i in unmatched_dets:
+            trk = KalmanBoxTracker(high_dets[i, :4])
+            self.trackers.append(trk)
+        
+        # Remove dead trackers
+        i = len(self.trackers)
+        ret = []
+        for trk in reversed(self.trackers):
+            d = trk.get_state()
+            if (trk.time_since_update < 1) and (trk.hit_streak >= self.min_hits or self.frame_count <= self.min_hits):
+                ret.append(np.concatenate((d, [trk.id])).reshape(1, -1))
+            i -= 1
+            if trk.time_since_update > self.max_age:
+                self.trackers.pop(i)
+        
+        if len(ret) > 0:
+            return np.concatenate(ret)
+        return np.empty((0, 5))
+    
+    def _associate_detections_to_trackers(self, detections, trackers, iou_threshold):
+        """Associate detections to tracked objects."""
+        if len(trackers) == 0:
+            return np.empty((0, 2), dtype=int), list(range(len(detections))), []
+        
+        iou_matrix = iou_batch(detections[:, :4], trackers[:, :4])
+        
+        if min(iou_matrix.shape) > 0:
+            a = (iou_matrix > iou_threshold).astype(np.int32)
+            if a.sum(1).max() == 1 and a.sum(0).max() == 1:
+                matched_indices = np.stack(np.where(a), axis=1)
+            else:
+                matched_indices, unmatched_a, unmatched_b = linear_assignment(-iou_matrix)
+        else:
+            matched_indices = np.empty((0, 2), dtype=int)
+            unmatched_a = list(range(len(detections)))
+            unmatched_b = list(range(len(trackers)))
+        
+        # Filter out matched with low IoU
+        matches = []
+        for m in matched_indices:
+            if iou_matrix[m[0], m[1]] < iou_threshold:
+                unmatched_a.append(m[0])
+                unmatched_b.append(m[1])
+            else:
+                matches.append(m.reshape(1, 2))
+        
+        if len(matches) == 0:
+            matches = np.empty((0, 2), dtype=int)
+        else:
+            matches = np.concatenate(matches, axis=0)
+        
+        return matches, unmatched_a, unmatched_b