Upload 22 files

src/__init__.py

@@ -0,0 +1,22 @@
+"""
+NETRA Source Code
+Core detection and pipeline modules
+"""
+
+from .detectors import (
+    YOLODetector,
+    ViolenceDetector,
+    WeaponPersonDetector,
+    PoseDetection,
+    AnomalyDetector,
+)
+from .pipeline import VideoCapture
+
+__all__ = [
+    'YOLODetector',
+    'ViolenceDetector',
+    'WeaponPersonDetector',
+    'PoseDetection',
+    'AnomalyDetector',
+    'VideoCapture',
+]

src/detectors/__init__.py

@@ -0,0 +1,19 @@
+"""
+NETRA Detection Modules
+Core AI detection components for video surveillance
+"""
+
+from .yolo_detector import YOLODetector, Detection
+from .violence_detector import ViolenceDetector
+from .weapon_detector import WeaponPersonDetector
+from .pose_detector import PoseDetection
+from .anomaly_detector import AnomalyDetector
+
+__all__ = [
+    'YOLODetector',
+    'Detection',
+    'ViolenceDetector',
+    'WeaponPersonDetector',
+    'PoseDetection',
+    'AnomalyDetector',
+]

src/detectors/anomaly_detector.py

@@ -0,0 +1,194 @@
+"""
+Anomaly Detection Module
+Loads and runs inference using the anomaly detection model
+"""
+
+import cv2
+import numpy as np
+import torch
+from pathlib import Path
+from typing import Optional, Tuple, Dict, Any
+from dataclasses import dataclass
+
+
+@dataclass
+class AnomalyDetection:
+    """Anomaly detection result."""
+    is_anomaly: bool = False
+    confidence: float = 0.0
+    anomaly_score: float = 0.0
+    alert_level: str = "SAFE"
+    
+    @property
+    def description(self) -> str:
+        """Get description based on anomaly detection."""
+        if not self.is_anomaly:
+            return f"Normal behavior detected (score: {self.anomaly_score:.2f})"
+        elif self.confidence >= 0.8:
+            return f"HIGH RISK - Anomaly detected (score: {self.anomaly_score:.2f})"
+        elif self.confidence >= 0.6:
+            return f"MEDIUM RISK - Possible anomaly (score: {self.anomaly_score:.2f})"
+        else:
+            return f"LOW RISK - Minor anomaly (score: {self.anomaly_score:.2f})"
+
+
+class AnomalyDetector:
+    """Anomaly detection using trained model."""
+    
+    def __init__(self, 
+                 model_path: str,
+                 input_size: Tuple[int, int] = (224, 224),
+                 device: str = 'cpu',
+                 anomaly_threshold: float = 0.5):
+        """
+        Initialize anomaly detector.
+        
+        Args:
+            model_path: Path to trained anomaly detection model (.bin file)
+            input_size: Input frame size for the model
+            device: Device to run model on ('cpu' or 'cuda')
+            anomaly_threshold: Threshold for classifying as anomaly
+        """
+        self.model_path = Path(model_path)
+        self.input_size = input_size
+        self.device = device
+        self.anomaly_threshold = anomaly_threshold
+        self.model = None
+        self.frame_buffer = []
+        self.buffer_size = 16  # Number of frames to buffer
+        
+        self._load_model()
+    
+    def _load_model(self):
+        """Load the anomaly detection model."""
+        if not self.model_path.exists():
+            raise FileNotFoundError(f"Model not found: {self.model_path}")
+        
+        self.is_tensorflow = False
+        
+        try:
+            # Try loading as PyTorch model first
+            self.model = torch.load(str(self.model_path), map_location=self.device)
+            self.model.eval()
+            print(f"[OK] Anomaly detection model (PyTorch) loaded from: {self.model_path}")
+        except Exception as e:
+            try:
+                # Try loading as TensorFlow SavedModel
+                import tensorflow as tf
+                self.model = tf.keras.models.load_model(str(self.model_path))
+                self.is_tensorflow = True
+                print(f"[OK] Anomaly detection model (TensorFlow) loaded from: {self.model_path}")
+            except Exception as tf_e:
+                raise RuntimeError(
+                    f"Failed to load anomaly detection model. "
+                    f"PyTorch error: {e}, TensorFlow error: {tf_e}"
+                )
+    
+    def preprocess_frame(self, frame: np.ndarray) -> np.ndarray:
+        """Preprocess frame for model inference."""
+        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+        resized = cv2.resize(rgb, self.input_size)
+        normalized = resized.astype(np.float32) / 255.0
+        return normalized
+    
+    def predict_frame(self, frame: np.ndarray) -> Optional[AnomalyDetection]:
+        """
+        Predict anomaly for a single frame.
+        
+        Args:
+            frame: Input frame (BGR format from OpenCV)
+        
+        Returns:
+            AnomalyDetection result or None if not enough frames buffered
+        """
+        # Add frame to buffer
+        processed = self.preprocess_frame(frame)
+        self.frame_buffer.append(processed)
+        
+        # Keep buffer at specified size
+        if len(self.frame_buffer) > self.buffer_size:
+            self.frame_buffer.pop(0)
+        
+        # Need minimum frames for temporal analysis
+        if len(self.frame_buffer) < max(1, self.buffer_size // 2):
+            return None
+        
+        return self._inference()
+    
+    def _inference(self) -> AnomalyDetection:
+        """Run inference on buffered frames."""
+        try:
+            # Prepare input
+            input_data = np.array(self.frame_buffer, dtype=np.float32)
+            
+            if self.is_tensorflow:
+                # TensorFlow model
+                if input_data.ndim == 3:  # Single sample
+                    input_data = np.expand_dims(input_data, axis=0)
+                
+                prediction = self.model.predict(input_data, verbose=0)
+            else:
+                # PyTorch model
+                input_tensor = torch.FloatTensor(input_data).to(self.device)
+                if input_tensor.dim() == 3:  # Add batch dimension
+                    input_tensor = input_tensor.unsqueeze(0)
+                
+                with torch.no_grad():
+                    prediction = self.model(input_tensor)
+            
+            # Extract anomaly score
+            anomaly_score = self._extract_score(prediction)
+            is_anomaly = anomaly_score >= self.anomaly_threshold
+            confidence = min(anomaly_score, 1.0)
+            
+            return AnomalyDetection(
+                is_anomaly=is_anomaly,
+                confidence=confidence,
+                anomaly_score=anomaly_score,
+                alert_level=self._get_alert_level(confidence, is_anomaly)
+            )
+        except Exception as e:
+            print(f"[ERROR] Anomaly detection inference failed: {e}")
+            return AnomalyDetection(is_anomaly=False, confidence=0.0, alert_level="ERROR")
+    
+    @staticmethod
+    def _extract_score(prediction) -> float:
+        """Extract anomaly score from model output."""
+        if isinstance(prediction, torch.Tensor):
+            prediction = prediction.cpu().numpy()
+        
+        # Flatten and get last value or mean
+        values = np.array(prediction).flatten()
+        
+        if values.size == 0:
+            return 0.0
+        
+        # Return mean or last value depending on output shape
+        if len(values) == 1:
+            return float(values[0])
+        
+        return float(np.mean(values))
+    
+    @staticmethod
+    def _get_alert_level(confidence: float, is_anomaly: bool) -> str:
+        """Get alert level based on confidence and anomaly status."""
+        if not is_anomaly:
+            return "SAFE"
+        elif confidence >= 0.8:
+            return "HIGH RISK"
+        elif confidence >= 0.6:
+            return "MEDIUM RISK"
+        else:
+            return "LOW RISK"
+    
+    def reset(self):
+        """Reset frame buffer for new session."""
+        self.frame_buffer = []
+    
+    def get_buffer_status(self) -> Dict[str, Any]:
+        """Get current buffer status."""
+        return {
+            'buffered_frames': len(self.frame_buffer),
+            'buffer_size': self.buffer_size,
+            'is_ready': len(self.frame_buffer) >= max(1, self.buffer_size // 2)
+        }

src/detectors/pose_detector.py

@@ -0,0 +1,672 @@
+from pathlib import Path
+
+import cv2
+import numpy as np
+from ultralytics import YOLO
+
+
+class PoseDetection:
+    def __init__(self, model_path="yolo11n-pose.pt", conf=0.25, imgsz=640, device="cpu"):
+        self.model_path = Path(model_path)
+        if not self.model_path.exists():
+            raise FileNotFoundError(
+                f"Pose model not found: {self.model_path}. "
+                "Add a YOLO pose model file such as yolo11n-pose.pt to the project or pass --model."
+            )
+
+        self.model = YOLO(str(self.model_path))
+        self.conf = conf
+        self.imgsz = imgsz
+        self.device = device
+        self.movement_evaluator = MovementRiskEvaluator()
+
+    def reset_movement_state(self):
+        self.movement_evaluator.reset()
+
+    def assess_movement(self, result):
+        return self.movement_evaluator.assess(result)
+
+    def predict(self, source):
+        return self.model.predict(
+            source=source,
+            conf=self.conf,
+            imgsz=self.imgsz,
+            device=self.device,
+            verbose=False,
+        )
+
+    def annotate(self, source):
+        result = self.predict(source)[0]
+        annotated = result.plot()
+        return result, annotated
+
+    @staticmethod
+    def format_detections(result, source_name: str):
+        keypoints = getattr(result, "keypoints", None)
+        if keypoints is None or keypoints.xy is None or len(keypoints.xy) == 0:
+            return [f"{source_name}: no poses detected"]
+
+        lines = [f"{source_name}: detected {len(keypoints.xy)} pose(s)"]
+        confidences = getattr(keypoints, "conf", None)
+        for index, pose_points in enumerate(keypoints.xy, start=1):
+            visible_points = int(np.sum(np.any(pose_points.cpu().numpy() > 0, axis=1)))
+            if confidences is not None:
+                pose_conf = float(np.nanmean(confidences[index - 1].cpu().numpy()))
+                lines.append(
+                    f"Pose {index}: {visible_points} visible keypoints, average confidence {pose_conf:.2f}"
+                )
+            else:
+                lines.append(f"Pose {index}: {visible_points} visible keypoints")
+        return lines
+
+    def save_image_result(self, image_path, output_dir):
+        image_path = Path(image_path)
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        self.reset_movement_state()
+        result, annotated = self.annotate(str(image_path))
+        movement = self.assess_movement(result)
+        output_path = output_dir / image_path.name
+        preview_path = output_dir / f"{image_path.stem}_preview.png"
+        cv2.imwrite(str(output_path), annotated)
+        cv2.imwrite(str(preview_path), annotated)
+
+        lines = self.format_detections(result, image_path.name)
+        lines.append(
+            f"Movement risk: {movement['risk_level']} | action: {movement['action']} | score: {movement['risk_score']:.2f}"
+        )
+
+        return {
+            "type": "image",
+            "source": str(image_path),
+            "output_path": str(output_path),
+            "preview_path": str(preview_path),
+            "lines": lines,
+            "movement": movement,
+        }
+
+    def save_video_result(self, video_path, output_dir, show=False, window_name="Pose Detection"):
+        video_path = Path(video_path)
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        cap = cv2.VideoCapture(str(video_path))
+        if not cap.isOpened():
+            raise RuntimeError(f"Could not open video: {video_path}")
+
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) or 640
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) or 480
+        fps = cap.get(cv2.CAP_PROP_FPS) or 25.0
+
+        output_path = output_dir / f"{video_path.stem}_pose.mp4"
+        preview_path = output_dir / f"{video_path.stem}_preview.png"
+        writer = cv2.VideoWriter(
+            str(output_path),
+            cv2.VideoWriter_fourcc(*"mp4v"),
+            fps,
+            (width, height),
+        )
+
+        frame_count = 0
+        last_result = None
+        last_movement = None
+        risk_counters = {"SAFE": 0, "LOW_RISK": 0, "HIGH_RISK": 0}
+        preview_saved = False
+        self.reset_movement_state()
+        while True:
+            ok, frame = cap.read()
+            if not ok:
+                break
+
+            last_result, annotated = self.annotate(frame)
+            last_movement = self.assess_movement(last_result)
+            risk_counters[last_movement["risk_level"]] += 1
+            self.draw_movement_banner(annotated, last_movement)
+            writer.write(annotated)
+            if not preview_saved:
+                cv2.imwrite(str(preview_path), annotated)
+                preview_saved = True
+
+            if show:
+                cv2.imshow(window_name, annotated)
+                if cv2.waitKey(1) & 0xFF == ord("q"):
+                    break
+
+            frame_count += 1
+
+        cap.release()
+        writer.release()
+        cv2.destroyAllWindows()
+
+        lines = [f"{video_path.name}: processed {frame_count} frames"]
+        if last_result is not None:
+            lines.extend(self.format_detections(last_result, f"{video_path.name} last frame"))
+        if last_movement is not None:
+            lines.append(
+                f"Last movement risk: {last_movement['risk_level']} | action: {last_movement['action']} | score: {last_movement['risk_score']:.2f}"
+            )
+            lines.append(
+                "Risk distribution: "
+                f"SAFE={risk_counters['SAFE']}, LOW_RISK={risk_counters['LOW_RISK']}, HIGH_RISK={risk_counters['HIGH_RISK']}"
+            )
+
+        return {
+            "type": "video",
+            "source": str(video_path),
+            "output_path": str(output_path),
+            "preview_path": str(preview_path) if preview_saved else None,
+            "lines": lines,
+            "movement": last_movement,
+            "risk_counters": risk_counters,
+        }
+
+    def run_webcam(self, camera_index=0, output_dir="runs/pose_inference", show=True):
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        cap = cv2.VideoCapture(camera_index)
+        if not cap.isOpened():
+            raise RuntimeError(f"Could not open webcam index: {camera_index}")
+
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) or 640
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) or 480
+        fps = cap.get(cv2.CAP_PROP_FPS) or 20.0
+        output_path = output_dir / f"webcam_{camera_index}_pose.mp4"
+        writer = cv2.VideoWriter(
+            str(output_path),
+            cv2.VideoWriter_fourcc(*"mp4v"),
+            fps,
+            (width, height),
+        )
+
+        frame_count = 0
+        last_result = None
+        last_movement = None
+        risk_counters = {"SAFE": 0, "LOW_RISK": 0, "HIGH_RISK": 0}
+        preview_path = output_dir / f"webcam_{camera_index}_preview.png"
+        preview_saved = False
+        self.reset_movement_state()
+        while True:
+            ok, frame = cap.read()
+            if not ok:
+                break
+
+            last_result, annotated = self.annotate(frame)
+            last_movement = self.assess_movement(last_result)
+            risk_counters[last_movement["risk_level"]] += 1
+            self.draw_movement_banner(annotated, last_movement)
+            writer.write(annotated)
+            if not preview_saved:
+                cv2.imwrite(str(preview_path), annotated)
+                preview_saved = True
+
+            if show:
+                cv2.imshow("Pose Detection", annotated)
+                if cv2.waitKey(1) & 0xFF == ord("q"):
+                    break
+
+            frame_count += 1
+
+        cap.release()
+        writer.release()
+        cv2.destroyAllWindows()
+
+        lines = [f"webcam_{camera_index}: processed {frame_count} frames"]
+        if last_result is not None:
+            lines.extend(self.format_detections(last_result, f"webcam_{camera_index} last frame"))
+        if last_movement is not None:
+            lines.append(
+                f"Last movement risk: {last_movement['risk_level']} | action: {last_movement['action']} | score: {last_movement['risk_score']:.2f}"
+            )
+            lines.append(
+                "Risk distribution: "
+                f"SAFE={risk_counters['SAFE']}, LOW_RISK={risk_counters['LOW_RISK']}, HIGH_RISK={risk_counters['HIGH_RISK']}"
+            )
+
+        return {
+            "type": "webcam",
+            "source": str(camera_index),
+            "output_path": str(output_path),
+            "preview_path": str(preview_path) if preview_saved else None,
+            "lines": lines,
+            "movement": last_movement,
+            "risk_counters": risk_counters,
+        }
+
+    @staticmethod
+    def draw_movement_banner(frame, movement):
+        level = movement["risk_level"]
+        action = movement["action"]
+        score = movement["risk_score"]
+        if level == "HIGH_RISK":
+            color = (0, 0, 255)
+        elif level == "LOW_RISK":
+            color = (0, 165, 255)
+        else:
+            color = (0, 128, 0)
+
+        text = f"Risk: {level} | Action: {action} | Score: {score:.2f}"
+        cv2.rectangle(frame, (0, 0), (frame.shape[1], 40), color, -1)
+        cv2.putText(
+            frame,
+            text,
+            (10, 27),
+            cv2.FONT_HERSHEY_SIMPLEX,
+            0.62,
+            (255, 255, 255),
+            2,
+            cv2.LINE_AA,
+        )
+
+
+class MovementRiskEvaluator:
+    def __init__(self, keypoint_conf_threshold=0.3):
+        self.keypoint_conf_threshold = keypoint_conf_threshold
+        self.prev_people = None
+
+    def reset(self):
+        self.prev_people = None
+
+    def assess(self, result):
+        people = self._extract_people(result)
+        if not people:
+            self.prev_people = None
+            return {
+                "risk_level": "SAFE",
+                "action": "other",
+                "risk_score": 0.0,
+                "details": "no_pose",
+            }
+
+        speed_stats = self._compute_motion(people)
+        crowd_stats = self._compute_crowd_features(people)
+        pose_stats = self._compute_pose_features(people)
+
+        # Compute violence action scores
+        punch_score = self._score_punch(speed_stats, crowd_stats, pose_stats)
+        kick_score = self._score_kick(speed_stats, crowd_stats, pose_stats)
+        slap_score = self._score_slap(speed_stats, crowd_stats, pose_stats)
+        push_score = self._score_push(speed_stats, crowd_stats, pose_stats)
+        throw_score = self._score_throw(speed_stats, crowd_stats, pose_stats)
+        headbutt_score = self._score_headbutt(speed_stats, crowd_stats, pose_stats)
+        choking_score = self._score_choking(speed_stats, crowd_stats, pose_stats)
+        weapon_score = self._score_weapon(speed_stats, crowd_stats, pose_stats)
+        aggressive_grab_score = self._score_aggressive_grab(speed_stats, crowd_stats, pose_stats)
+        grappling_score = self._score_grappling(speed_stats, crowd_stats, pose_stats)
+        falling_score = self._score_falling(speed_stats, crowd_stats, pose_stats)
+        defensive_score = self._score_defensive(speed_stats, crowd_stats, pose_stats)
+        running_score = self._score_running(speed_stats, crowd_stats, pose_stats)
+
+        # Find best matching action
+        action_scores = {
+            "punch": punch_score,
+            "kick": kick_score,
+            "slap": slap_score,
+            "push": push_score,
+            "throw": throw_score,
+            "headbutt": headbutt_score,
+            "choking": choking_score,
+            "weapon": weapon_score,
+            "aggressive_grab": aggressive_grab_score,
+            "grappling": grappling_score,
+            "falling": falling_score,
+            "defensive": defensive_score,
+            "running": running_score,
+            "other": 0.0,
+        }
+
+        best_action = max(action_scores, key=action_scores.get)
+        risk_score = action_scores[best_action]
+
+        # Determine risk level based on action and score
+        if best_action in ["punch", "kick", "throw", "headbutt", "choking", "weapon", "grappling"]:
+            if risk_score >= 0.85:
+                risk_level = "HIGH_RISK"
+            elif risk_score >= 0.5:
+                risk_level = "LOW_RISK"
+            else:
+                risk_level = "SAFE"
+                best_action = "other"
+        elif best_action in ["slap", "push", "aggressive_grab", "falling"]:
+            if risk_score >= 0.8:
+                risk_level = "HIGH_RISK"
+            elif risk_score >= 0.5:
+                risk_level = "LOW_RISK"
+            else:
+                risk_level = "SAFE"
+                best_action = "other"
+        elif best_action == "defensive":
+            risk_level = "LOW_RISK"
+        elif best_action == "running":
+            risk_level = "LOW_RISK" if risk_score >= 0.5 else "SAFE"
+        else:
+            risk_level = "SAFE"
+
+        self.prev_people = people
+        return {
+            "risk_level": risk_level,
+            "action": best_action,
+            "risk_score": float(min(risk_score, 1.5)),
+            "details": action_scores,
+        }
+
+    def _extract_people(self, result):
+        keypoints = getattr(result, "keypoints", None)
+        if keypoints is None or keypoints.xy is None or len(keypoints.xy) == 0:
+            return []
+
+        xy_sets = keypoints.xy.cpu().numpy()
+        conf_sets = keypoints.conf.cpu().numpy() if getattr(keypoints, "conf", None) is not None else None
+        people = []
+
+        for i, points in enumerate(xy_sets):
+            conf = conf_sets[i] if conf_sets is not None else np.ones(points.shape[0], dtype=np.float32)
+            valid = conf >= self.keypoint_conf_threshold
+            if np.count_nonzero(valid) < 5:
+                continue
+
+            torso = self._torso_scale(points, conf)
+            center = self._person_center(points, conf)
+            arm_extension = self._arm_extension(points, conf, torso)
+            people.append(
+                {
+                    "points": points,
+                    "conf": conf,
+                    "torso": torso,
+                    "center": center,
+                    "arm_extension": arm_extension,
+                }
+            )
+        return people
+
+    @staticmethod
+    def _distance(a, b):
+        return float(np.linalg.norm(np.array(a, dtype=np.float32) - np.array(b, dtype=np.float32)))
+
+    def _torso_scale(self, points, conf):
+        pairs = [(5, 11), (6, 12), (5, 6), (11, 12)]
+        lengths = []
+        for a, b in pairs:
+            if conf[a] >= self.keypoint_conf_threshold and conf[b] >= self.keypoint_conf_threshold:
+                lengths.append(self._distance(points[a], points[b]))
+        if lengths:
+            return max(8.0, float(np.mean(lengths)))
+        return 40.0
+
+    def _person_center(self, points, conf):
+        preferred = [5, 6, 11, 12]
+        coords = [points[idx] for idx in preferred if conf[idx] >= self.keypoint_conf_threshold]
+        if not coords:
+            coords = [points[idx] for idx in range(points.shape[0]) if conf[idx] >= self.keypoint_conf_threshold]
+        if not coords:
+            return np.array([0.0, 0.0], dtype=np.float32)
+        return np.mean(np.array(coords, dtype=np.float32), axis=0)
+
+    def _arm_extension(self, points, conf, torso):
+        extensions = []
+        for shoulder_idx, wrist_idx in [(5, 9), (6, 10)]:
+            if conf[shoulder_idx] >= self.keypoint_conf_threshold and conf[wrist_idx] >= self.keypoint_conf_threshold:
+                extensions.append(self._distance(points[shoulder_idx], points[wrist_idx]) / max(torso, 1e-6))
+        if not extensions:
+            return 0.0
+        return float(np.max(extensions))
+
+    def _compute_motion(self, people):
+        if not self.prev_people:
+            return {"body_speed": 0.0, "arm_speed": 0.0, "leg_speed": 0.0}
+
+        count = min(len(people), len(self.prev_people))
+        if count == 0:
+            return {"body_speed": 0.0, "arm_speed": 0.0, "leg_speed": 0.0}
+
+        body_speeds = []
+        arm_speeds = []
+        leg_speeds = []
+
+        for i in range(count):
+            cur = people[i]
+            prev = self.prev_people[i]
+            scale = max((cur["torso"] + prev["torso"]) * 0.5, 1e-6)
+
+            body_speeds.append(self._distance(cur["center"], prev["center"]) / scale)
+            arm_speeds.append(self._average_joint_speed(cur, prev, [7, 8, 9, 10], scale))
+            leg_speeds.append(self._average_joint_speed(cur, prev, [13, 14, 15, 16], scale))
+
+        return {
+            "body_speed": float(np.max(body_speeds) if body_speeds else 0.0),
+            "arm_speed": float(np.max(arm_speeds) if arm_speeds else 0.0),
+            "leg_speed": float(np.max(leg_speeds) if leg_speeds else 0.0),
+        }
+
+    def _average_joint_speed(self, cur, prev, indices, scale):
+        values = []
+        for idx in indices:
+            if cur["conf"][idx] >= self.keypoint_conf_threshold and prev["conf"][idx] >= self.keypoint_conf_threshold:
+                values.append(self._distance(cur["points"][idx], prev["points"][idx]) / scale)
+        if not values:
+            return 0.0
+        return float(np.mean(values))
+
+    @staticmethod
+    def _compute_crowd_features(people):
+        if len(people) < 2:
+            return {"close_people": 0.0, "rapid_multi_person": 0.0, "arm_extension": float(max(p["arm_extension"] for p in people))}
+
+        min_center_dist = 1e9
+        avg_torso = max(8.0, float(np.mean([p["torso"] for p in people])))
+        for i in range(len(people)):
+            for j in range(i + 1, len(people)):
+                d = float(np.linalg.norm(people[i]["center"] - people[j]["center"]))
+                min_center_dist = min(min_center_dist, d)
+
+        close_people = max(0.0, 1.2 - (min_center_dist / (avg_torso * 2.2)))
+        rapid_multi_person = 1.0 if close_people > 0.35 else 0.0
+        arm_extension = float(max(p["arm_extension"] for p in people))
+        return {
+            "close_people": float(close_people),
+            "rapid_multi_person": float(rapid_multi_person),
+            "arm_extension": arm_extension,
+        }
+
+    def _compute_pose_features(self, people):
+        """Compute detailed pose features for all violence types."""
+        features = {
+            "leg_extension": 0.0,
+            "head_position": [0.0, 0.0],
+            "body_angle": 0.0,
+            "arm_angles": [0.0, 0.0],
+            "upward_motion": 0.0,
+            "downward_motion": 0.0,
+            "ground_contact": False,
+        }
+        if not people:
+            return features
+
+        person = people[0]
+        points = person["points"]
+        conf = person["conf"]
+
+        # Leg extension
+        if conf[13] >= self.keypoint_conf_threshold and conf[14] >= self.keypoint_conf_threshold:
+            leg_ext = self._distance(points[13], points[14]) / max(person["torso"], 1e-6)
+            features["leg_extension"] = float(leg_ext)
+
+        # Head position
+        if conf[0] >= self.keypoint_conf_threshold:
+            features["head_position"] = list(map(float, points[0]))
+
+        # Body angle (from head to hip)
+        if conf[0] >= self.keypoint_conf_threshold and conf[11] >= self.keypoint_conf_threshold:
+            vec = points[11] - points[0]
+            angle = float(np.arctan2(vec[1], vec[0]) * 180 / np.pi)
+            features["body_angle"] = angle
+
+        # Arm angles
+        arm_angles = []
+        for shoulder, elbow, wrist in [(5, 7, 9), (6, 8, 10)]:
+            if (conf[shoulder] >= self.keypoint_conf_threshold and 
+                conf[elbow] >= self.keypoint_conf_threshold and 
+                conf[wrist] >= self.keypoint_conf_threshold):
+                v1 = points[shoulder] - points[elbow]
+                v2 = points[wrist] - points[elbow]
+                denom = np.linalg.norm(v1) * np.linalg.norm(v2)
+                if denom > 1e-6:
+                    cos_angle = np.dot(v1, v2) / denom
+                    angle = np.arccos(np.clip(cos_angle, -1, 1)) * 180 / np.pi
+                    arm_angles.append(float(angle))
+        if arm_angles:
+            features["arm_angles"] = arm_angles
+
+        # Vertical motion if previous frame exists
+        if self.prev_people and len(self.prev_people) > 0:
+            prev = self.prev_people[0]
+            prev_torso = max(prev["torso"], 1e-6)
+            head_motion = self._distance(points[0], prev["points"][0]) if conf[0] >= self.keypoint_conf_threshold else 0.0
+            hip_motion = self._distance(person["center"], prev["center"])
+            if points[0][1] < prev["points"][0][1]:
+                features["upward_motion"] = head_motion / prev_torso
+            else:
+                features["downward_motion"] = head_motion / prev_torso
+
+        # Ground contact (low ankle/knee positions)
+        if conf[15] >= self.keypoint_conf_threshold or conf[16] >= self.keypoint_conf_threshold:
+            ankle_y = min(points[15][1] if conf[15] >= self.keypoint_conf_threshold else 1e9,
+                         points[16][1] if conf[16] >= self.keypoint_conf_threshold else 1e9)
+            hip_y = person["center"][1]
+            if ankle_y > hip_y * 0.8:
+                features["ground_contact"] = True
+
+        return features
+
+    def _score_punch(self, speed_stats, crowd_stats, pose_stats):
+        """Detect punching motion: high arm speed, extended arm, close to another person."""
+        score = speed_stats["arm_speed"] * 1.5
+        if crowd_stats["close_people"] > 0.3:
+            score += crowd_stats["close_people"] * 0.7
+        if crowd_stats["arm_extension"] > 1.1:
+            score += 0.4
+        score = max(0.0, score - 0.5)
+        return float(min(score, 1.0))
+
+    def _score_kick(self, speed_stats, crowd_stats, pose_stats):
+        """Detect kicking motion: very high leg speed, leg extension."""
+        score = speed_stats["leg_speed"] * 1.8
+        if pose_stats["leg_extension"] > 1.2:
+            score += 0.5
+        score = max(0.0, score - 0.55)
+        return float(min(score, 1.0))
+
+    def _score_slap(self, speed_stats, crowd_stats, pose_stats):
+        """Detect slapping motion: high arm speed, close range, high arm extension."""
+        score = speed_stats["arm_speed"] * 1.4
+        if crowd_stats["close_people"] > 0.35:
+            score += 0.5
+        if crowd_stats["arm_extension"] > 1.0:
+            score += 0.3
+        score = max(0.0, score - 0.6)
+        return float(min(score, 1.0))
+
+    def _score_push(self, speed_stats, crowd_stats, pose_stats):
+        """Detect pushing motion: arm speed + body speed, close proximity."""
+        score = (speed_stats["arm_speed"] * 0.9 + speed_stats["body_speed"] * 1.0)
+        if crowd_stats["close_people"] > 0.25:
+            score += 0.6
+        score = max(0.0, score - 0.45)
+        return float(min(score, 1.0))
+
+    def _score_throw(self, speed_stats, crowd_stats, pose_stats):
+        """Detect throwing motion: upward arm motion + body extension."""
+        score = 0.0
+        if pose_stats["upward_motion"] > 0.3:
+            score += pose_stats["upward_motion"] * 1.5
+        score += speed_stats["arm_speed"] * 0.8
+        if crowd_stats["arm_extension"] > 1.3:
+            score += 0.4
+        score = max(0.0, score - 0.3)
+        return float(min(score, 1.0))
+
+    def _score_headbutt(self, speed_stats, crowd_stats, pose_stats):
+        """Detect headbutt: rapid head motion toward another person."""
+        score = 0.0
+        if crowd_stats["close_people"] > 0.5:
+            score += 0.8
+        if pose_stats["body_angle"] != 0.0:
+            score += abs(pose_stats["body_angle"]) / 180.0 * 0.5
+        score += speed_stats["body_speed"] * 0.6
+        score = max(0.0, score - 0.4)
+        return float(min(score, 1.0))
+
+    def _score_choking(self, speed_stats, crowd_stats, pose_stats):
+        """Detect choking: arms around neck area, very close proximity."""
+        score = 0.0
+        if crowd_stats["close_people"] > 0.6:
+            score += 0.9
+        if len(pose_stats["arm_angles"]) > 0 and min(pose_stats["arm_angles"]) < 90:
+            score += 0.6
+        score += speed_stats["arm_speed"] * 0.5
+        score = max(0.0, score - 0.5)
+        return float(min(score, 1.0))
+
+    def _score_weapon(self, speed_stats, crowd_stats, pose_stats):
+        """Detect weapon use: irregular arm motion patterns, quick directional changes."""
+        score = 0.0
+        if speed_stats["arm_speed"] > 0.8:
+            score += 0.5
+        if speed_stats["leg_speed"] > 0.6:
+            score += 0.3
+        if crowd_stats["close_people"] > 0.3:
+            score += 0.3
+        score = max(0.0, score - 0.35)
+        return float(min(score, 1.0))
+
+    def _score_aggressive_grab(self, speed_stats, crowd_stats, pose_stats):
+        """Detect aggressive grabbing: very close proximity, intertwined arms."""
+        score = 0.0
+        if crowd_stats["close_people"] > 0.55:
+            score += 0.9
+        if len(pose_stats["arm_angles"]) > 0 and any(a < 100 for a in pose_stats["arm_angles"]):
+            score += 0.5
+        score += speed_stats["arm_speed"] * 0.6
+        score = max(0.0, score - 0.4)
+        return float(min(score, 1.0))
+
+    def _score_grappling(self, speed_stats, crowd_stats, pose_stats):
+        """Detect grappling: multiple body contacts, wrestling motion."""
+        score = 0.0
+        if self.prev_people and len(self.prev_people) > 0:
+            score += speed_stats["body_speed"] * 1.1
+        if crowd_stats["close_people"] > 0.5:
+            score += 0.7
+        if crowd_stats["rapid_multi_person"] > 0.5:
+            score += 0.6
+        score = max(0.0, score - 0.45)
+        return float(min(score, 1.0))
+
+    def _score_falling(self, speed_stats, crowd_stats, pose_stats):
+        """Detect falling or being knocked down: rapid downward motion, ground contact."""
+        score = 0.0
+        if pose_stats["downward_motion"] > 0.4:
+            score += pose_stats["downward_motion"] * 1.5
+        if pose_stats["ground_contact"]:
+            score += 0.8
+        score += speed_stats["body_speed"] * 0.7
+        score = max(0.0, score - 0.35)
+        return float(min(score, 1.0))
+
+    def _score_defensive(self, speed_stats, crowd_stats, pose_stats):
+        """Detect defensive posture: arms raised, body protected."""
+        score = 0.0
+        if len(pose_stats["arm_angles"]) > 0:
+            avg_angle = np.mean(pose_stats["arm_angles"])
+            if avg_angle < 120:
+                score += 0.6
+        if abs(pose_stats["body_angle"]) > 30:
+            score += 0.4
+        score = max(0.0, score - 0.3)
+        return float(min(score, 1.0))
+
+    def _score_running(self, speed_stats, crowd_stats, pose_stats):
+        """Detect running: high leg speed, high body speed."""
+        score = max(0.0, speed_stats["body_speed"] * 1.2 + speed_stats["leg_speed"] * 0.8 - 0.35)
+        return float(min(score, 1.0))

