Skip to content

leonkaushikdeka/leosa

BranchesTags

Repository files navigation

🔬 ForensicSight v2.0

ForensicSight Python YOLOv8 License

Production-grade real-time forensic analysis system with MSc-level capabilities

Features • Installation • Usage • Documentation • Contributing

📋 Table of Contents

About

ForensicSight v2.0 is an advanced real-time forensic analysis system designed for crime scene investigation and evidence processing. Built with production-grade Python code, it combines state-of-the-art computer vision (YOLOv8) with specialized forensic analysis algorithms to provide lab-quality results in the field.

🎯 Key Capabilities

  • Real-time object detection with 30+ FPS performance
  • Automated evidence categorization following forensic protocols
  • Advanced forensic analysis including bloodstain patterns, GSR detection, and fingerprint enhancement
  • ISO 17025 compliant evidence management system
  • Chain of custody tracking with SHA-256 integrity verification

✨ Features

Core Architecture

Feature Description
YOLOv8s/m Integration State-of-the-art object detection for real-time analysis
Multi-threaded Design Capture → Inference → Main threads for optimal performance
Thread-safe Queues Real-time evidence logging without frame drops
Webcam Support 1280x720 @ 30fps with automatic resolution detection
Demo Mode No camera required for testing and training

Forensic Categorization System

┌─────────────────────────────────────────────────────────────────┐
│                    EVIDENCE CLASSIFICATION                      │
├─────────────────┬─────────────────┬─────────────────────────────┤
│  PRIMARY        │  SEARCH ZONES   │  ANOMALIES                  │
│  (Red, thick=3) │  (Blue, thick=1)│  (Yellow, thick=2)          │
├─────────────────┼─────────────────┼─────────────────────────────┤
│  • sports ball  │  • bed          │  • handbag                  │
│  • bottle       │  • couch        │  • backpack                 │
│  • cell phone   │  • chair        │  • suitcase                 │
│  • knife        │  • dining table │  • box                      │
│  • scissors     │  • refrigerator │  • book                     │
│  • clock        │  • oven         │  • laptop                   │
│  • vase         │  • microwave    │                             │
│  • suitcase     │  • suitcase     │                             │
└─────────────────┴─────────────────┴─────────────────────────────┘

Visual Overlays

  • Header Bar - Case ID and system status
  • Bounding Boxes - Color-coded by evidence type
  • ABFO #2 Ruler - ASTM E2917 compliant scale marker
  • Status Bar - Live evidence counts
  • Zone Prompts - Contextual forensic instructions
  • FPS Counter - Real-time performance monitoring

🔬 Forensic Analysis Modules

A. Bloodstain Pattern Analysis (BPA)

HSV Dual-Range Detection:
  • Primary range:  H:0-10,   S:100-255, V:50-255
  • Secondary range: H:160-180, S:100-255, V:50-255

Pattern Classification:
  ┌──────────────────────────┬──────────────────────────────────┐
  │ Type                     │ Criteria                         │
  ├──────────────────────────┼──────────────────────────────────┤
  │ Drip Stain               │ Circularity > 0.7, Area > 100px  │
  │ Spatter (High Velocity)  │ Area < 50px, irregular shape     │
  │ Spatter (Medium Velocity)│ Area 50-100px, moderate circularity│
  │ Pooling                  │ Area > 500px                     │
  └──────────────────────────┴──────────────────────────────────┘

Morphological Processing:
  • 5x5 kernel opening/closing for noise reduction
  • Automatic logging when blood_ratio > 10%

B. Gunshot Residue (GSR) Detection

Stippling Pattern Analysis:
  • Circular contour detection (area: 10-100px)
  • Circularity threshold: > 0.7

Distance Estimation:
  ┌───────────────────┬─────────────────┐
  │ Particles         │ Distance        │
  ├───────────────────┼─────────────────┤
  │ > 100             │ Contact - 6"    │
  │ 50-100            │ 6" - 12"        │
  │ 20-50             │ 12" - 24"       │
  │ < 20              │ > 24" or no GSR │
  └───────────────────┴─────────────────┘

