README.md

metadata

title: ICH Detection Pipeline
emoji: 🏥
colorFrom: blue
colorTo: pink
sdk: docker
pinned: false

AI Medical Intelligence Pipeline for CT Scan Analysis

AI medical intelligence pipeline for intracranial hemorrhage (ICH) analysis 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 intelligence pipeline 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

When model files are not present locally (for example on Render), the app can download required artifacts from this Hugging Face repository at runtime.

Detailed Performance Report

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

• B4_Performance_Report.md

GitHub Pages Setup

For step-by-step GitHub Pages setup (project site and username.github.io site), see:

• GITHUB_PAGES_DOCUMENT.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
• ICH_HF_MODEL_REPO: Hugging Face model repo used for runtime artifact download
• ICH_HF_TOKEN: optional token (required only if the Hugging Face repo is private)

Run the Application

python app.py

Open in browser:

http://127.0.0.1:7860

Deploy on Render

This repository includes render.yaml for Render deployment.

1. Push the repository to GitHub.
2. In Render, create a new Blueprint/Web Service from the repository.
3. Ensure these environment variables are set in Render:
   • ICH_HF_MODEL_REPO=HarshCode/eff_b4_brain
   • ICH_HF_TOKEN (only if repo is private)
   • ICH_SECRET_KEY (recommended custom value)
4. Deploy. The service will start with:

gunicorn app:app --bind 0.0.0.0:$PORT --workers 1 --timeout 180

Note: first startup can take longer because model artifacts may be downloaded from Hugging Face.

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.