src/detectors/violence_detector.py

@@ -0,0 +1,296 @@
+"""
+Violence Detection Module
+Loads and runs inference using the trained violence detection model
+"""
+
+import cv2
+import numpy as np
+import pickle
+from pathlib import Path
+from typing import Optional, List, Tuple, Dict, Any
+from dataclasses import dataclass
+
+# Model configuration
+MODEL_PATH = Path(__file__).parent / "model" / "violence_model.h5"
+LABEL_PATH = Path(__file__).parent / "model" / "lb.pickle"
+
+
+@dataclass
+class ViolenceDetection:
+    """Violence detection result."""
+    class_name: str = "Unknown"
+    confidence: float = 0.0
+    is_violence: bool = False
+    bbox: Optional[Tuple[int, int, int, int]] = None  # For ROI-based detection
+    
+    @property
+    def alert_level(self) -> str:
+        """Get alert level based on confidence."""
+        if not self.is_violence:
+            return "SAFE"
+        elif self.confidence >= 0.8:
+            return "HIGH RISK"
+        elif self.confidence >= 0.6:
+            return "MEDIUM RISK"
+        else:
+            return "LOW RISK"
+
+
+class ViolenceDetector:
+    """Violence detection using trained CNN model."""
+    
+    def __init__(self, 
+                 model_path: str = str(MODEL_PATH),
+                 label_path: str = str(LABEL_PATH),
+                 input_size: Tuple[int, int] = (224, 224)):
+        """
+        Initialize violence detector.
+        
+        Args:
+            model_path: Path to trained Keras model (.h5 file)
+            label_path: Path to label encoder pickle file
+            input_size: Expected input size for the model
+        """
+        try:
+            import tensorflow as tf
+            from tensorflow import keras
+        except ImportError:
+            raise ImportError(
+                "TensorFlow not installed. Run: pip install tensorflow"
+            )
+        
+        self.model_path = model_path
+        self.label_path = label_path
+        self.input_size = input_size
+        
+        # Load the trained model
+        try:
+            self.model = keras.models.load_model(model_path, compile=False)
+            print(f"Loaded violence detection model: {model_path}")
+        except Exception as e:
+            raise FileNotFoundError(f"Could not load model from {model_path}: {e}")
+        
+        # Load label encoder
+        try:
+            with open(label_path, 'rb') as f:
+                self.label_encoder = pickle.load(f)
+            print(f"Loaded label encoder: {label_path}")
+            print(f"Classes: {self.label_encoder.classes_}")
+        except Exception as e:
+            raise FileNotFoundError(f"Could not load label encoder from {label_path}: {e}")
+        
+        # Get model input shape
+        input_shape = self.model.input_shape
+        if len(input_shape) >= 3 and input_shape[1] is not None and input_shape[2] is not None:
+            self.input_size = (input_shape[1], input_shape[2])
+            print(f"Model input size: {self.input_size}")
+    
+    @property
+    def class_names(self) -> List[str]:
+        """Get list of class names."""
+        return list(self.label_encoder.classes_)
+    
+    def preprocess_frame(self, frame: np.ndarray) -> np.ndarray:
+        """
+        Preprocess frame for violence detection model.
+        
+        Args:
+            frame: BGR image (numpy array)
+            
+        Returns:
+            Preprocessed frame ready for inference
+        """
+        # Resize to model input size
+        resized = cv2.resize(frame, self.input_size, interpolation=cv2.INTER_AREA)
+        
+        # Convert BGR to RGB
+        rgb_frame = cv2.cvtColor(resized, cv2.COLOR_BGR2RGB)
+        
+        # Normalize to [0, 1]
+        normalized = rgb_frame.astype(np.float32) / 255.0
+        
+        # Add batch dimension
+        batch_frame = np.expand_dims(normalized, axis=0)
+        
+        return batch_frame
+    
+    def detect_violence(self, 
+                       frame: np.ndarray,
+                       confidence_threshold: float = 0.5) -> ViolenceDetection:
+        """
+        Detect violence in a single frame.
+        
+        Args:
+            frame: BGR image (numpy array)
+            confidence_threshold: Minimum confidence for violence detection
+            
+        Returns:
+            ViolenceDetection object with results
+        """
+        # Preprocess frame
+        preprocessed = self.preprocess_frame(frame)
+        
+        # Run inference
+        predictions = self.model.predict(preprocessed, verbose=0)[0]
+        
+        # Get predicted class and confidence
+        predicted_idx = np.argmax(predictions)
+        confidence = float(predictions[predicted_idx])
+        class_name = self.label_encoder.classes_[predicted_idx]
+        
+        # Determine if violence detected
+        is_violence = self._is_violent_class(class_name) and confidence >= confidence_threshold
+        
+        return ViolenceDetection(
+            class_name=class_name,
+            confidence=confidence,
+            is_violence=is_violence
+        )
+    
+    def detect_batch(self, 
+                    frames: List[np.ndarray],
+                    confidence_threshold: float = 0.5) -> List[ViolenceDetection]:
+        """
+        Detect violence in multiple frames (batch processing).
+        
+        Args:
+            frames: List of BGR images
+            confidence_threshold: Minimum confidence for violence detection
+            
+        Returns:
+            List of ViolenceDetection objects
+        """
+        if not frames:
+            return []
+        
+        # Preprocess all frames
+        batch = np.vstack([self.preprocess_frame(frame) for frame in frames])
+        
+        # Run batch inference
+        predictions = self.model.predict(batch, verbose=0)
+        
+        results = []
+        for i, pred in enumerate(predictions):
+            predicted_idx = np.argmax(pred)
+            confidence = float(pred[predicted_idx])
+            class_name = self.label_encoder.classes_[predicted_idx]
+            
+            is_violence = self._is_violent_class(class_name) and confidence >= confidence_threshold
+            
+            results.append(ViolenceDetection(
+                class_name=class_name,
+                confidence=confidence,
+                is_violence=is_violence
+            ))
+        
+        return results
+    
+    def _is_violent_class(self, class_name: str) -> bool:
+        """
+        Determine if a class name indicates violence.
+        
+        Args:
+            class_name: Name of the predicted class
+            
+        Returns:
+            True if class indicates violence
+        """
+        # Common violence class names (adjust based on your model's classes)
+        violence_keywords = [
+            'violence', 'violent', 'fight', 'fighting', 'assault', 'attack',
+            'aggression', 'aggressive', 'hitting', 'punch', 'kick', 'weapon',
+            'gun', 'knife', 'sword', 'bat', 'stick'
+        ]
+        
+        class_lower = class_name.lower()
+        return any(keyword in class_lower for keyword in violence_keywords)
+    
+    def draw_violence_detection(self, 
+                               frame: np.ndarray, 
+                               detection: ViolenceDetection,
+                               roi_bbox: Optional[Tuple[int, int, int, int]] = None) -> np.ndarray:
+        """
+        Draw violence detection results on frame.
+        
+        Args:
+            frame: Original BGR frame
+            detection: ViolenceDetection object
+            roi_bbox: ROI bounding box (x, y, w, h) if detection was on ROI
+            
+        Returns:
+            Frame with detection visualization
+        """
+        display_frame = frame.copy()
+        
+        # Choose colors based on alert level
+        if detection.is_violence:
+            if detection.confidence >= 0.8:
+                color = (0, 0, 255)  # Red - High risk
+            elif detection.confidence >= 0.6:
+                color = (0, 165, 255)  # Orange - Medium risk
+            else:
+                color = (0, 255, 255)  # Yellow - Low risk
+        else:
+            color = (0, 255, 0)  # Green - Safe
+        
+        # Draw ROI box if provided
+        if roi_bbox is not None:
+            x, y, w, h = roi_bbox
+            cv2.rectangle(display_frame, (x, y), (x + w, y + h), color, 3)
+        
+        # Draw alert banner
+        alert_text = f"{detection.alert_level}: {detection.class_name}"
+        confidence_text = f"Confidence: {detection.confidence:.2f}"
+        
+        # Background rectangle for text
+        text_size = cv2.getTextSize(alert_text, cv2.FONT_HERSHEY_SIMPLEX, 1.2, 3)[0]
+        cv2.rectangle(display_frame, (10, 10), 
+                     (text_size[0] + 20, 80), color, -1)
+        
+        # White text on colored background
+        cv2.putText(display_frame, alert_text, (15, 40),
+                   cv2.FONT_HERSHEY_SIMPLEX, 1.2, (255, 255, 255), 3)
+        cv2.putText(display_frame, confidence_text, (15, 70),
+                   cv2.FONT_HERSHEY_SIMPLEX, 0.8, (255, 255, 255), 2)
+        
+        return display_frame
+
+
+def main():
+    """Demo: Test violence detection on webcam feed."""
+    
+    detector = ViolenceDetector()
+    cap = cv2.VideoCapture(0)
+    
+    print("Press 'q' to quit")
+    print("Violence detection active")
+    print(f"Classes: {detector.class_names}")
+    
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+        
+        # Detect violence
+        detection = detector.detect_violence(frame, confidence_threshold=0.5)
+        
+        # Draw results
+        display_frame = detector.draw_violence_detection(frame, detection)
+        
+        # Show frame
+        cv2.imshow("Violence Detection", display_frame)
+        
+        # Print alerts to console
+        if detection.is_violence:
+            print(f"ALERT: {detection.alert_level} - {detection.class_name} "
+                  f"(Confidence: {detection.confidence:.2f})")
+        
+        if cv2.waitKey(1) & 0xFF == ord('q'):
+            break
+    
+    cap.release()
+    cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    main()

