README.md

metadata

title: AI MedScan
emoji: 🏥
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

AI MedScan — Medical Image Intelligence Platform 🏥🤖

Industry-grade AI-powered chest radiograph analysis using DenseNet121 architecture with Grad-CAM explainability

Features • Architecture • Quick Start • API Docs • Research

---

🌟 Features

Feature	Description
🧠 DenseNet121 Classification	CheXNet-inspired multi-label classifier detecting 14 thoracic pathologies
👁️ Grad-CAM Explainability	Visual attention maps showing diagnostic regions with anatomical localization
📋 Clinical Reporting	Automated DICOM SR-style reports with ICD-10 codes and differential diagnoses
🛡️ Quality Assessment	CLAHE-enhanced preprocessing with automated image quality scoring
⚡ Real-Time Processing	Sub-2-second analysis with FastAPI async backend
📊 Risk Stratification	Automated triage from CRITICAL to NORMAL with severity scoring

🔬 Detectable Pathologies (14)

#	Pathology	ICD-10	Urgency
1	Atelectasis	J98.11	Moderate
2	Cardiomegaly	I51.7	Moderate
3	Consolidation	J18.9	High
4	Edema	J81.0	High
5	Effusion	J90	Moderate
6	Emphysema	J43.9	Moderate
7	Fibrosis	J84.10	Moderate
8	Hernia	K44.9	Low
9	Infiltration	R09.89	Moderate
10	Mass	R91.8	Critical
11	Nodule	R91.1	High
12	Pleural Thickening	J92.9	Low
13	Pneumonia	J18.9	High
14	Pneumothorax	J93.9	Critical

🏗️ Architecture

┌─────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Input       │────▶│ Preprocess   │────▶│ DenseNet121  │────▶│ Grad-CAM     │
│  Chest X-Ray │     │ CLAHE+Norm   │     │ Classification│     │ Attention    │
│  (JPEG/PNG)  │     │ (224×224×3)  │     │ (14 classes)  │     │ Maps         │
└─────────────┘     └──────────────┘     └──────────────┘     └──────┬───────┘
                                                                      │
                    ┌──────────────┐     ┌──────────────┐            │
                    │  Clinical    │◀────│  Risk        │◀───────────┘
                    │  Report      │     │  Assessment  │
                    │  (ICD-10)    │     │  (Triage)    │
                    └──────────────┘     └──────────────┘

Tech Stack

Component	Technology	Purpose
ML Backbone	TensorFlow + DenseNet121	Feature extraction & classification
Explainability	Grad-CAM	Visual attention mapping
Image Processing	OpenCV + PIL	CLAHE enhancement, preprocessing
Backend API	FastAPI + Uvicorn	REST API + async processing
Frontend	HTML5 + CSS3 + JavaScript	Interactive analysis dashboard
Visualization	Chart.js	Confidence charts & quality radar
Computation	NumPy + SciPy	Numerical operations

🚀 Quick Start

Prerequisites

• Python 3.10+
• pip package manager

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/ai-medscan.git
cd ai-medscan

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate        # Linux/macOS
# OR
.\venv\Scripts\activate         # Windows

# 3. Install dependencies
cd backend
pip install -r requirements.txt

# 4. Start the server
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Access

• Web UI: http://localhost:8000
• API Docs: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• Health Check: http://localhost:8000/api/health

📡 API Documentation

Endpoints

Method	Endpoint	Description
POST	/api/analyze	Analyze a medical image
GET	/api/health	System health check
GET	/api/model/info	Model architecture info
GET	/api/pathologies	List all detectable pathologies
GET	/api/analysis/{id}	Retrieve previous analysis
GET	/api/stats	Platform statistics

Example: Analyze Image

curl -X POST "http://localhost:8000/api/analyze?enhance=true&colormap=jet" \
  -H "accept: application/json" \
  -F "file=@chest_xray.jpg"

Response Structure

{
  "analysis_id": "MEDSCAN-A1B2C3D4E5F6",
  "status": "completed",
  "processing_time_ms": 1245.3,
  "quality_assessment": {
    "quality_score": 82.5,
    "quality_grade": "Good"
  },
  "predictions": {
    "findings": [...],
    "assessment": {
      "risk_score": 45.2,
      "status": "BORDERLINE - Follow-up Suggested",
      "status_code": "borderline"
    }
  },
  "heatmaps": {
    "primary": {
      "overlay": "<base64>",
      "raw": "<base64>",
      "contours": "<base64>"
    }
  },
  "clinical_report": {...}
}

📚 Research References

1. CheXNet: Rajpurkar et al., "Radiologist-Level Pneumonia Detection on Chest X-Rays with Deep Learning" (arXiv:1711.05225, 2017)
2. Grad-CAM: Selvaraju et al., "Visual Explanations from Deep Networks via Gradient-based Localization" (ICCV 2017)
3. CheXpert: Irvin et al., "A Large Chest Radiograph Dataset with Uncertainty Labels" (AAAI 2019)
4. DenseNet: Huang et al., "Densely Connected Convolutional Networks" (CVPR 2017)

🎓 Training Pipeline

Download Real NIH Data & Train

cd backend

# 1. Download real NIH Chest X-Ray14 images (via MedMNIST)
python -m app.training.download_real_data --output_dir ./real_data --max_images 3000

# 2. Train DenseNet121 with two-phase strategy
python -m app.training.train_model --data_dir ./real_data --epochs 15 --batch_size 16 --loss focal

# 3. Model auto-deploys to trained_models/best_model.keras

Training Results (Real NIH Data)

Metric	Value
Dataset	4,200 real NIH chest X-rays
Best Val AUC	0.664
Test Mean AUROC	0.609
Top Pathology	Cardiomegaly (0.789 AUROC)
Training Time	~6 hours (CPU)

📁 Project Structure

ai-medscan/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py                    # FastAPI application
│   │   ├── models/
│   │   │   └── classifier.py          # DenseNet121 classifier
│   │   ├── services/
│   │   │   ├── gradcam.py             # Grad-CAM implementation
│   │   │   └── report_generator.py    # Clinical report generation
│   │   ├── utils/
│   │   │   └── preprocessing.py       # Image preprocessing pipeline
│   │   └── training/
│   │       ├── train_model.py         # DenseNet121 training engine
│   │       ├── dataset.py             # Multi-format dataset loader
│   │       ├── evaluate.py            # AUROC evaluation
│   │       ├── prepare_data.py        # Synthetic data generator
│   │       └── download_real_data.py  # Real NIH data downloader
│   ├── trained_models/                # Trained model weights (.keras)
│   ├── real_data/                     # Real NIH training images
│   └── requirements.txt
├── frontend/
│   ├── index.html                     # Main application page
│   ├── css/
│   │   └── styles.css                 # Medical-grade dark UI
│   └── js/
│       └── app.js                     # Frontend application logic
├── sample_images/                     # Sample chest X-rays
├── README.md
└── .gitignore

⚠️ Disclaimer

This application is for research and educational purposes ONLY. It has NOT been validated for clinical use and should NOT be used for actual medical diagnosis or treatment decisions. Always consult qualified healthcare professionals for medical advice. The AI model may produce false positives or false negatives.

📄 License

MIT License — See LICENSE for details.

---

Built with ❤️ for advancing healthcare AI

⬆ Back to Top