Upload 11 files

.gitattributes

@@ -4,3 +4,5 @@
 *.mp4 filter=lfs diff=lfs merge=lfs -text
 *.avi filter=lfs diff=lfs merge=lfs -text
 *.mov filter=lfs diff=lfs merge=lfs -text
+data/annotated_frame.png filter=lfs diff=lfs merge=lfs -text
+data/frame.png filter=lfs diff=lfs merge=lfs -text

data/vehicles.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0f2ceb75fcb9be14c74abcc88b79a1de722019992262d65c2cf1fbf5a0ff0fa8
+size 6106564

data/vehicles_output.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b0436bb36acd10a2e41cd9748a33555794b0595ee7730e30b7d6ebceb5c75678
+size 14132171

models/VisDrone_YOLO_x2.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:53910cdfafd0065503ffeafdd41a1acecf892551d0ab971cfc2cb869836a4558
+size 10432046

models/yolov8n.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f59b3d833e2ff32e194b5bb8e08d211dc7c5bdf144b90d2c8412c47ccfc83b36
+size 6549796

src/__init__.py

@@ -0,0 +1,49 @@
+"""
+Vehicle Detection and Speed Estimation Package
+===============================================
+
+A comprehensive system for vehicle detection, tracking, counting, and speed estimation
+using YOLO object detection and perspective transformation.
+
+Authors:
+    - Abhay Gupta (0205CC221005)
+    - Aditi Lakhera (0205CC221011)
+    - Balraj Patel (0205CC221049)
+    - Bhumika Patel (0205CC221050)
+
+Modules:
+    - annotator: Frame annotation and visualization
+    - speed_estimator: Vehicle speed calculation
+    - view_transformer: Perspective transformation utilities
+    - exceptions: Custom exception classes
+"""
+
+__version__ = "1.0.0"
+__author__ = "Abhay Gupta, Aditi Lakhera, Balraj Patel, Bhumika Patel"
+
+# Import main classes for easy access
+from .annotator import FrameAnnotator
+from .speed_estimator import VehicleSpeedEstimator
+from .view_transformer import PerspectiveTransformer
+from .exceptions import (
+    VehicleDetectionError,
+    VideoProcessingError,
+    ModelLoadError,
+    ConfigurationError,
+    DetectionError,
+    TrackingError,
+    SpeedEstimationError
+)
+
+__all__ = [
+    "FrameAnnotator",
+    "VehicleSpeedEstimator",
+    "PerspectiveTransformer",
+    "VehicleDetectionError",
+    "VideoProcessingError",
+    "ModelLoadError",
+    "ConfigurationError",
+    "DetectionError",
+    "TrackingError",
+    "SpeedEstimationError",
+]

src/annotator.py