Visual Markers: Magenta circles on detected particles

C. Latent Fingerprint Enhancement

Image Processing Pipeline:
  1. CLAHE Enhancement (clipLimit=3.0, tileGridSize=8x8)
  2. Gabor Filter Bank (4 orientations: 0°, 45°, 90°, 135°)
  3. Ridge Detection with skeletonization
  4. Minutiae Extraction (endings & bifurcations)

Quality Assessment:
  • Based on intensity standard deviation
  • Automatic trigger when minutiae_count > 10
  • Suitable for AFIS comparison

D. Tool Mark Analysis

Striation Pattern Detection:
  1. Sobel edge detection
  2. Hough Line Transform for parallel lines
  3. Angle variance calculation

Classification:
  ┌───────────────────┬──────────────────┐
  │ Angle Variance    │ Tool Type        │
  ├───────────────────┼──────────────────┤
  │ < 50°             │ Screwdriver      │
  │ 50° - 200°        │ Pliers/Wrench    │
  │ > 200°            │ Irregular/Impact │
  └───────────────────┴──────────────────┘

E. Trace Evidence (ALS Simulation)

Alternative Light Source Profiles:
  • UV (365nm): Semen/Saliva detection
    - HSV: H:130-170, S:50-255, V:0-100
  • Blue (450nm): Blood enhancement
    - HSV: H:100-140, S:50-255, V:0-255

Metrics:
  • Particle density per 1000px
  • Confidence scoring

📁 Evidence Management

Directory Structure (ISO 17025 Compliant)

forensic_case_files/[CASE_ID]/
├── 01_Biology_DNA/
│   └── *[CASE_ID]-BIO-###.png/.jpg
├── 02_Trace_Evidence/
│   └── *[CASE_ID]-TRC-###.png/.jpg
├── 03_Impressions/
│   └── *[CASE_ID]-IMP-###.png/.jpg
├── 04_Ballistics/
│   └── *[CASE_ID]-BAL-###.png/.jpg
├── 05_Crime_Scene_Photography/
│   ├── *[evidence_id]_macro_[hash].png    (close-up)
│   └── *[evidence_id]_context_[hash].jpg  (full frame)
├── 06_Chain_of_Custody/
│   └── custody_*.json
└── master_evidence_registry.csv

Evidence Numbering System