src/detectors/weapon_detector.py

@@ -0,0 +1,377 @@
+"""
+Weapon & Person Detection System
+Detects weapons in frame and counts persons visible while weapon is present.
+Alert stays active until the person with the weapon leaves the frame.
+
+Uses two YOLO models:
+- best.pt (ai_models/wepan_detection) or GunDetector.pt fallback — custom weapon model
+- yolov8n.pt      — COCO model for person detection (class 0: person)
+"""
+
+import cv2
+import numpy as np
+import time
+from pathlib import Path
+from typing import List, Tuple, Optional, Dict
+from dataclasses import dataclass, field
+
+try:
+    from ..pipeline import VideoCapture
+    from .yolo_detector import YOLODetector, Detection
+except ImportError:
+    # Fallback for direct execution
+    import sys
+    sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+    from src.pipeline import VideoCapture
+    from src.detectors.yolo_detector import YOLODetector, Detection
+
+# ---------------------------------------------------------------------------
+# Model paths
+# ---------------------------------------------------------------------------
+_BASE = Path(__file__).parent
+_PROJECT_ROOT = _BASE.parent
+
+# Prefer the shared trained model under ai_models, then fall back to legacy path.
+_WEAPON_MODEL_CANDIDATES = [
+    _PROJECT_ROOT / "ai_models" / "wepan_detection" / "best.pt",
+    _PROJECT_ROOT / "ai_models" / "weapon_detection" / "best.pt",
+    _BASE / "model" / "GunDetector.pt",
+]
+
+def _resolve_weapon_model_path() -> str:
+    for candidate in _WEAPON_MODEL_CANDIDATES:
+        if candidate.exists():
+            return str(candidate)
+    # Keep first candidate as default so callers get a clear file-not-found path if missing.
+    return str(_WEAPON_MODEL_CANDIDATES[0])
+
+GUN_MODEL_PATH = _resolve_weapon_model_path()
+
+_PERSON_MODEL_CANDIDATES = [
+    _PROJECT_ROOT / "ai_models" / "object_detection" / "yolov8n.pt",
+    _BASE / "model" / "yolov8s.pt",
+    _BASE / "model" / "yolov8n.pt",
+]
+
+def _resolve_person_model_path() -> str:
+    for candidate in _PERSON_MODEL_CANDIDATES:
+        if candidate.exists():
+            return str(candidate)
+    return str(_PERSON_MODEL_CANDIDATES[0])
+
+PERSON_MODEL_PATH = _resolve_person_model_path()
+
+# COCO class IDs from yolov8n
+PERSON_CLASS_ID = 0
+KNIFE_CLASS_ID = 43  # "knife" in COCO
+
+# How many consecutive "no-weapon" frames before we clear the alert.
+WEAPON_COOLDOWN_FRAMES = 10
+
+# How many consecutive frames a weapon must appear before alert triggers.
+# This prevents random one-off false positives from firing an alert.
+WEAPON_CONFIRM_FRAMES = 3
+
+# Minimum bounding-box area (pixels) to accept a gun detection.
+# Tiny boxes are almost always false positives.
+MIN_WEAPON_AREA = 1500
+
+# Gun model needs a higher confidence bar because it produces false positives.
+GUN_CONF_THRESHOLD = 0.60
+
+# Person / knife confidence can stay lower (COCO model is reliable).
+PERSON_CONF_THRESHOLD = 0.30
+
+
+@dataclass
+class FrameResult:
+    """Result of analysing a single frame."""
+    weapons: List[Detection] = field(default_factory=list)
+    persons: List[Detection] = field(default_factory=list)
+    alert_active: bool = False
+    person_count: int = 0
+
+
+class WeaponPersonDetector:
+    """Real-time weapon detection with person counting using dual YOLO models."""
+
+    def __init__(self,
+                 gun_model_path: str = GUN_MODEL_PATH,
+                 person_model_path: str = PERSON_MODEL_PATH,
+                 gun_conf: float = GUN_CONF_THRESHOLD,
+                 person_conf: float = PERSON_CONF_THRESHOLD,
+                 cooldown_frames: int = WEAPON_COOLDOWN_FRAMES,
+                 confirm_frames: int = WEAPON_CONFIRM_FRAMES,
+                 min_weapon_area: int = MIN_WEAPON_AREA):
+        """
+        Args:
+            gun_model_path: Path to weapon model weights (.pt).
+            person_model_path: Path to yolov8n.pt weights (for person detection).
+            gun_conf: Confidence threshold for gun detections (higher = fewer false positives).
+            person_conf: Confidence threshold for person/knife detections.
+            cooldown_frames: Frames without weapon before alert clears.
+            confirm_frames: Consecutive weapon frames needed to trigger alert.
+            min_weapon_area: Minimum bbox area (px) to accept a gun detection.
+        """
+        print(f"Loading weapon model ({gun_model_path})...")
+        self.gun_detector = YOLODetector(gun_model_path)
+        print("Loading person model (yolov8n.pt)...")
+        self.person_detector = YOLODetector(person_model_path)
+
+        self.gun_conf = gun_conf
+        self.person_conf = person_conf
+        self.cooldown_frames = cooldown_frames
+        self.confirm_frames = confirm_frames
+        self.min_weapon_area = min_weapon_area
+
+        # State
+        self._alert_active = False
+        self._frames_since_last_weapon = 0
+        self._consecutive_weapon_frames = 0
+        self._alert_start_time: Optional[float] = None
+
+        # Build human-readable names
+        self.weapon_names = dict(self.gun_detector.class_names)
+        self.weapon_names[f"yolo_{KNIFE_CLASS_ID}"] = "knife"
+        self.person_names = {PERSON_CLASS_ID: self.person_detector.class_names.get(PERSON_CLASS_ID, "person")}
+
+        print(f"\nWeapon-Person Detector initialised")
+        print(f"  Gun model      : {gun_model_path}")
+        print(f"  Gun confidence : {self.gun_conf}  (high to reduce false positives)")
+        print(f"  Person conf    : {self.person_conf}")
+        print(f"  Min weapon area: {self.min_weapon_area} px")
+        print(f"  Confirm frames : {self.confirm_frames}  (weapon must appear this many frames in a row)")
+        print(f"  Cooldown       : {self.cooldown_frames} frames")
+        print(f"  Weapon classes : {self.weapon_names}")
+
+    # ------------------------------------------------------------------
+    # Core detection
+    # ------------------------------------------------------------------
+
+    def process_frame(self, frame: np.ndarray) -> FrameResult:
+        """Run both models on a single BGR frame and update alert state."""
+        # --- Gun detector (high confidence + size filter) ---
+        raw_guns = self.gun_detector.detect(
+            frame,
+            conf_threshold=self.gun_conf,
+        )
+        # Filter out small bounding boxes (false positives)
+        weapons = [d for d in raw_guns if d.area >= self.min_weapon_area]
+
+        # --- COCO model for person + knife ---
+        coco_detections = self.person_detector.detect(
+            frame,
+            conf_threshold=self.person_conf,
+            classes=[PERSON_CLASS_ID, KNIFE_CLASS_ID],
+        )
+        persons = [d for d in coco_detections if d.class_id == PERSON_CLASS_ID]
+        knives = [d for d in coco_detections if d.class_id == KNIFE_CLASS_ID]
+        weapons.extend(knives)
+
+        # --- Multi-frame confirmation before triggering alert ---
+        if weapons:
+            self._consecutive_weapon_frames += 1
+            self._frames_since_last_weapon = 0
+        else:
+            self._consecutive_weapon_frames = 0
+            self._frames_since_last_weapon += 1
+
+        # Only activate alert after weapon seen N frames in a row
+        if self._consecutive_weapon_frames >= self.confirm_frames:
+            if not self._alert_active:
+                self._alert_active = True
+                self._alert_start_time = time.time()
+
+        # Clear alert after cooldown with no weapons
+        if self._frames_since_last_weapon >= self.cooldown_frames:
+            self._alert_active = False
+            self._alert_start_time = None
+
+        return FrameResult(
+            weapons=weapons,
+            persons=persons,
+            alert_active=self._alert_active,
+            person_count=len(persons),
+        )
+
+    # ------------------------------------------------------------------
+    # Drawing / overlay helpers
+    # ------------------------------------------------------------------
+
+    def draw_results(self, frame: np.ndarray, result: FrameResult) -> np.ndarray:
+        """Draw bounding boxes and compact HUD overlay on the frame."""
+        out = frame.copy()
+        h, w = out.shape[:2]
+
+        # --- Draw person boxes (thin green) ---
+        for i, det in enumerate(result.persons, 1):
+            x1, y1, x2, y2 = det.bbox
+            cv2.rectangle(out, (x1, y1), (x2, y2), (0, 200, 0), 1)
+            self._draw_label(out, f"P{i}", (x1, y1), bg_color=(0, 200, 0),
+                             scale=0.35, thickness=1)
+
+        # --- Draw weapon boxes (thin red) ---
+        for det in result.weapons:
+            x1, y1, x2, y2 = det.bbox
+            cv2.rectangle(out, (x1, y1), (x2, y2), (0, 0, 255), 2)
+            self._draw_label(out, f"{det.class_name} {det.confidence:.0%}",
+                             (x1, y1), bg_color=(0, 0, 255),
+                             scale=0.35, thickness=1)
+
+        # --- Compact top-right info box ---
+        if result.alert_active:
+            elapsed = time.time() - (self._alert_start_time or time.time())
+            weapon_names = ", ".join(d.class_name for d in result.weapons) or "last seen"
+            lines = [
+                f"WEAPON: {weapon_names}",
+                f"Persons: {result.person_count}  Time: {elapsed:.0f}s",
+            ]
+            box_color = (0, 0, 180)
+        else:
+            lines = [
+                "No Weapon",
+                f"Persons: {result.person_count}",
+            ]
+            box_color = (0, 130, 0)
+
+        # Draw compact semi-transparent box in top-right corner
+        line_h = 16
+        pad = 4
+        box_h = len(lines) * line_h + pad * 2
+        max_tw = max(cv2.getTextSize(l, cv2.FONT_HERSHEY_SIMPLEX, 0.38, 1)[0][0] for l in lines)
+        box_w = max_tw + pad * 2
+        x0 = w - box_w - 5
+        y0 = 5
+
+        overlay = out.copy()
+        cv2.rectangle(overlay, (x0, y0), (x0 + box_w, y0 + box_h), box_color, -1)
+        cv2.addWeighted(overlay, 0.55, out, 0.45, 0, out)
+
+        for i, line in enumerate(lines):
+            cv2.putText(out, line, (x0 + pad, y0 + pad + (i + 1) * line_h - 2),
+                        cv2.FONT_HERSHEY_SIMPLEX, 0.38, (255, 255, 255), 1)
+
+        return out
+
+    @staticmethod
+    def _draw_label(frame, text, origin, bg_color=(0, 0, 0),
+                    font=cv2.FONT_HERSHEY_SIMPLEX, scale=0.55, thickness=1):
+        """Draw a text label with filled background."""
+        x, y = origin
+        (tw, th), baseline = cv2.getTextSize(text, font, scale, thickness)
+        cv2.rectangle(frame, (x, y - th - 8), (x + tw + 4, y), bg_color, -1)
+        cv2.putText(frame, text, (x + 2, y - 4), font, scale, (255, 255, 255), thickness)
+
+    # ------------------------------------------------------------------
+    # High-level run loop
+    # ------------------------------------------------------------------
+
+    def run(self, source=0, show_window: bool = True):
+        """
+        Start the live detection loop.
+
+        Args:
+            source: Camera index (0, 1, …) or RTSP URL string.
+            show_window: Whether to display the OpenCV window.
+
+        Controls:
+            q      – quit
+            s      – save screenshot
+            +/-    – increase / decrease confidence threshold
+        """
+        capture = VideoCapture(source, use_motion_detection=False)
+        if not capture.start(verbose=True):
+            print("ERROR: Could not open video source.")
+            return
+
+        print("\n--- Weapon + Person Detection Running ---")
+        print("Controls:  q = quit  |  s = screenshot  |  +/- = gun confidence")
+        print(f"Watching for: {list(self.weapon_names.values())}")
+        print(f"Gun conf: {self.gun_conf}  |  Min area: {self.min_weapon_area}px  |  Confirm: {self.confirm_frames} frames")
+        print()
+
+        fps_timer = time.time()
+        frame_count = 0
+
+        try:
+            for original, _preprocessed in capture.stream_frames():
+                result = self.process_frame(original)
+
+                # Log alerts to console
+                if result.weapons:
+                    names = ", ".join(f"{d.class_name}({d.confidence:.0%})" for d in result.weapons)
+                    print(f"[ALERT] Weapons: {names}  |  Persons in frame: {result.person_count}")
+
+                if show_window:
+                    display = self.draw_results(original, result)
+
+                    # FPS counter
+                    frame_count += 1
+                    if frame_count % 15 == 0:
+                        now = time.time()
+                        fps = 15 / max(now - fps_timer, 1e-9)
+                        fps_timer = now
+                        cv2.setWindowTitle("Weapon Detection", f"Weapon Detection  [{fps:.1f} FPS]")
+
+                    cv2.imshow("Weapon Detection", display)
+                    key = cv2.waitKey(1) & 0xFF
+                    if key == ord("q"):
+                        break
+                    elif key == ord("s"):
+                        fname = f"weapon_screenshot_{int(time.time())}.jpg"
+                        cv2.imwrite(fname, display)
+                        print(f"Screenshot saved: {fname}")
+                    elif key == ord("+") or key == ord("="):
+                        self.gun_conf = min(0.95, self.gun_conf + 0.05)
+                        print(f"Gun confidence threshold -> {self.gun_conf:.2f}")
+                    elif key == ord("-"):
+                        self.gun_conf = max(0.10, self.gun_conf - 0.05)
+                        print(f"Gun confidence threshold -> {self.gun_conf:.2f}")
+        finally:
+            capture.stop()
+            cv2.destroyAllWindows()
+            print("Detection stopped.")
+
+
+# -----------------------------------------------------------------------
+# CLI entry point
+# -----------------------------------------------------------------------
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Weapon & Person Detection System")
+    parser.add_argument("--source", default="0",
+                        help="Camera index (0,1,..) or RTSP URL (default: 0)")
+    parser.add_argument("--gun-conf", type=float, default=GUN_CONF_THRESHOLD,
+                        help=f"Gun model confidence threshold (default: {GUN_CONF_THRESHOLD})")
+    parser.add_argument("--person-conf", type=float, default=PERSON_CONF_THRESHOLD,
+                        help=f"Person/knife confidence threshold (default: {PERSON_CONF_THRESHOLD})")
+    parser.add_argument("--cooldown", type=int, default=WEAPON_COOLDOWN_FRAMES,
+                        help=f"Frames before alert clears (default: {WEAPON_COOLDOWN_FRAMES})")
+    parser.add_argument("--confirm", type=int, default=WEAPON_CONFIRM_FRAMES,
+                        help=f"Consecutive frames to confirm weapon (default: {WEAPON_CONFIRM_FRAMES})")
+    parser.add_argument("--min-area", type=int, default=MIN_WEAPON_AREA,
+                        help=f"Min weapon bbox area in pixels (default: {MIN_WEAPON_AREA})")
+    parser.add_argument("--gun-model", default=GUN_MODEL_PATH,
+                        help="Path to gun detection model weights")
+    parser.add_argument("--person-model", default=PERSON_MODEL_PATH,
+                        help="Path to person detection model weights")
+    args = parser.parse_args()
+
+    source = int(args.source) if args.source.strip().isdigit() else args.source
+
+    wpd = WeaponPersonDetector(
+        gun_model_path=args.gun_model,
+        person_model_path=args.person_model,
+        gun_conf=args.gun_conf,
+        person_conf=args.person_conf,
+        cooldown_frames=args.cooldown,
+        confirm_frames=args.confirm,
+        min_weapon_area=args.min_area,
+    )
+    wpd.run(source=source)
+
+
+if __name__ == "__main__":
+    main()