@@ -0,0 +1,237 @@
+"""
+Frame Annotation Module
+========================
+
+Provides comprehensive video frame annotation capabilities for vehicle detection
+visualization including bounding boxes, labels, trajectories, and counting zones.
+
+Authors:
+    - Abhay Gupta (0205CC221005)
+    - Aditi Lakhera (0205CC221011)
+    - Balraj Patel (0205CC221049)
+    - Bhumika Patel (0205CC221050)
+"""
+
+import numpy as np
+import supervision as sv
+from typing import List, Optional, Tuple
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class FrameAnnotator:
+    """
+    Comprehensive frame annotation system for vehicle detection visualization.
+    
+    This class manages multiple annotation layers including bounding boxes,
+    labels, object trajectories, counting lines, and detection zones.
+    """
+    
+    def __init__(
+        self,
+        video_resolution: Tuple[int, int],
+        show_boxes: bool = True,
+        show_labels: bool = True,
+        show_traces: bool = True,
+        show_line_zones: bool = True,
+        trace_length: int = 20,
+        zone_polygon: Optional[np.ndarray] = None
+    ):
+        """
+        Initialize the frame annotator.
+        
+        Args:
+            video_resolution: Video resolution as (width, height)
+            show_boxes: Enable bounding box annotations
+            show_labels: Enable label annotations
+            show_traces: Enable trajectory trace annotations
+            show_line_zones: Enable line zone annotations
+            trace_length: Maximum number of points in trajectory trace
+            zone_polygon: Optional polygon defining detection zone
+        """
+        self.resolution = video_resolution
+        self.show_boxes = show_boxes
+        self.show_labels = show_labels
+        self.show_traces = show_traces
+        self.show_line_zones = show_line_zones
+        self.zone_polygon = zone_polygon
+        
+        # Calculate optimal annotation parameters based on resolution
+        self.line_thickness = sv.calculate_optimal_line_thickness(video_resolution)
+        self.text_scale = sv.calculate_optimal_text_scale(video_resolution)
+        
+        logger.info(f"Initializing annotator for {video_resolution[0]}x{video_resolution[1]}")
+        logger.info(f"Line thickness: {self.line_thickness}, Text scale: {self.text_scale}")
+        
+        # Initialize annotation components
+        self._setup_annotators(trace_length)
+    
+    def _setup_annotators(self, trace_length: int) -> None:
+        """
+        Set up individual annotation components.
+        
+        Args:
+            trace_length: Maximum trajectory trace length
+        """
+        # Bounding box annotator
+        if self.show_boxes:
+            self.box_drawer = sv.BoxAnnotator(
+                thickness=self.line_thickness,
+                color_lookup=sv.ColorLookup.TRACK
+            )
+            logger.debug("Box annotator initialized")
+        else:
+            self.box_drawer = None
+        
+        # Label annotator
+        if self.show_labels:
+            self.label_drawer = sv.LabelAnnotator(
+                text_thickness=self.line_thickness,
+                text_scale=self.text_scale,
+                text_position=sv.Position.BOTTOM_CENTER,
+                color_lookup=sv.ColorLookup.TRACK
+            )
+            logger.debug("Label annotator initialized")
+        else:
+            self.label_drawer = None
+        
+        # Trajectory trace annotator
+        if self.show_traces:
+            self.trace_drawer = sv.TraceAnnotator(
+                thickness=self.line_thickness,
+                trace_length=trace_length,
+                position=sv.Position.BOTTOM_CENTER,
+                color_lookup=sv.ColorLookup.TRACK
+            )
+            logger.debug(f"Trace annotator initialized with length {trace_length}")
+        else:
+            self.trace_drawer = None
+        
+        # Line zone annotator
+        if self.show_line_zones:
+            self.line_zone_drawer = sv.LineZoneAnnotator(
+                thickness=self.line_thickness,
+                text_thickness=self.line_thickness,
+                text_scale=self.text_scale,
+                color=sv.Color.WHITE,
+                text_color=sv.Color.BLACK,
+                display_in_count=True,
+                display_out_count=True
+            )
+            logger.debug("Line zone annotator initialized")
+        else:
+            self.line_zone_drawer = None
+        
+        # Polygon zone annotator (for detection area visualization)
+        if self.zone_polygon is not None:
+            try:
+                zone = sv.PolygonZone(
+                    polygon=self.zone_polygon,
+                    frame_resolution_wh=self.resolution
+                )
+                self.polygon_drawer = sv.PolygonZoneAnnotator(
+                    zone=zone,
+                    color=sv.Color.GREEN,
+                    thickness=self.line_thickness,
+                    display_in_zone_count=False
+                )
+                logger.debug("Polygon zone annotator initialized")
+            except Exception as e:
+                logger.warning(f"Failed to initialize polygon zone: {e}")
+                self.polygon_drawer = None
+        else:
+            self.polygon_drawer = None
+    
+    def draw_annotations(
+        self,
+        frame: np.ndarray,
+        detections: sv.Detections,
+        labels: Optional[List[str]] = None,
+        line_zones: Optional[List[sv.LineZone]] = None
+    ) -> np.ndarray:
+        """
+        Apply all enabled annotations to a video frame.
+        
+        Args:
+            frame: Input video frame (BGR format)
+            detections: Detection results to annotate
+            labels: Optional list of labels for each detection
+            line_zones: Optional list of line zones for counting visualization
+            
+        Returns:
+            Annotated frame
+        """
+        # Create a copy to avoid modifying original
+        annotated = frame.copy()
+        
+        try:
+            # Draw polygon zone first (background layer)
+            if self.polygon_drawer is not None:
+                annotated = self.polygon_drawer.annotate(annotated)
+            
+            # Draw bounding boxes
+            if self.box_drawer is not None and len(detections) > 0:
+                annotated = self.box_drawer.annotate(
+                    scene=annotated,
+                    detections=detections
+                )
+            
+            # Draw trajectory traces
+            if self.trace_drawer is not None and len(detections) > 0:
+                annotated = self.trace_drawer.annotate(
+                    scene=annotated,
+                    detections=detections
+                )
+            
+            # Draw labels
+            if self.label_drawer is not None and len(detections) > 0:
+                annotated = self.label_drawer.annotate(
+                    scene=annotated,
+                    detections=detections,
+                    labels=labels
+                )
+            
+            # Draw line zones
+            if self.line_zone_drawer is not None and line_zones:
+                for zone in line_zones:
+                    annotated = self.line_zone_drawer.annotate(
+                        frame=annotated,
+                        line_counter=zone
+                    )
+            
+            return annotated
+            
+        except Exception as e:
+            logger.error(f"Error during annotation: {e}")
+            # Return original frame if annotation fails
+            return frame
+    
+    def update_settings(
+        self,
+        show_boxes: Optional[bool] = None,
+        show_labels: Optional[bool] = None,
+        show_traces: Optional[bool] = None,
+        show_line_zones: Optional[bool] = None
+    ) -> None:
+        """
+        Update annotation settings dynamically.
+        
+        Args:
+            show_boxes: Enable/disable bounding boxes
+            show_labels: Enable/disable labels
+            show_traces: Enable/disable traces
+            show_line_zones: Enable/disable line zones
+        """
+        if show_boxes is not None:
+            self.show_boxes = show_boxes
+        if show_labels is not None:
+            self.show_labels = show_labels
+        if show_traces is not None:
+            self.show_traces = show_traces
+        if show_line_zones is not None:
+            self.show_line_zones = show_line_zones
+        
+        logger.info(f"Annotation settings updated: boxes={self.show_boxes}, "
+                   f"labels={self.show_labels}, traces={self.show_traces}, "
+                   f"zones={self.show_line_zones}")

src/exceptions.py

@@ -0,0 +1,47 @@
+"""
+Custom Exception Classes for Vehicle Detection System
+======================================================
+
+Defines custom exceptions for better error handling and user feedback.
+
+Authors:
+    - Abhay Gupta (0205CC221005)
+    - Aditi Lakhera (0205CC221011)
+    - Balraj Patel (0205CC221049)
+    - Bhumika Patel (0205CC221050)
+"""
+
+
+class VehicleDetectionError(Exception):
+    """Base exception for vehicle detection system."""
+    pass
+
+
+class VideoProcessingError(VehicleDetectionError):
+    """Raised when video processing fails."""
+    pass
+
+
+class ModelLoadError(VehicleDetectionError):
+    """Raised when model loading fails."""
+    pass
+
+
+class ConfigurationError(VehicleDetectionError):
+    """Raised when configuration is invalid."""
+    pass
+
+
+class DetectionError(VehicleDetectionError):
+    """Raised when object detection fails."""
+    pass
+
+
+class TrackingError(VehicleDetectionError):
+    """Raised when object tracking fails."""
+    pass
+
+
+class SpeedEstimationError(VehicleDetectionError):
+    """Raised when speed estimation fails."""
+    pass

src/speed_estimator.py

@@ -0,0 +1,236 @@
+"""
+Vehicle Speed Estimation Module
+================================
+
+Implements speed calculation for tracked vehicles using perspective transformation
+and temporal position tracking with smoothing and outlier detection.
+
+Authors:
+    - Abhay Gupta (0205CC221005)
+    - Aditi Lakhera (0205CC221011)
+    - Balraj Patel (0205CC221049)
+    - Bhumika Patel (0205CC221050)
+
+Technical Approach:
+    - Tracks vehicle positions across frames in transformed coordinate space
+    - Calculates displacement over time windows
+    - Applies smoothing to reduce noise
+    - Converts to desired speed units
+"""
+
+import numpy as np
+import supervision as sv
+from collections import defaultdict, deque
+from typing import Dict, Optional
+import logging
+
+from .view_transformer import PerspectiveTransformer
+
+logger = logging.getLogger(__name__)
+
+
+class VehicleSpeedEstimator:
+    """
+    Estimates vehicle speeds using perspective-corrected position tracking.
+    
+    This class maintains a history of vehicle positions in real-world coordinates
+    and calculates speeds based on displacement over time.
+    """
+    
+    def __init__(
+        self,
+        fps: int,
+        transformer: PerspectiveTransformer,
+        history_duration: int = 1,
+        speed_unit: str = "km/h",
+        min_frames_for_speed: Optional[int] = None
+    ):
+        """
+        Initialize the speed estimator.
+        
+        Args:
+            fps: Video frames per second
+            transformer: Perspective transformation instance
+            history_duration: Time window for speed calculation (seconds)
+            speed_unit: Output speed unit ("km/h", "mph", or "m/s")
+            min_frames_for_speed: Minimum frames needed for speed calculation
+                                 (defaults to fps/2)
+        """
+        self.fps = fps
+        self.transformer = transformer
+        self.history_duration = history_duration
+        self.speed_unit = speed_unit
+        
+        # Calculate minimum frames needed for reliable speed estimation
+        self.min_frames = min_frames_for_speed or max(int(fps / 2), 5)
+        
+        # Maximum history length in frames
+        max_history_frames = int(fps * history_duration)
+        
+        # Store position history for each tracked object
+        # Key: tracker_id, Value: deque of (x, y) positions in real-world coordinates
+        self.position_history: Dict[int, deque] = defaultdict(
+            lambda: deque(maxlen=max_history_frames)
+        )
+        
+        # Speed unit conversion factors (from m/s)
+        self.unit_conversions = {
+            "km/h": 3.6,
+            "mph": 2.23694,
+            "m/s": 1.0
+        }
+        
+        if speed_unit not in self.unit_conversions:
+            raise ValueError(f"Invalid speed unit: {speed_unit}")
+        
+        self.conversion_factor = self.unit_conversions[speed_unit]
+        
+        logger.info(f"Speed estimator initialized: {fps}fps, {history_duration}s history, "
+                   f"unit={speed_unit}, min_frames={self.min_frames}")
+    
+    def _calculate_speed_for_vehicle(self, tracker_id: int) -> Optional[float]:
+        """
+        Calculate speed for a specific tracked vehicle.
+        
+        Args:
+            tracker_id: Unique tracker ID
+            
+        Returns:
+            Speed in configured units, or None if insufficient data
+        """
+        positions = self.position_history[tracker_id]
+        
+        # Need sufficient position history
+        if len(positions) < self.min_frames:
+            return None
+        
+        try:
+            # Get first and last positions
+            start_pos = positions[0]
+            end_pos = positions[-1]
+            
+            # Calculate Euclidean distance in real-world coordinates (meters)
+            displacement = np.linalg.norm(end_pos - start_pos)
+            
+            # Calculate time elapsed
+            time_elapsed = len(positions) / self.fps
+            
+            # Avoid division by zero
+            if time_elapsed == 0:
+                return None
+            
+            # Calculate speed in m/s
+            speed_ms = displacement / time_elapsed
+            
+            # Convert to desired unit
+            speed = speed_ms * self.conversion_factor
+            
+            # Apply reasonable bounds (0-300 km/h equivalent)
+            max_speed = 300 * self.unit_conversions["km/h"] / self.conversion_factor
+            if speed < 0 or speed > max_speed:
+                logger.debug(f"Outlier speed detected for vehicle {tracker_id}: {speed:.1f}")
+                return None
+            
+            return speed
+            
+        except Exception as e:
+            logger.warning(f"Error calculating speed for vehicle {tracker_id}: {e}")
+            return None
+    
+    def _apply_smoothing(self, speeds: np.ndarray, window_size: int = 3) -> np.ndarray:
+        """
+        Apply moving average smoothing to speed values.
+        
+        Args:
+            speeds: Array of speed values
+            window_size: Smoothing window size
+            
+        Returns:
+            Smoothed speed array
+        """
+        if len(speeds) < window_size:
+            return speeds
+        
+        # Simple moving average
+        smoothed = np.convolve(speeds, np.ones(window_size)/window_size, mode='same')
+        return smoothed
+    
+    def estimate(self, detections: sv.Detections) -> sv.Detections:
+        """
+        Estimate speeds for all detected vehicles in current frame.
+        
+        Args:
+            detections: Detection results from current frame
+            
+        Returns:
+            Updated detections with 'speed' field added to data
+        """
+        # Initialize speed array
+        speeds = []
+        
+        # Check if we have tracker IDs
+        if not hasattr(detections, 'tracker_id') or detections.tracker_id is None:
+            logger.warning("No tracker IDs found in detections")
+            detections.data["speed"] = np.zeros(len(detections))
+            return detections
+        
+        # Get anchor points (bottom center of bounding boxes)
+        anchor_points = detections.get_anchors_coordinates(
+            anchor=sv.Position.BOTTOM_CENTER
+        )
+        
+        # Transform points to real-world coordinates
+        try:
+            transformed_points = self.transformer.apply_transformation(anchor_points)
+        except Exception as e:
+            logger.error(f"Error transforming points: {e}")
+            detections.data["speed"] = np.zeros(len(detections))
+            return detections
+        
+        # Process each detection
+        for tracker_id, point in zip(detections.tracker_id, transformed_points):
+            # Add position to history
+            self.position_history[tracker_id].append(point)
+            
+            # Calculate speed
+            speed = self._calculate_speed_for_vehicle(tracker_id)
+            
+            # Use 0 if speed cannot be calculated
+            speeds.append(speed if speed is not None else 0.0)
+        
+        # Convert to numpy array and round
+        speeds = np.array(speeds)
+        speeds = np.round(speeds).astype(int)
+        
+        # Add to detections data
+        detections.data["speed"] = speeds
+        
+        return detections
+    
+    def reset(self) -> None:
+        """Clear all position history."""
+        self.position_history.clear()
+        logger.info("Speed estimator history cleared")
+    
+    def get_tracked_vehicle_count(self) -> int:
+        """
+        Get number of currently tracked vehicles.
+        
+        Returns:
+            Number of vehicles with position history
+        """
+        return len(self.position_history)
+    
+    def cleanup_old_tracks(self, active_ids: set) -> None:
+        """
+        Remove position history for vehicles no longer being tracked.
+        
+        Args:
+            active_ids: Set of currently active tracker IDs
+        """
+        inactive_ids = set(self.position_history.keys()) - active_ids
+        for tracker_id in inactive_ids:
+            del self.position_history[tracker_id]
+        
+        if inactive_ids:
+            logger.debug(f"Cleaned up {len(inactive_ids)} inactive tracks")