Format: [CASE_ID]-[TYPE]-[###]

Examples:
  CASE-2026-001-BIO-001  → Biological evidence #1
  CASE-2026-001-TRC-003  → Trace evidence #3
  CASE-2026-001-IMP-012  → Impression #12
  CASE-2026-001-BAL-001  → Ballistics #1

Master CSV Registry

Column Description
Evidence_ID Unique identifier
Case_Number Case identifier
Date_Time_Collected UTC timestamp
Type Evidence category
Description Specific findings
Location_Found Bounding box coordinates
Collected_By Custodian ID
Photography_Reference Image file paths
Packaging Evidence packaging
Storage_Location Storage details
Chain_of_Custody Custody events
Contamination_Risks Cross-contamination flags

Integrity Verification

SHA-256 Hash Computation:
  → Every evidence image is hashed
  → Hash stored in metadata JSON
  → Verification during audit

{
  "evidence_id": "CASE-2026-001-BIO-001",
  "image_hash_sha256": "a1b2c3d4...",
  "collection_timestamp": "2026-01-31T07:00:00Z",
  "iso17025_compliant": true
}

Demo

Running locally

💻 Installation

Prerequisites

  • Python 3.8 or higher
  • 4GB RAM (8GB recommended)
  • Webcam (optional, demo mode available)
  • CUDA-compatible GPU (optional, for faster inference)

Setup

# Clone the repository
git clone https://github.com/leonkaushikdeka/leosa.git
cd leosa

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Download YOLOv8 model (automatic on first run)
python ForensicSight_v2.py

Requirements

opencv-python>=4.8.0
ultralytics>=8.0.0
numpy>=1.24.0
scipy>=1.10.0
scikit-image>=0.21.0

🎮 Usage

Basic Commands

# Run with live camera
python ForensicSight_v2.py

# Run in demo mode (no camera required)
python ForensicSight_v2.py --demo

# Run with specific YOLO model size
python ForensicSight_v2.py --model m  # medium model

Keyboard Controls

Key Action
q Quit application
s Manual screenshot
d Toggle demo mode

Programmatic Usage

from ForensicSight_v2 import ForensicSightSystem

# Initialize with custom case ID
system = ForensicSightSystem(
    case_id="CASE-2026-001",
    model_size="s"  # 'n', 's', 'm', 'l', 'x'
)

# Start analysis
system.start()

📊 Output Structure

Evidence Files Generated

  1. Macro Images (*_macro_[hash].png)

    • High-resolution close-up of detected evidence
    • Clean background for analysis

  2. Context Images (*_context_[hash].jpg)

    • Full frame with annotation
    • ABFO #2 scale ruler included
    • Evidence ID overlay

  3. Metadata Files (*_metadata.json)

    • SHA-256 image hash
    • Bounding box coordinates
    • Forensic analysis results
    • Chain of custody timestamps

  4. Master Registry (master_evidence_registry.csv)

    • Complete evidence log
    • Importable to database systems

⚖️ Forensic Standards

ForensicSight v2.0 is designed to comply with international forensic standards:

Standard Compliance
ISO 17025 General requirements for testing laboratories
ASTM E2917 Forensic photography - scale in documentation
SWGDAM DNA analysis guidelines
NIJ standards Physical evidence handling

Chain of Custody Features

  • Timestamp logging (UTC)
  • Custodian identification
  • SHA-256 digital signatures
  • Contamination risk detection
  • Complete audit trail

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    FORENSICSIGHT v2.0 ARCHITECTURE              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌───────────────┐                                             │
│  │   WEBCAM/     │                                             │
│  │   VIDEO       │                                             │
│  └───────┬───────┘                                             │
│          │                                                     │
│          ▼                                                     │
│  ┌───────────────┐    ┌───────────────┐                       │
│  │  CAPTURE      │    │  INFERENCE    │                       │
│  │  THREAD       │───▶│  THREAD       │                       │
│  │  (Queue)      │    │  (YOLOv8)     │                       │
│  └───────────────┘    └───────┬───────┘                       │
│                               │                                │
│                               ▼                                │
│  ┌───────────────────────────────────────────────────────────┐│
│  │                    MAIN THREAD                             ││
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   ││
│  │  │ Evidence    │  │ Overlay     │  │ Evidence Queue  │   ││
│  │  │ Processing  │  │ Rendering   │  │ (Thread-safe)   │   ││
│  │  └─────────────┘  └─────────────┘  └────────┬────────┘   ││
│  └─────────────────────────────────────────────┼────────────┘│
│                                                │              │
│                                                ▼              │
│  ┌───────────────────────────────────────────────────────────┐│
│  │              FORENSIC EVIDENCE MANAGER                     ││
│  │  ┌───────────┐  ┌───────────┐  ┌───────────────────┐     ││
│  │  │ Directory │  │ CSV Log   │  │ Image Storage     │     ││
│  │  │ Structure │  │ Registry  │  │ (SHA-256)         │     ││
│  │  └───────────┘  └───────────┘  └───────────────────┘     ││
│  └───────────────────────────────────────────────────────────┘│
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

🗺️ Roadmap

Version 2.1 (In Progress)

  • GPU acceleration with CUDA
  • Video recording (session capture)
  • PDF report generation

Version 2.2 (Planned)

  • REST API for integration
  • Web dashboard
  • Mobile companion app

Version 3.0 (Future)

  • 3D scene reconstruction
  • Ballistic trajectory analysis
  • AFIS integration
  • Blockchain chain-of-custody

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Ways to Contribute

  • 🐛 Report bugs
  • 💡 Suggest features
  • 📝 Improve documentation
  • 🔧 Submit pull requests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Contact

Leon Kaushik Deka

Project Link: https://github.com/leonkaushikdeka/leosa

Made with 🔬 for Forensic Science

About

ForensicSight v2.0 - Real-time forensic analysis system

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages