HaniaRuby/crash-detector-3dresnet

3D ResNet Car Crash Detector (TorchScript)

This repository hosts a compiled TorchScript (JIT) model for automated traffic accident and car crash detection from video clips.

Because this model is exported via TorchScript, it has zero external codebase dependencies—you do not need to clone the training repository or import any custom PyTorch Lightning classes.

---

Model Specifications

• Architecture: 3D ResNet-18 (r3d_18)
• Input Format: (Batch, Channels, Frames, Height, Width) -> (1, 3, 16, 112, 112)
• Color Space: RGB normalized to [0.0, 1.0]
• Output: Single float tensor representing Crash Probability [0.0 to 1.0] (Sigmoid pre-applied).

---

Quickstart Usage

1. Install Dependencies

pip install torch torchvision opencv-python numpy huggingface_hub

2. Python Inference Script

Paste and run the following script to load the model directly from Hugging Face and evaluate any .mp4 or .avi video file:

import cv2
import numpy as np
import torch
from huggingface_hub import hf_hub_download

# Configuration
HF_REPO_ID = "HaniaRuby/crash-detector-3dresnet"
HF_FILENAME = "crash_detector_3dresnet_jit.pt"

def preprocess_video(video_path, num_frames=16, frame_size=(112, 112)):
    """Extracts 16 uniform frames from a video file, normalizes, and reshapes for 3D ResNet."""
    cap = cv2.VideoCapture(video_path)
    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
    
    if total_frames <= 0:
        raise ValueError(f"Could not read frames from video file: {video_path}")

    # Sample 'num_frames' evenly across the clip duration
    frame_indices = np.linspace(0, total_frames - 1, num_frames, dtype=int)
    frames = []

    for idx in range(total_frames):
        ret, frame = cap.read()
        if not ret:
            break
        if idx in frame_indices:
            # Convert OpenCV BGR -> RGB, resize, and normalize to [0, 1]
            frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
            frame = cv2.resize(frame, frame_size)
            frame = frame.astype(np.float32) / 255.0
            frames.append(frame)

    cap.release()

    # Zero-pad if video duration is under 16 frames
    while len(frames) < num_frames:
        frames.append(np.zeros((*frame_size, 3), dtype=np.float32))

    # Convert to NumPy array: (16, 112, 112, 3)
    video_np = np.array(frames[:num_frames], dtype=np.float32)
    
    # Transpose to PyTorch 3D CNN tensor shape: (C, T, H, W) -> (3, 16, 112, 112)
    video_tensor = torch.tensor(video_np).permute(3, 0, 1, 2)
    
    # Add Batch dimension -> (1, 3, 16, 112, 112)
    return video_tensor.unsqueeze(0)

def predict_crash(video_path):
    print(f"Fetching compiled model from Hugging Face: {HF_REPO_ID}...")
    model_path = hf_hub_download(repo_id=HF_REPO_ID, filename=HF_FILENAME)

    print("Loading compiled TorchScript runtime...")
    model = torch.jit.load(model_path)
    model.eval()

    print(f"Processing video file: {video_path}")
    input_tensor = preprocess_video(video_path)

    print("Running model inference...")
    with torch.no_grad():
        crash_probability = model(input_tensor).item()

    print("\n" + "="*45)
    print(f"Input Video       : {video_path}")
    print(f"Crash Probability : {crash_probability * 100:.2f}%")
    print(f"Status            : {'CRASH DETECTED' if crash_probability > 0.5 else 'NORMAL DRIVING'}")
    print("="*45)

if __name__ == "__main__":
    # Replace with path to your video file
    video_file = "path/to/sample_video.mp4"
    predict_crash(video_file)