src/view_transformer.py

@@ -0,0 +1,254 @@
+"""
+Perspective Transformation Module
+==================================
+
+Implements perspective transformation for converting camera view coordinates
+to real-world top-down coordinates, essential for accurate speed calculation.
+
+Authors:
+    - Abhay Gupta (0205CC221005)
+    - Aditi Lakhera (0205CC221011)
+    - Balraj Patel (0205CC221049)
+    - Bhumika Patel (0205CC221050)
+
+Mathematical Background:
+    Perspective transformation uses a 3x3 homography matrix to map points
+    from one plane to another. This is crucial for converting pixel coordinates
+    to real-world measurements.
+"""
+
+import cv2
+import numpy as np
+from typing import Tuple
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class PerspectiveTransformer:
+    """
+    Handles perspective transformation between camera view and real-world coordinates.
+    
+    This class computes and applies homography transformations to convert
+    image coordinates to a top-down view with real-world measurements.
+    """
+    
+    def __init__(
+        self,
+        source_points: np.ndarray,
+        target_points: np.ndarray
+    ):
+        """
+        Initialize the perspective transformer.
+        
+        Args:
+            source_points: 4 points in source image (camera view)
+                          Shape: (4, 2) with [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
+            target_points: 4 corresponding points in target space (real-world)
+                          Shape: (4, 2) with same format
+                          
+        Raises:
+            ValueError: If points are invalid or transformation cannot be computed
+        """
+        # Validate inputs
+        self._validate_points(source_points, "source")
+        self._validate_points(target_points, "target")
+        
+        # Store points as float32 (required by OpenCV)
+        self.source_pts = source_points.astype(np.float32)
+        self.target_pts = target_points.astype(np.float32)
+        
+        # Compute transformation matrix
+        self.matrix = self._compute_transformation_matrix()
+        
+        # Compute inverse transformation (for reverse mapping if needed)
+        self.inverse_matrix = self._compute_inverse_matrix()
+        
+        logger.info("Perspective transformer initialized successfully")
+        logger.debug(f"Source points:\n{self.source_pts}")
+        logger.debug(f"Target points:\n{self.target_pts}")
+    
+    def _validate_points(self, points: np.ndarray, name: str) -> None:
+        """
+        Validate point array format and values.
+        
+        Args:
+            points: Points array to validate
+            name: Name for error messages
+            
+        Raises:
+            ValueError: If points are invalid
+        """
+        if not isinstance(points, np.ndarray):
+            raise ValueError(f"{name} points must be a numpy array")
+        
+        if points.shape != (4, 2):
+            raise ValueError(
+                f"{name} points must have shape (4, 2), got {points.shape}"
+            )
+        
+        if not np.isfinite(points).all():
+            raise ValueError(f"{name} points contain invalid values (NaN or Inf)")
+    
+    def _compute_transformation_matrix(self) -> np.ndarray:
+        """
+        Compute the perspective transformation matrix.
+        
+        Returns:
+            3x3 homography matrix
+            
+        Raises:
+            ValueError: If transformation cannot be computed
+        """
+        try:
+            matrix = cv2.getPerspectiveTransform(
+                self.source_pts,
+                self.target_pts
+            )
+            
+            # Validate matrix
+            if matrix is None or not np.isfinite(matrix).all():
+                raise ValueError("Invalid transformation matrix computed")
+            
+            logger.debug(f"Transformation matrix:\n{matrix}")
+            return matrix
+            
+        except cv2.error as e:
+            raise ValueError(f"Failed to compute perspective transform: {e}")
+    
+    def _compute_inverse_matrix(self) -> np.ndarray:
+        """
+        Compute the inverse transformation matrix.
+        
+        Returns:
+            3x3 inverse homography matrix
+        """
+        try:
+            inverse = cv2.getPerspectiveTransform(
+                self.target_pts,
+                self.source_pts
+            )
+            return inverse
+        except Exception as e:
+            logger.warning(f"Could not compute inverse matrix: {e}")
+            return None
+    
+    def apply_transformation(self, points: np.ndarray) -> np.ndarray:
+        """
+        Transform points from source to target coordinate system.
+        
+        Args:
+            points: Array of points to transform
+                   Shape: (N, 2) where N is number of points
+                   
+        Returns:
+            Transformed points in target coordinate system
+            Shape: (N, 2)
+            
+        Raises:
+            ValueError: If points have invalid shape
+        """
+        # Handle empty input
+        if points.size == 0:
+            return points
+        
+        # Validate input shape
+        if len(points.shape) != 2 or points.shape[1] != 2:
+            raise ValueError(
+                f"Points must have shape (N, 2), got {points.shape}"
+            )
+        
+        try:
+            # Reshape for OpenCV: (N, 1, 2)
+            points_reshaped = points.reshape(-1, 1, 2).astype(np.float32)
+            
+            # Apply transformation
+            transformed = cv2.perspectiveTransform(
+                points_reshaped,
+                self.matrix
+            )
+            
+            # Reshape back to (N, 2)
+            result = transformed.reshape(-1, 2)
+            
+            return result
+            
+        except Exception as e:
+            logger.error(f"Error applying transformation: {e}")
+            raise ValueError(f"Transformation failed: {e}")
+    
+    def apply_inverse_transformation(self, points: np.ndarray) -> np.ndarray:
+        """
+        Transform points from target back to source coordinate system.
+        
+        Args:
+            points: Array of points in target coordinates
+                   Shape: (N, 2)
+                   
+        Returns:
+            Points in source coordinate system
+            Shape: (N, 2)
+            
+        Raises:
+            ValueError: If inverse matrix not available or transformation fails
+        """
+        if self.inverse_matrix is None:
+            raise ValueError("Inverse transformation matrix not available")
+        
+        if points.size == 0:
+            return points
+        
+        try:
+            points_reshaped = points.reshape(-1, 1, 2).astype(np.float32)
+            transformed = cv2.perspectiveTransform(
+                points_reshaped,
+                self.inverse_matrix
+            )
+            return transformed.reshape(-1, 2)
+            
+        except Exception as e:
+            logger.error(f"Error applying inverse transformation: {e}")
+            raise ValueError(f"Inverse transformation failed: {e}")
+    
+    def transform_single_point(self, x: float, y: float) -> Tuple[float, float]:
+        """
+        Transform a single point (convenience method).
+        
+        Args:
+            x: X coordinate in source system
+            y: Y coordinate in source system
+            
+        Returns:
+            Tuple of (x, y) in target system
+        """
+        point = np.array([[x, y]], dtype=np.float32)
+        transformed = self.apply_transformation(point)
+        return tuple(transformed[0])
+    
+    def get_transformation_matrix(self) -> np.ndarray:
+        """
+        Get the transformation matrix.
+        
+        Returns:
+            3x3 homography matrix
+        """
+        return self.matrix.copy()
+    
+    def get_scale_factors(self) -> Tuple[float, float]:
+        """
+        Estimate scale factors in x and y directions.
+        
+        Returns:
+            Tuple of (scale_x, scale_y) representing pixels per meter
+        """
+        # Transform corners to estimate scaling
+        source_width = np.linalg.norm(self.source_pts[1] - self.source_pts[0])
+        source_height = np.linalg.norm(self.source_pts[3] - self.source_pts[0])
+        
+        target_width = np.linalg.norm(self.target_pts[1] - self.target_pts[0])
+        target_height = np.linalg.norm(self.target_pts[3] - self.target_pts[0])
+        
+        scale_x = source_width / target_width if target_width > 0 else 1.0
+        scale_y = source_height / target_height if target_height > 0 else 1.0
+        
+        return scale_x, scale_y