README.md

Intracranial Hemorrhage Detection

AI-assisted screening system for intracranial hemorrhage (ICH) from head CT (DICOM) images.

This project provides a Flask web interface for:

• uploading single or batch DICOM scans,
• running model inference,
• viewing Grad-CAM visualizations,
• browsing past reports and logs,
• reviewing calibration and evaluation summaries.

Project Overview

Intracranial hemorrhage is a time-critical emergency finding in neuroimaging. This repository focuses on a practical screening workflow with explainability and structured report output.

The system is built for decision support and triage assistance, not standalone diagnosis.

Model and Artifacts

Model weights and related inference artifacts are hosted on Hugging Face:

• Hugging Face Model Repository

Detailed Performance Report

Detailed performance and B4-specific analysis are documented separately in:

• B4_Performance_Report.md

Repository Structure

• app.py: Flask application entry point
• run_interface.py: adapter layer between app and inference implementation
• download_imp/: inference code and local artifact layout
• templates/: HTML templates (Jinja2)
• static/: styles and static assets
• docs/: GitHub Pages content

Requirements

• Python 3.10+ (3.12 works)
• pip
• virtual environment (recommended)

Install dependencies:

pip install -r requirements.txt

Environment Setup

Create local environment file from template:

cp .env.example .env

Important variables in .env:

• ICH_APP_DEBUG: run Flask in debug mode (1 or 0)
• ICH_APP_PORT: app port (default 7860)
• ICH_SECRET_KEY: Flask secret key
• ICH_MAX_UPLOAD_MB: max upload size in MB
• ICH_FOLD_SELECTION: ensemble, best, or fold id (0 to 4)
• ICH_LOCAL_MODE: enables local directory scanning mode
• ICH_LOG_LEVEL: DEBUG, INFO, WARNING, ERROR

Run the Application

python app.py

Open in browser:

http://127.0.0.1:7860

Basic Usage

1. Go to the upload page.
2. Upload one .dcm, multiple .dcm files, or batch input.
3. Wait for inference and report generation.
4. Review:
   • screening outcome,
   • calibrated probability,
   • confidence band,
   • triage action,
   • Grad-CAM overlay.
5. Use Reports / Logs / Evaluation pages for history and analysis.

Notes

• Keep heavy model binaries out of GitHub (managed via .gitignore).
• Generated report outputs are created during runtime.
• If required artifacts are missing locally, fetch them from the Hugging Face repository linked above.

Disclaimer

This system is an AI-assisted screening and decision-support tool. It does not provide a medical diagnosis and must be used with qualified clinical review.