src/detectors/yolo_detector.py

@@ -0,0 +1,86 @@
+"""
+YOLO Object Detection Module
+Lightweight wrapper around Ultralytics YOLO results for consistent app usage.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+from ultralytics import YOLO
+
+
+@dataclass
+class Detection:
+    """Normalized detection record used across the NETRA app."""
+
+    class_id: int
+    class_name: str
+    confidence: float
+    bbox: Tuple[int, int, int, int]  # (x1, y1, x2, y2)
+
+    @property
+    def area(self) -> int:
+        x1, y1, x2, y2 = self.bbox
+        return max(0, x2 - x1) * max(0, y2 - y1)
+
+
+class YOLODetector:
+    """Simple inference wrapper over an Ultralytics YOLO model."""
+
+    def __init__(self, model_path: Optional[str] = None):
+        resolved_path = self._resolve_model_path(model_path)
+        self.model = YOLO(resolved_path)
+        self.model_path = resolved_path
+        self.class_names: Dict[int, str] = dict(getattr(self.model, "names", {}) or {})
+
+    @staticmethod
+    def _resolve_model_path(model_path: Optional[str]) -> str:
+        if model_path:
+            return model_path
+
+        root = Path(__file__).resolve().parent.parent
+        candidates = [
+            root / "ai_models" / "object_detection" / "yolov8n.pt",
+            Path(__file__).resolve().parent / "model" / "yolov8n.pt",
+            Path(__file__).resolve().parent / "model" / "yolov8s.pt",
+        ]
+        for candidate in candidates:
+            if candidate.exists():
+                return str(candidate)
+
+        return str(candidates[0])
+
+    def detect(
+        self,
+        frame: np.ndarray,
+        conf_threshold: float = 0.25,
+        classes: Optional[Sequence[int]] = None,
+    ) -> List[Detection]:
+        """Run inference on a single BGR frame and return normalized detections."""
+        results = self.model.predict(frame, conf=conf_threshold, classes=classes, verbose=False)
+        if not results:
+            return []
+
+        boxes = results[0].boxes
+        if boxes is None:
+            return []
+
+        detections: List[Detection] = []
+        for box in boxes:
+            cls_id = int(box.cls.item()) if box.cls is not None else -1
+            conf = float(box.conf.item()) if box.conf is not None else 0.0
+            xyxy = box.xyxy[0].tolist()
+            x1, y1, x2, y2 = [int(v) for v in xyxy]
+            class_name = self.class_names.get(cls_id, str(cls_id))
+            detections.append(
+                Detection(
+                    class_id=cls_id,
+                    class_name=class_name,
+                    confidence=conf,
+                    bbox=(x1, y1, x2, y2),
+                )
+            )
+
+        return detections

src/pipeline/__init__.py

@@ -0,0 +1,8 @@
+"""
+Video Processing Pipeline
+Frame capture and preprocessing modules
+"""
+
+from .video_capture import VideoCapture
+
+__all__ = ['VideoCapture']

src/pipeline/video_capture.py

@@ -0,0 +1,446 @@
+
+"""
+Video Capture Module for AI Processing
+Captures frames from webcam or RTSP stream and preprocesses them for YOLOv8
+Uses motion detection (MOG2) to extract ROIs for faster inference
+"""
+
+import cv2
+import numpy as np
+import platform
+from typing import Optional, Tuple, Generator, List
+from dataclasses import dataclass
+
+
+@dataclass
+class ROI:
+    """Region of Interest containing motion."""
+    x: int
+    y: int
+    width: int
+    height: int
+    cropped_frame: np.ndarray  # Original cropped region
+    preprocessed: np.ndarray   # Resized to 640x640 for YOLO
+
+
+class MotionDetector:
+    """Detects motion using MOG2 background subtraction."""
+    
+    def __init__(self,  
+                 history: int = 500,
+                 var_threshold: float = 16,
+                 detect_shadows: bool = True,
+                 min_contour_area: int = 500,
+                 merge_distance: int = 50):
+        """
+        Initialize MOG2 background subtractor.
+        
+        Args:
+            history: Number of frames for background model
+            var_threshold: Variance threshold for background/foreground segmentation
+            detect_shadows: Whether to detect shadows (marks them gray vs white)
+            min_contour_area: Minimum area (pixels) to consider as valid motion
+            merge_distance: Distance to merge nearby contours into single ROI
+        """
+        self.bg_subtractor = cv2.createBackgroundSubtractorMOG2(
+            history=history,
+            varThreshold=var_threshold,
+            detectShadows=detect_shadows
+        )
+        self.min_contour_area = min_contour_area
+        self.merge_distance = merge_distance
+        self.kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+    
+    def get_foreground_mask(self, frame: np.ndarray) -> np.ndarray:
+        """
+        Get binary mask of moving objects.
+        
+        Args:
+            frame: Input BGR frame
+            
+        Returns:
+            Binary mask where white = motion
+        """
+        # Apply background subtraction
+        fg_mask = self.bg_subtractor.apply(frame)
+        
+        # Remove shadows (gray pixels become black)
+        _, fg_mask = cv2.threshold(fg_mask, 250, 255, cv2.THRESH_BINARY)
+        
+        # Morphological operations to clean up noise
+        fg_mask = cv2.morphologyEx(fg_mask, cv2.MORPH_OPEN, self.kernel)
+        fg_mask = cv2.morphologyEx(fg_mask, cv2.MORPH_CLOSE, self.kernel)
+        fg_mask = cv2.dilate(fg_mask, self.kernel, iterations=2)
+        
+        return fg_mask
+    
+    def _merge_bounding_boxes(self, boxes: List[Tuple[int, int, int, int]]) -> List[Tuple[int, int, int, int]]:
+        """Merge nearby bounding boxes to reduce fragmentation."""
+        if not boxes:
+            return []
+        
+        merged = []
+        used = [False] * len(boxes)
+        
+        for i, (x1, y1, w1, h1) in enumerate(boxes):
+            if used[i]:
+                continue
+            
+            # Start with current box
+            min_x, min_y = x1, y1
+            max_x, max_y = x1 + w1, y1 + h1
+            used[i] = True
+            
+            # Find and merge nearby boxes
+            changed = True
+            while changed:
+                changed = False
+                for j, (x2, y2, w2, h2) in enumerate(boxes):
+                    if used[j]:
+                        continue
+                    
+                    # Check if boxes are close enough to merge
+                    if (x2 < max_x + self.merge_distance and 
+                        x2 + w2 > min_x - self.merge_distance and
+                        y2 < max_y + self.merge_distance and 
+                        y2 + h2 > min_y - self.merge_distance):
+                        
+                        min_x = min(min_x, x2)
+                        min_y = min(min_y, y2)
+                        max_x = max(max_x, x2 + w2)
+                        max_y = max(max_y, y2 + h2)
+                        used[j] = True
+                        changed = True
+            
+            merged.append((min_x, min_y, max_x - min_x, max_y - min_y))
+        
+        return merged
+    
+    def detect_motion_regions(self, frame: np.ndarray, 
+                              padding: int = 20) -> List[Tuple[int, int, int, int]]:
+        """
+        Detect regions with motion.
+        
+        Args:
+            frame: Input BGR frame
+            padding: Pixels to add around detected regions
+            
+        Returns:
+            List of bounding boxes (x, y, width, height)
+        """
+        fg_mask = self.get_foreground_mask(frame)
+        
+        # Find contours of moving objects
+        contours, _ = cv2.findContours(fg_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        
+        boxes = []
+        h, w = frame.shape[:2]
+        
+        for contour in contours:
+            area = cv2.contourArea(contour)
+            if area < self.min_contour_area:
+                continue
+            
+            x, y, bw, bh = cv2.boundingRect(contour)
+            
+            # Add padding and clamp to frame bounds
+            x = max(0, x - padding)
+            y = max(0, y - padding)
+            bw = min(w - x, bw + 2 * padding)
+            bh = min(h - y, bh + 2 * padding)
+            
+            boxes.append((x, y, bw, bh))
+        
+        # Merge nearby boxes
+        return self._merge_bounding_boxes(boxes)
+
+
+class VideoCapture:
+    """Captures and preprocesses video frames for AI inference."""
+    
+    # YOLOv8 native input size
+    TARGET_SIZE = (640, 640)
+    
+    def __init__(self, source: int | str = 0, use_motion_detection: bool = True):
+        """
+        Initialize video capture.
+        
+        Args:
+            source: Camera index (0 for default webcam) or RTSP URL string
+                    Example RTSP: "rtsp://username:password@ip_address:port/stream"
+            use_motion_detection: Enable MOG2 motion detection for ROI extraction
+        """
+        self.source = self._normalize_source(source)
+        self.cap: Optional[cv2.VideoCapture] = None
+        self.use_motion_detection = use_motion_detection
+        self.motion_detector: Optional[MotionDetector] = None
+        self.active_source: Optional[int | str] = None
+        self.active_backend: Optional[int] = None
+
+    @staticmethod
+    def _normalize_source(source: int | str) -> int | str:
+        """Normalize source values so numeric strings map to camera indices."""
+        if isinstance(source, str) and source.strip().isdigit():
+            return int(source.strip())
+        return source
+
+    @staticmethod
+    def _backend_name(backend: int) -> str:
+        """Get a readable backend name for diagnostics."""
+        names = {
+            cv2.CAP_ANY: "CAP_ANY",
+            cv2.CAP_DSHOW: "CAP_DSHOW",
+            cv2.CAP_MSMF: "CAP_MSMF",
+        }
+        return names.get(backend, str(backend))
+
+    def _source_candidates(self) -> List[int | str]:
+        """Return source candidates to try opening in order."""
+        if isinstance(self.source, int):
+            candidates = [self.source]
+            if self.source == 0:
+                candidates.extend([1, 2])
+            return candidates
+        return [self.source]
+
+    def _backend_candidates(self) -> List[int]:
+        """Return backend candidates based on platform and source type."""
+        if isinstance(self.source, str):
+            return [cv2.CAP_ANY]
+
+        if platform.system().lower().startswith("win"):
+            return [cv2.CAP_DSHOW, cv2.CAP_MSMF, cv2.CAP_ANY]
+
+        return [cv2.CAP_ANY]
+        
+    def start(self, verbose: bool = True) -> bool:
+        """
+        Start the video capture.
+        
+        Returns:
+            True if capture started successfully, False otherwise
+        """
+        self.stop()
+
+        open_attempts = []
+        for source_candidate in self._source_candidates():
+            for backend in self._backend_candidates():
+                cap = cv2.VideoCapture(source_candidate, backend)
+                open_attempts.append(f"{source_candidate} via {self._backend_name(backend)}")
+
+                if cap.isOpened():
+                    self.cap = cap
+                    self.active_source = source_candidate
+                    self.active_backend = backend
+                    break
+
+                cap.release()
+
+            if self.cap is not None:
+                break
+
+        if self.cap is None:
+            if verbose:
+                print(f"Error: Could not open video source: {self.source}")
+                print("Tried:")
+                for attempt in open_attempts:
+                    print(f"  - {attempt}")
+            return False
+        
+        # Set buffer size to minimize latency (useful for RTSP streams)
+        self.cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)
+        
+        # Initialize motion detector if enabled
+        if self.use_motion_detection:
+            self.motion_detector = MotionDetector()
+            if verbose:
+                print("Motion detection enabled (MOG2)")
+        
+        # Print capture info
+        width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        fps = self.cap.get(cv2.CAP_PROP_FPS)
+        if verbose:
+            backend_name = self._backend_name(self.active_backend) if self.active_backend is not None else "Unknown"
+            print(f"Video capture started: source={self.active_source}, backend={backend_name}")
+            print(f"Resolution: {width}x{height} @ {fps:.1f} FPS")
+        
+        return True
+    
+    def stop(self):
+        """Release the video capture resources."""
+        if self.cap is not None:
+            self.cap.release()
+            self.cap = None
+            self.active_source = None
+            self.active_backend = None
+            print("Video capture stopped")
+    
+    def preprocess_frame(self, frame: np.ndarray) -> np.ndarray:
+        """
+        Preprocess frame for YOLOv8 inference.
+        
+        Args:
+            frame: Raw BGR frame from camera
+            
+        Returns:
+            Preprocessed frame resized to 640x640
+        """
+        # Resize to YOLOv8 native size (640x640)
+        resized = cv2.resize(frame, self.TARGET_SIZE, interpolation=cv2.INTER_LINEAR)
+        return resized
+    
+    def read_frame(self) -> Tuple[bool, Optional[np.ndarray], Optional[np.ndarray]]:
+        """
+        Read and preprocess a single frame.
+        
+        Returns:
+            Tuple of (success, original_frame, preprocessed_frame)
+        """
+        if self.cap is None:
+            return False, None, None
+        
+        ret, frame = self.cap.read()
+        
+        if not ret or frame is None:
+            return False, None, None
+        
+        preprocessed = self.preprocess_frame(frame)
+        return True, frame, preprocessed
+    
+    def extract_rois(self, frame: np.ndarray) -> List[ROI]:
+        """
+        Extract regions of interest (moving objects) from frame.
+        
+        Args:
+            frame: Input BGR frame
+            
+        Returns:
+            List of ROI objects containing cropped and preprocessed regions
+        """
+        if self.motion_detector is None:
+            # If no motion detection, return whole frame as single ROI
+            preprocessed = self.preprocess_frame(frame)
+            return [ROI(0, 0, frame.shape[1], frame.shape[0], frame, preprocessed)]
+        
+        boxes = self.motion_detector.detect_motion_regions(frame)
+        
+        if not boxes:
+            return []
+        
+        rois = []
+        for x, y, w, h in boxes:
+            cropped = frame[y:y+h, x:x+w]
+            preprocessed = cv2.resize(cropped, self.TARGET_SIZE, interpolation=cv2.INTER_LINEAR)
+            rois.append(ROI(x, y, w, h, cropped, preprocessed))
+        
+        return rois
+    
+    def read_frame_with_rois(self) -> Tuple[bool, Optional[np.ndarray], List[ROI], Optional[np.ndarray]]:
+        """
+        Read frame and extract ROIs for motion regions.
+        
+        Returns:
+            Tuple of (success, original_frame, list_of_rois, foreground_mask)
+        """
+        if self.cap is None:
+            return False, None, [], None
+        
+        ret, frame = self.cap.read()
+        
+        if not ret or frame is None:
+            return False, None, [], None
+        
+        rois = self.extract_rois(frame)
+        
+        # Get foreground mask for visualization
+        fg_mask = None
+        if self.motion_detector is not None:
+            fg_mask = self.motion_detector.get_foreground_mask(frame)
+        
+        return True, frame, rois, fg_mask
+    
+    def stream_frames(self) -> Generator[Tuple[np.ndarray, np.ndarray], None, None]:
+        """
+        Generator that continuously yields frames (no motion detection).
+        
+        Yields:
+            Tuple of (original_frame, preprocessed_frame)
+        """
+        while True:
+            success, original, preprocessed = self.read_frame()
+            if not success:
+                break
+            yield original, preprocessed
+    
+    def stream_rois(self) -> Generator[Tuple[np.ndarray, List[ROI], Optional[np.ndarray]], None, None]:
+        """
+        Generator that yields frames with motion-detected ROIs.
+        
+        Yields:
+            Tuple of (original_frame, list_of_rois, foreground_mask)
+        """
+        while True:
+            success, original, rois, fg_mask = self.read_frame_with_rois()
+            if not success:
+                break
+            yield original, rois, fg_mask
+    
+    def __enter__(self):
+        """Context manager entry."""
+        if not self.start():
+            raise RuntimeError(f"Could not open video source: {self.source}")
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.stop()
+
+
+def main():
+    """Demo: Capture frames with motion detection from webcam."""
+    
+    # Use 0 for default webcam, or provide RTSP URL for IP camera
+    # Example RTSP: "rtsp://admin:password@192.168.1.100:554/stream1"
+    source = 0
+    
+    with VideoCapture(source, use_motion_detection=True) as capture:
+        print("Press 'q' to quit")
+        print("Motion detection active - only moving regions will be processed")
+        
+        for original, rois, fg_mask in capture.stream_rois():
+            # Draw bounding boxes around motion regions
+            display_frame = original.copy()
+            
+            for i, roi in enumerate(rois):
+                # Draw green rectangle around ROI
+                cv2.rectangle(display_frame, 
+                             (roi.x, roi.y), 
+                             (roi.x + roi.width, roi.y + roi.height),
+                             (0, 255, 0), 2)
+                
+                # Label with ROI index and size
+                label = f"ROI {i+1}: {roi.width}x{roi.height}"
+                cv2.putText(display_frame, label, (roi.x, roi.y - 10),
+                           cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1)
+            
+            # Show info
+            info = f"Motion ROIs: {len(rois)} | Press 'q' to quit"
+            cv2.putText(display_frame, info, (10, 30),
+                       cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 255), 2)
+            
+            cv2.imshow("Video Capture - Motion Detection", display_frame)
+            
+            # Show foreground mask
+            if fg_mask is not None:
+                cv2.imshow("Foreground Mask", fg_mask)
+            
+            if cv2.waitKey(1) & 0xFF == ord('q'):
+                break
+    
+    cv2.destroyAllWindows()
+    print("Done!")
+
+
+if __name__ == "__main__":
+    main()

src/utils/__init__.py

@@ -0,0 +1,34 @@
+"""
+Utility Functions
+Common helper functions and utilities
+"""
+
+import logging
+from pathlib import Path
+
+# Setup logging
+logger = logging.getLogger(__name__)
+
+
+def ensure_dir(directory: Path) -> Path:
+    """
+    Ensure directory exists, create if needed
+    
+    Args:
+        directory: Path to directory
+    
+    Returns:
+        Path object
+    """
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def get_project_root() -> Path:
+    """
+    Get root directory of NETRA project
+    
+    Returns:
+        Path to project root
+    """
+    return Path(__file__).parent.parent.parent

src/utils/model_downloader.py

@@ -0,0 +1,147 @@
+"""
+Model Downloader - Downloads AI models from Hugging Face Hub
+Automatically caches models locally after first download
+FULLY PORTABLE - Works on any device with any project path
+"""
+
+from huggingface_hub import hf_hub_download
+from pathlib import Path
+import os
+import sys
+import shutil
+
+# Detect PROJECT_ROOT dynamically
+def get_project_root():
+    """
+    Find project root by looking for config/ directory
+    Works regardless of where app.py is located
+    """
+    current_path = Path(__file__).resolve()  # Full path to this file
+    
+    # Go up from src/utils/model_downloader.py to project root
+    for parent in current_path.parents:
+        if (parent / 'config').exists() and (parent / 'webapp').exists():
+            return parent
+    
+    # Fallback: assume parent of src/
+    return current_path.parent.parent.parent
+
+PROJECT_ROOT = get_project_root()
+REPO_ID = "itsluckysharma01/NETRA-Models"
+CACHE_DIR = PROJECT_ROOT / 'ai_models'  # Models cached in project root
+
+print(f"\n🔍 [Model Downloader] PROJECT_ROOT detected: {PROJECT_ROOT}")
+print(f"🔍 [Model Downloader] CACHE_DIR: {CACHE_DIR}\n")
+
+def download_model(filename):
+    """
+    Download model from Hugging Face Hub with automatic path handling
+    
+    Args:
+        filename: Model file path (e.g., 'ai_models/activity_recognition/violence_model.h5')
+    
+    Returns:
+        str: Path to downloaded/cached model (absolute path)
+    """
+    try:
+        # Ensure cache directory exists
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        
+        # Check if model already exists in flat structure
+        local_path = CACHE_DIR / filename
+        if local_path.exists():
+            print(f"✅ Model cached: {filename}")
+            return str(local_path)
+        
+        # Download from Hugging Face Hub (goes to HF cache)
+        print(f"📥 Downloading: {filename}")
+        downloaded_path = hf_hub_download(
+            repo_id=REPO_ID,
+            filename=filename,
+            cache_dir=str(CACHE_DIR),
+            local_files_only=False
+        )
+        
+        # Copy from HF cache structure to flat ai_models/ structure
+        src_path = Path(downloaded_path)
+        
+        # Create destination directory
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Copy file to flat structure
+        shutil.copy2(src_path, local_path)
+        print(f"✅ Downloaded and cached: {filename}")
+        return str(local_path)
+        
+    except Exception as e:
+        print(f"❌ Error downloading {filename}: {e}")
+        return None
+
+
+def ensure_model_exists(filename):
+    """
+    Ensure a model exists locally, download if necessary
+    
+    Args:
+        filename: Model file path
+    
+    Returns:
+        bool: True if model exists or was downloaded successfully
+    """
+    local_path = CACHE_DIR / filename
+    
+    # Already exists
+    if local_path.exists():
+        return True
+    
+    # Try to download
+    result = download_model(filename)
+    return result is not None
+
+
+def setup_all_models():
+    """Download all required models on startup"""
+    models = [
+        "ai_models/activity_recognition/violence_model.h5",
+        "ai_models/object_detection/yolov8n.pt",
+        "ai_models/pose_detection/yolo11n-pose.pt",
+        "ai_models/weapon_detection/best.pt",
+        "ai_models/analysis_models/binarycnn200.h5",
+        "ai_models/analysis_models/CNN93.h5",
+        "ai_models/analysis_models/CustomCNN.h5",
+        "ai_models/analysis_models/fight_detection_model.h5",
+    ]
+    
+    print("\n" + "=" * 60)
+    print("📥 SETTING UP AI MODELS FROM HUGGING FACE HUB")
+    print("=" * 60)
+    print(f"🔍 PROJECT_ROOT: {PROJECT_ROOT}")
+    print(f"🔍 CACHE_DIR: {CACHE_DIR}")
+    print(f"🔍 Cache exists: {CACHE_DIR.exists()}")
+    print("=" * 60)
+    
+    downloaded = 0
+    cached = 0
+    failed = 0
+    
+    for model in models:
+        local_path = CACHE_DIR / model
+        
+        if local_path.exists():
+            print(f"✅ Cached: {model}")
+            cached += 1
+        else:
+            try:
+                result = download_model(model)
+                if result:
+                    downloaded += 1
+                else:
+                    failed += 1
+            except Exception as e:
+                print(f"⚠️  Warning: Could not load {model}")
+                failed += 1
+    
+    print("\n" + "=" * 60)
+    print(f"✅ Setup Complete: {downloaded} downloaded, {cached} cached, {failed} warnings")
+    print(f"📁 Models should be at: {CACHE_DIR}")
+    print("=" * 60 + "\n")